chore(apps): make the packages publishable and keep them out of releases

The apps packages were npm workspaces of the repo root, whose only other job is
the semantic-release run in release.yml and prerelease-alpha.yml. Its npm ci
therefore installed every app dependency, cloudflared's 38 MB binary included.
They get their own workspace root at apps/ instead, so the release install drops
from ~490 to ~310 packages and local development is one npm install in apps/.

Publishing fixes:

- Both packages declared 0.0.1-alpha.1, already on npm with different contents
  (the newest published is alpha.7). They move to 0.0.1-alpha.8.
- files: ["dist"] with no build hook shipped an empty package from a clean
  checkout; both gain prepack.
- Neither declared a license or a repository.
- create-tolgee-app pinned an SDK release that does not export selfRegisterApp
  or applyTolgeeTheme, so the scaffold only failed later, as TypeScript errors.
  resolveSdk now refuses the registry path outright and names what to do;
  PUBLISHED_SDK_RELEASED is the flag to flip once the SDK is published.
- create-tolgee-app's .gitignore did not cover node_modules.

Dependency fixes:

- cloudflared is a local-dev convenience whose postinstall downloads an
  unpinned, unverified binary; it moves to devDependencies and the tunnel
  script now degrades to a message when it is absent instead of crashing.
- @tginternal/client was a direct dependency of the template and keys-showcase
  but imported by neither.
- express 4 -> 5, @clack/prompts 0.11 -> 1, and @types/node aligned with the
  Node versions the packages actually claim.

Finally, nothing in CI built, typechecked or tested any of this, which is how
all of the above got in. test.yml gains an apps-check job that installs the
workspace, builds the SDK, typechecks all three packages and runs their tests.

Author: JanCizmar

.github/workflows/test.yml

@@ -376,6 +376,29 @@ jobs:
         run: npm test
         working-directory: ./webapp
 
+  apps-check:
+    name: Apps workspace check 🧩
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
+        with:
+          java: "false"
+
+      # --ignore-scripts keeps cloudflared's postinstall from downloading its
+      # ~38 MB binary; it is a dev-tunnel convenience nothing here runs.
+      - name: Install apps dependencies
+        run: npm ci --ignore-scripts
+        working-directory: ./apps
+
+      # Builds the SDK first — the generator and the example apps typecheck
+      # against its dist/, not its sources.
+      - name: Build, typecheck and test the apps workspace
+        run: npm run check
+        working-directory: ./apps
+
   schema-check:
     name: Schema Check 📋
     needs: [backend-build]
@@ -651,6 +674,7 @@ jobs:
       - frontend-code-check
       - frontend-test
       - frontend-test-without-ee
+      - apps-check
       - schema-check
       - migration-check
       - data-cy-check
@@ -697,6 +721,10 @@ jobs:
             failed_jobs+=("frontend-test-without-ee")
           fi
 
+          if [[ "${{ needs.apps-check.result }}" != "success" ]]; then
+            failed_jobs+=("apps-check")
+          fi
+
           if [[ "${{ needs.schema-check.result }}" != "success" ]]; then
             failed_jobs+=("schema-check")
           fi

apps/.gitignore

@@ -0,0 +1 @@
+node_modules

apps/create-tolgee-app/.gitignore

@@ -1 +1,3 @@
+node_modules
 dist
+*.tsbuildinfo

apps/create-tolgee-app/README.md

@@ -8,12 +8,13 @@ to your Tolgee instance.
 npx create-tolgee-app my-app
 ```
 
-> **Status: alpha, not published.** Inside this repository the package is
-> resolved through npm workspaces, so `npm install` at the repo root links it
-> (and `@tolgee/apps-sdk`) locally. `npx create-tolgee-app` from a clean machine
-> does not work yet. Run from a checkout, it scaffolds anywhere on disk and
-> wires the generated app to the SDK sources — see *Which SDK the generated app
-> gets*.
+> **Status: alpha, needs a checkout.** Inside this repository the package is
+> resolved through npm workspaces, so `npm install` in `apps/` links it (and
+> `@tolgee/apps-sdk`) locally. `npx create-tolgee-app` from a clean machine
+> **exits with an error**: no `@tolgee/apps-sdk` on npm carries the API the
+> template imports, so the scaffold could only produce a project that does not
+> compile. Run from a checkout, it scaffolds anywhere on disk and wires the
+> generated app to the SDK sources — see *Which SDK the generated app gets*.
 
 ## What it generates
 
@@ -89,14 +90,21 @@ summary and again in the next steps.
 
 | Mode | What the dependency becomes |
 | --- | --- |
-| `auto` (default) | `*` when the app is generated into this repo's npm workspaces (they link the SDK already), otherwise `file:<abs path>/apps/tolgee-apps-sdk`, and an exact published version when the CLI has no SDK sources next to it |
+| `auto` (default) | `*` when the app is generated into the `apps/` npm workspaces (they link the SDK already), otherwise `file:<abs path>/apps/tolgee-apps-sdk` |
 | `local` | as `auto`, but fails instead of falling back to the registry |
 | `published` | an exact published version, never a range |
 
+**`published` currently refuses to run.** Every `@tolgee/apps-sdk` release on npm
+predates `selfRegisterApp` and `applyTolgeeTheme`, which the template imports, so
+the generator exits with that sentence rather than handing you a project full of
+missing-export errors. `PUBLISHED_SDK_RELEASED` in `src/registry.ts` is the flag
+to flip — together with `PUBLISHED_SDK_VERSION` — once the SDK is on npm. `auto`
+hits the same wall only when the CLI has no SDK sources next to it.
+
 A `file:` dependency uses the SDK's build output, so the SDK has to be built:
 
 ```bash
-npm run build --workspace @tolgee/apps-sdk
+npm run build --workspace @tolgee/apps-sdk   # from apps/
 ```
 
 The generator does not build it for you, but it does check and says so in the
@@ -111,6 +119,11 @@ Cloudflare quick tunnel, publishes the public URLs to `.tolgee-dev/tunnel.json`,
 and the server registers the app with *those* URLs. `TOLGEE_DEV_TUNNEL=none`, or
 a localhost `TOLGEE_URL`, keeps everything local.
 
+`cloudflared` is a **dev dependency** of the generated app — it downloads a
+platform binary on install, which no deployment of the app needs. A production
+install (`npm ci --omit=dev`) simply has no tunnel; the script says so and lets
+Vite and the app server carry on.
+
 ## Non-interactive use
 
 ```bash
@@ -133,6 +146,9 @@ them there to run two apps side by side.
 
 ## Developing this package
 
+It is part of the `apps/` npm workspace, so dependencies come from
+`npm install` there, not at the repo root.
+
 ```bash
 npm run dev        # run the CLI from source (tsx)
 npm run typecheck

apps/create-tolgee-app/package.json

@@ -1,7 +1,17 @@
 {
   "name": "create-tolgee-app",
-  "version": "0.0.1-alpha.1",
+  "version": "0.0.1-alpha.8",
   "description": "Scaffold a Tolgee App — a Vite + React dashboard page with a manifest server — in one command.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tolgee/tolgee-platform.git",
+    "directory": "apps/create-tolgee-app"
+  },
+  "homepage": "https://github.com/tolgee/tolgee-platform/tree/main/apps/create-tolgee-app#readme",
+  "bugs": {
+    "url": "https://github.com/tolgee/tolgee-platform/issues"
+  },
   "type": "module",
   "bin": {
     "create-tolgee-app": "./dist/index.js"
@@ -12,21 +22,25 @@
   ],
   "scripts": {
     "build": "tsup",
+    "prepack": "npm run build",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
+    "@clack/prompts": "^1.7.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@tolgee/apps-sdk": "*",
-    "@types/node": "^24.12.3",
+    "@types/node": "^20.19.9",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "~6.0.2"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.12.0"
   }
 }

apps/create-tolgee-app/src/index.ts

@@ -289,7 +289,9 @@ const nextSteps = (answers: Answers): string[] => {
   return steps
 }
 
-main().catch((err) => {
-  console.error(err)
+main().catch((err: unknown) => {
+  // These are the generator's own "you cannot get there from here" messages —
+  // a stack trace would only bury them.
+  log.error(err instanceof Error ? err.message : String(err))
   process.exit(1)
 })

apps/create-tolgee-app/src/registry.ts

@@ -54,12 +54,24 @@ export type SdkMode = 'auto' | 'local' | 'published'
 export const SDK_MODES: SdkMode[] = ['auto', 'local', 'published']
 
 /**
- * Used only when the generator cannot see the SDK sources. It is an exact
- * version on purpose: the SDK's npm `latest` tag points at an early alpha that
- * predates most of the API, so any range (`*`, `^…`) resolves to a package the
- * generated app does not compile against.
+ * Version the template is written against, used when the generator cannot see
+ * the SDK sources. It is an exact version on purpose: the SDK's npm `latest` tag
+ * points at an early alpha that predates most of the API, so any range (`*`,
+ * `^…`) resolves to a package the generated app does not compile against.
  */
-export const PUBLISHED_SDK_VERSION = '0.0.1-alpha.1'
+export const PUBLISHED_SDK_VERSION = '0.0.1-alpha.8'
+
+/**
+ * RELEASE MARKER — flip to `true` in the same commit that publishes
+ * `PUBLISHED_SDK_VERSION` to npm, and keep the two in lockstep afterwards.
+ *
+ * While it is `false`, `resolveSdk` refuses to scaffold against the registry:
+ * every version published so far predates `selfRegisterApp` and
+ * `applyTolgeeTheme`, which the template imports, so the generated app would
+ * fail to typecheck with a wall of missing-export errors instead of one
+ * sentence naming the cause.
+ */
+export const PUBLISHED_SDK_RELEASED = false
 
 export const DEFAULT_TOLGEE_URL = 'http://localhost:8718'
 export const DEFAULT_VITE_PORT = 5180