@jtl-software/create-cloud-app 0.6.0 → 0.8.0

package/README.md

@@ -40,6 +40,14 @@ npm run register
 npm run dev
 ```
 
+Pass `--legacy` to scaffold the backend for the legacy Ory M2M flow instead of the Zitadel service account (compat testing only, node backend only):
+
+```bash
+npm create @jtl-software/cloud-app@latest -- --legacy
+```
+
+`npm run register` then writes the app's Ory client credentials, and the backend mints its M2M token against the Ory auth host. Everything else is unchanged: the backend still verifies the incoming app token and reads the tenant id from it.
+
 The generated project includes:
 
 - A monorepo wired up with [Turborepo](https://turbo.build/)
@@ -65,7 +73,7 @@ Flags:
 | Flag                                        | Description                                                                                                                                                                                          |
 | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--api-host <url>`                          | API host. Default `https://api.jtl-cloud.com`.                                                                                                                                                       |
-| `--auth-host <url>`                         | OAuth host. Default `https://auth.jtl-cloud.com`. The CLI picks the matching client ID for the known prod/QA/dev hosts.                                                                              |
+| `--auth-host <url>`                         | OAuth host. Default `https://id.jtl-cloud.com`. The CLI picks the matching client ID for the known prod/QA/dev hosts.                                                                                |
 | `--hub-host <url>`                          | Hub host (used in printed links). Default `https://hub.jtl-cloud.com`.                                                                                                                               |
 | `--client-id <id>`                          | Override the OAuth client ID. Only needed for custom auth hosts.                                                                                                                                     |
 | `--scope <scope>`                           | OAuth scope. Default `openid offline_access`.                                                                                                                                                        |

package/dist/index.js

@@ -703,7 +703,8 @@ function readScaffoldStack(root) {
     if (meta && typeof meta === "object") {
       return {
         backend: typeof meta.backend === "string" ? meta.backend : null,
-        frontend: typeof meta.frontend === "string" ? meta.frontend : null
+        frontend: typeof meta.frontend === "string" ? meta.frontend : null,
+        legacy: meta.legacy === true
       };
     }
   } catch {
@@ -717,13 +718,14 @@ function environmentFromApi(api) {
   if (h.includes("api.jtl-cloud.com")) return "prod";
   return "other";
 }
-function writeFrontendPublicClient(root, authIssuer, publicClientId) {
+function writeFrontendPublicClient(root, authIssuer, publicClientId, apiBase) {
   const frontendDir = detectFrontend(root);
   if (!frontendDir) return null;
   const envFile = path2.join(frontendDir, ".env");
   upsertEnv(envFile, {
     VITE_JTL_CLIENT_ID: publicClientId,
-    VITE_JTL_ISSUER: authIssuer
+    VITE_JTL_ISSUER: authIssuer,
+    ...apiBase ? { VITE_JTL_API_BASE: apiBase.replace(/\/$/, "") } : {}
   });
   return envFile;
 }
@@ -763,19 +765,18 @@ function readExistingCredentials(backend) {
 function authBaseFromApi(apiHost) {
   return apiHost.replace(/:\/\/api\./, "://auth.").replace(/\/$/, "");
 }
-function writeBackendCredentials(backend, clientId, clientSecret, issuer, apiBase, appId) {
-  const hosts = apiBase ? {
-    JTL_API_BASE: apiBase.replace(/\/$/, ""),
-    JTL_AUTH_BASE: authBaseFromApi(apiBase)
-  } : {};
+function writeBackendCredentials(backend, clientId, clientSecret, issuer, apiBase, appId, authBase) {
+  const hosts = apiBase ? { JTL_API_BASE: apiBase.replace(/\/$/, "") } : {};
   if (backend.kind === "node") {
-    upsertEnv(backend.envFile, {
+    const updates = {
       CLIENT_ID: clientId,
-      CLIENT_SECRET: clientSecret,
-      ...issuer ? { JTL_ISSUER: issuer } : {},
-      ...appId ? { JTL_APP_ID: appId } : {},
-      ...hosts
-    });
+      CLIENT_SECRET: clientSecret
+    };
+    if (issuer) updates.JTL_ISSUER = issuer;
+    if (appId) updates.JTL_APP_ID = appId;
+    Object.assign(updates, hosts);
+    if (authBase) updates.JTL_AUTH_BASE = authBase.replace(/\/$/, "");
+    upsertEnv(backend.envFile, updates);
     return backend.envFile;
   }
   let settings = {};
@@ -967,7 +968,8 @@ async function listTenantApps(apiBaseUrl, jwt, tenantId, appServicePath = "app-s
       clientId: entry.clientId,
       provisioningStatus: entry.activeVersion?.provisioningStatus,
       isInstalled: entry.isInstalled,
-      publicClientId: entry.credentials?.publicClient?.clientId
+      publicClientId: entry.credentials?.publicClient?.clientId,
+      serviceAccountClientId: entry.credentials?.serviceAccount?.clientId
     };
   }).filter((a) => a !== null);
 }
@@ -1028,34 +1030,53 @@ async function provisionApp(apiBaseUrl, jwt, tenantId, appId, appServicePath = "
       `provision response missing clientId or clientSecret: ${JSON.stringify(provisioned)}`
     );
   }
+  const sa = provisioned.credentials?.serviceAccount;
   return {
     clientId,
     clientSecret,
-    publicClientId: provisioned.credentials?.publicClient?.clientId
+    publicClientId: provisioned.credentials?.publicClient?.clientId,
+    serviceAccount: sa?.clientId && sa.clientSecret ? { clientId: sa.clientId, clientSecret: sa.clientSecret } : void 0
   };
 }
-async function applyProvisionResult(root, backend, opts, tenant, appId, provisioned, isInstalled) {
+function resolveBackendAuth(provisioned, legacy = false) {
+  if (legacy) {
+    return {
+      clientId: provisioned.clientId,
+      clientSecret: provisioned.clientSecret
+    };
+  }
+  const sa = provisioned.serviceAccount;
+  if (!sa) {
+    throw new Error(
+      "Provision response did not include a service account; the backend cannot authenticate."
+    );
+  }
+  return { clientId: sa.clientId, clientSecret: sa.clientSecret };
+}
+async function applyProvisionResult(root, backend, opts, tenant, appId, provisioned, isInstalled, legacy) {
   if (provisioned.publicClientId) {
     const written = writeFrontendPublicClient(
       root,
       opts.auth,
-      provisioned.publicClientId
+      provisioned.publicClientId,
+      opts.api
     );
     if (written) {
       p2.log.success(
-        `Wrote VITE_JTL_CLIENT_ID/VITE_JTL_ISSUER to ${pc2.cyan(path2.relative(root, written))}.`
+        `Wrote VITE_JTL_CLIENT_ID/VITE_JTL_ISSUER/VITE_JTL_API_BASE to ${pc2.cyan(path2.relative(root, written))}.`
       );
     }
   }
   writeVerifyDemoEnv(root, backend);
   if (backend) {
+    const auth = resolveBackendAuth(provisioned, legacy);
     await persistCredentials(
       backend,
-      provisioned.clientId,
-      provisioned.clientSecret,
+      auth.clientId,
+      auth.clientSecret,
       root,
       opts,
-      { hub: opts.hub, tenantSlug: tenant.slug, appId, isInstalled }
+      { hub: opts.hub, tenantSlug: tenant.slug, appId, isInstalled, legacy }
     );
     return;
   }
@@ -1107,7 +1128,8 @@ async function persistCredentials(backend, clientId, clientSecret, root, opts, c
     clientSecret,
     opts.auth,
     opts.api,
-    context.appId
+    context.appId,
+    context.legacy ? authBaseFromApi(opts.api) : void 0
   );
   printHubLink(
     context.hub,
@@ -1155,11 +1177,18 @@ async function register(argv = [], runOpts = {}) {
   const manifest = readManifest(path2.join(root, "app.json"));
   const summary = summarizeManifest(manifest);
   const stack = readScaffoldStack(root);
+  const legacy = stack?.legacy ?? false;
   const auth = manifest.authentication;
+  if (!legacy && backend && !auth?.serviceAccount) {
+    bail(
+      "This project has a backend but app.json declares no authentication.serviceAccount. Add it (or re-scaffold) before registering, so the backend gets a Zitadel service account."
+    );
+  }
   const hasFrontend = stack ? !!stack.frontend : !!auth?.publicClient;
   const hasBackend = stack ? !!stack.backend : !!auth?.serviceAccount;
   const registerTelemetry = {
     environment: environmentFromApi(opts.api),
+    legacy,
     has_frontend: hasFrontend,
     has_backend: hasBackend,
     backend_tech: stack?.backend ?? (hasBackend ? "unknown" : "none"),
@@ -1168,7 +1197,7 @@ async function register(argv = [], runOpts = {}) {
   };
   for (; ; ) {
     const identityJwt = jwt;
-    const apiJwt = apiTokenFor(jwt);
+    const apiJwt = jwt;
     spinner4.start("Fetching tenants");
     let tenants;
     try {
@@ -1257,9 +1286,9 @@ async function register(argv = [], runOpts = {}) {
       }
       if (existing.provisioningStatus === "DRAFT") {
         spinner4.start("Provisioning app");
-        let provisioned;
+        let provisioned2;
         try {
-          provisioned = await provisionApp(
+          provisioned2 = await provisionApp(
             opts.api,
             apiJwt,
             tenant.id,
@@ -1277,8 +1306,9 @@ async function register(argv = [], runOpts = {}) {
           opts,
           tenant,
           existing.id,
-          provisioned,
-          existing.isInstalled ?? false
+          provisioned2,
+          existing.isInstalled ?? false,
+          legacy
         );
         return { ...registerTelemetry, is_new_app: false };
       }
@@ -1314,6 +1344,18 @@ async function register(argv = [], runOpts = {}) {
           );
           return { ...registerTelemetry, is_new_app: false };
         }
+        if (!legacy && localCreds.clientId !== existing.serviceAccountClientId) {
+          p2.outro(
+            pc2.yellow(
+              `Manifest updated, but your ${labels.pair} in ${pc2.cyan(path2.relative(root, envFile))} need to be migrated to the new authentication platform. Go to the Partner Portal (${pc2.cyan(opts.partner)}) and follow the migration instructions to get your new ${labels.pair}.`
+            )
+          );
+          return {
+            ...registerTelemetry,
+            is_new_app: false,
+            credential_migration_required: true
+          };
+        }
         p2.outro(
           pc2.green(
             `Manifest updated. Existing ${labels.pair} in ${pc2.cyan(path2.relative(root, envFile))} kept as-is.`
@@ -1340,17 +1382,15 @@ async function register(argv = [], runOpts = {}) {
       bail(err.message);
     }
     spinner4.start("Provisioning app");
-    let clientId;
-    let clientSecret;
-    let publicClientId;
+    let provisioned;
     try {
-      ({ clientId, clientSecret, publicClientId } = await provisionApp(
+      provisioned = await provisionApp(
         opts.api,
         apiJwt,
         tenant.id,
         appId,
         opts.appServicePath
-      ));
+      );
       spinner4.stop("Provisioned");
     } catch (err) {
       spinner4.stop("Failed to provision app");
@@ -1362,8 +1402,9 @@ async function register(argv = [], runOpts = {}) {
       opts,
       tenant,
       appId,
-      { clientId, clientSecret, publicClientId },
-      false
+      provisioned,
+      false,
+      legacy
     );
     return { ...registerTelemetry, is_new_app: true };
   }
@@ -1544,7 +1585,6 @@ async function listing(argv = [], runOpts = {}) {
     bail(err.message);
   }
   const identityJwt = jwt;
-  jwt = apiTokenFor(jwt);
   spinner4.start("Fetching tenants");
   let tenants;
   try {
@@ -1664,6 +1704,17 @@ function templateTech(template) {
   );
   return m?.[1] ?? template.packageName;
 }
+var NODE_TOKEN_BLOCK_ZITADEL = `// The service account mints its token at the issuer's token endpoint via the client_credentials
+// grant. Zitadel rejects a client_credentials request that asks for no scope.
+const TOKEN_URL = \`\${JTL_ISSUER}/oauth/v2/token\`;
+const TOKEN_SCOPE = 'openid';`;
+var NODE_TOKEN_BLOCK_LEGACY = `// Legacy Ory client-credentials M2M: mint the token at the Ory auth host. \`npm run register\` writes
+// JTL_AUTH_BASE for a --legacy app; the fallback is production. No scope is requested.
+const AUTH_BASE = (process.env.JTL_AUTH_BASE || 'https://auth.jtl-cloud.com').replace(/\\/$/, '');
+const TOKEN_URL = \`\${AUTH_BASE}/oauth2/token\`;
+const TOKEN_SCOPE = '';`;
+var NODE_ENV_EXAMPLE_ZITADEL = "# The service account mints its token at JTL_ISSUER + /oauth/v2/token; no extra config needed.";
+var NODE_ENV_EXAMPLE_LEGACY = "# Legacy Ory M2M: the backend mints its token at JTL_AUTH_BASE + /oauth2/token; `npm run register` writes JTL_AUTH_BASE.";
 function toPascalCase(kebab) {
   return kebab.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
@@ -1772,7 +1823,7 @@ function applyManifestAuthentication(appJsonPath, opts) {
       postLogoutRedirectUris: [`${origin}/`]
     };
   }
-  if (backend) {
+  if (backend && !opts.legacy) {
     authentication.serviceAccount = {
       clientCredentials: true,
       description: `${opts.appName} backend service account`
@@ -1801,8 +1852,14 @@ async function scaffold({
   shared,
   frontendPort = DEFAULT_FRONTEND_PORT,
   authentication,
+  legacy = false,
   targetDir: customTargetDir
 }) {
+  if (legacy && backend && templateTech(backend) !== "node") {
+    throw new Error(
+      `--legacy is currently only supported for the node backend (got "${templateTech(backend)}")`
+    );
+  }
   const targetDir = customTargetDir ?? path4.resolve(process.cwd(), appName);
   const baseReplacements = buildPlaceholders({
     appName,
@@ -1835,12 +1892,37 @@ async function scaffold({
       backend.meta.type,
       appName
     );
+    if (legacy) {
+      const backendIndex = path4.join(backendDest, "src", "index.ts");
+      const src = fs4.readFileSync(backendIndex, "utf-8");
+      if (!src.includes(NODE_TOKEN_BLOCK_ZITADEL)) {
+        throw new Error(
+          "node backend token block not found; the --legacy swap is out of date with the template"
+        );
+      }
+      fs4.writeFileSync(
+        backendIndex,
+        src.replace(NODE_TOKEN_BLOCK_ZITADEL, NODE_TOKEN_BLOCK_LEGACY)
+      );
+      const envExample = path4.join(backendDest, ".env.example");
+      const env = fs4.readFileSync(envExample, "utf-8");
+      if (!env.includes(NODE_ENV_EXAMPLE_ZITADEL)) {
+        throw new Error(
+          "node backend .env.example token line not found; the --legacy swap is out of date with the template"
+        );
+      }
+      fs4.writeFileSync(
+        envExample,
+        env.replace(NODE_ENV_EXAMPLE_ZITADEL, NODE_ENV_EXAMPLE_LEGACY)
+      );
+    }
   }
   if (authentication) {
     applyManifestAuthentication(path4.join(targetDir, "app.json"), {
       appName,
       frontendPort,
-      authentication
+      authentication,
+      legacy
     });
   }
   const runtimeVersions = backend?.meta.runtimeVersions ?? {};
@@ -1872,10 +1954,12 @@ async function scaffold({
       turbo: "^2.5.5"
     },
     // The stack the developer picked, recorded so `register` can report it in telemetry without
-    // guessing from the generated files.
+    // guessing from the generated files. `legacy` tells register to persist the Ory M2M client
+    // instead of the Zitadel service account.
     jtlCloudApp: {
       backend: backend ? templateTech(backend) : null,
-      frontend: frontend ? templateTech(frontend) : null
+      frontend: frontend ? templateTech(frontend) : null,
+      legacy
     }
   };
   fs4.writeFileSync(
@@ -1922,7 +2006,7 @@ import os2 from "os";
 import path6 from "path";
 import { PostHog } from "posthog-node";
 var TOKEN = "phc_SkFAxTIa4RUQxotci1Ftdw7xefZK2Ax0LEIGcl8zuD2";
-var CLI_VERSION = "0.6.0";
+var CLI_VERSION = "0.8.0";
 var client = TOKEN ? new PostHog(TOKEN, { host: "https://e.jtl-cloud.com" }) : null;
 function telemetryDisabledByEnv() {
   const dnt = process.env.DO_NOT_TRACK;
@@ -1991,11 +2075,11 @@ async function shutdownPostHog() {
 
 // src/index.ts
 var NONE = "__none__";
-function scaffoldChoice(backend, frontend, next) {
+function scaffoldChoice(backend, frontend, legacy) {
   const hasBackend = Boolean(backend);
   const hasFrontend = Boolean(frontend);
   return {
-    next,
+    legacy,
     backend_tech: hasBackend ? templateTech(backend) : "none",
     frontend_tech: hasFrontend ? templateTech(frontend) : "none",
     has_backend: hasBackend,
@@ -2020,8 +2104,17 @@ function cancelScaffold() {
   p4.cancel("Cancelled.");
   process.exit(0);
 }
-async function runNextScaffold(backends, frontends, shared) {
-  const cancelOpts = { onCancel: cancelScaffold };
+async function runScaffold() {
+  console.log();
+  p4.intro(pc4.bgCyan(pc4.black(" create-cloud-app ")));
+  const templates = discoverTemplates();
+  const backends = getTemplatesByType(templates, "backend");
+  const frontends = getTemplatesByType(templates, "frontend");
+  const shared = templates.find((t) => t.meta.type === "shared");
+  if (!backends.length || !frontends.length || !shared) {
+    p4.cancel("No templates found. Ensure template packages are installed.");
+    process.exit(1);
+  }
   const answers = await p4.group(
     {
       appName: () => p4.text({
@@ -2043,7 +2136,7 @@ async function runNextScaffold(backends, frontends, shared) {
         options: halfSelectOptions(backends, "no backend")
       })
     },
-    cancelOpts
+    { onCancel: cancelScaffold }
   );
   const selectedFrontend = frontends.find(
     (t) => t.packageName === answers.frontend
@@ -2055,6 +2148,11 @@ async function runNextScaffold(backends, frontends, shared) {
     p4.cancel("Pick at least a frontend or a backend.");
     process.exit(1);
   }
+  const legacy = process.argv.includes("--legacy");
+  if (legacy && selectedBackend && templateTech(selectedBackend) !== "node") {
+    p4.cancel("--legacy is only supported for the node backend.");
+    process.exit(1);
+  }
   const s = p4.spinner();
   s.start("Scaffolding project");
   const frontendPort = selectedFrontend ? await pickFrontendPort() : void 0;
@@ -2068,7 +2166,8 @@ async function runNextScaffold(backends, frontends, shared) {
     authentication: {
       frontend: Boolean(selectedFrontend),
       backend: Boolean(selectedBackend)
-    }
+    },
+    legacy
   });
   s.stop("Project scaffolded");
   if (selectedFrontend) {
@@ -2077,74 +2176,15 @@ async function runNextScaffold(backends, frontends, shared) {
       "Frontend login"
     );
   }
-  printNextSteps(answers.appName);
-  p4.outro(pc4.green("Done! Happy building."));
-  return scaffoldChoice(selectedBackend, selectedFrontend, true);
-}
-async function runScaffold() {
-  console.log();
-  p4.intro(pc4.bgCyan(pc4.black(" create-cloud-app ")));
-  const templates = discoverTemplates();
-  const backends = getTemplatesByType(templates, "backend");
-  const frontends = getTemplatesByType(templates, "frontend");
-  const shared = templates.find((t) => t.meta.type === "shared");
-  if (!backends.length || !frontends.length || !shared) {
-    p4.cancel("No templates found. Ensure template packages are installed.");
-    process.exit(1);
-  }
-  if (process.argv.includes("--next")) {
-    return runNextScaffold(backends, frontends, shared);
+  if (legacy && selectedBackend) {
+    p4.note(
+      "The backend is scaffolded for the legacy Ory M2M flow. `npm run register` will write its Ory client credentials.",
+      "Legacy backend"
+    );
   }
-  const answers = await p4.group(
-    {
-      appName: () => p4.text({
-        message: "App name",
-        placeholder: "my-jtl-app",
-        validate: (value) => {
-          if (!value) return "App name is required";
-          if (!/^[a-z0-9-]+$/.test(value))
-            return "Use lowercase letters, numbers, and hyphens only";
-        }
-      }),
-      description: () => p4.text({
-        message: "Description",
-        placeholder: "A JTL Platform app"
-      }),
-      backend: () => p4.select({
-        message: "Backend",
-        options: templateSelectOptions(backends)
-      }),
-      frontend: () => p4.select({
-        message: "Frontend",
-        options: templateSelectOptions(frontends)
-      })
-    },
-    {
-      onCancel: () => {
-        p4.cancel("Cancelled.");
-        process.exit(0);
-      }
-    }
-  );
-  const selectedBackend = templates.find(
-    (t) => t.packageName === answers.backend
-  );
-  const selectedFrontend = templates.find(
-    (t) => t.packageName === answers.frontend
-  );
-  const s = p4.spinner();
-  s.start("Scaffolding project");
-  await scaffold({
-    appName: answers.appName,
-    description: answers.description || "A JTL Platform app",
-    backend: selectedBackend,
-    frontend: selectedFrontend,
-    shared
-  });
-  s.stop("Project scaffolded");
   printNextSteps(answers.appName);
   p4.outro(pc4.green("Done! Happy building."));
-  return scaffoldChoice(selectedBackend, selectedFrontend, false);
+  return scaffoldChoice(selectedBackend, selectedFrontend, legacy);
 }
 function printNextSteps(appName) {
   p4.note(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtl-software/create-cloud-app",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "CLI tool for scaffolding JTL Platform cloud apps",
   "bin": {
@@ -18,19 +18,19 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@jtl-software/cloud-app-template-backend-dotnet": "0.0.13",
-    "@jtl-software/cloud-app-template-backend-node": "0.2.0",
-    "@jtl-software/cloud-app-template-backend-php": "0.1.3",
-    "@jtl-software/cloud-app-template-frontend-react": "0.2.1",
-    "@jtl-software/cloud-app-template-shared": "0.1.3",
+    "@jtl-software/cloud-app-template-backend-dotnet": "0.1.0",
+    "@jtl-software/cloud-app-template-backend-node": "0.3.0",
+    "@jtl-software/cloud-app-template-backend-php": "0.2.0",
+    "@jtl-software/cloud-app-template-frontend-react": "0.3.1",
+    "@jtl-software/cloud-app-template-shared": "0.2.0",
     "picocolors": "^1.1.1",
-    "posthog-node": "^5.49.1"
+    "posthog-node": "^5.51.6"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "msw": "^2.15.0",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.13",
     "typescript": "^6.0.3"
   },
   "publishConfig": {