@jtl-software/create-cloud-app 0.0.23 → 0.0.25

package/README.md

@@ -1,42 +1,148 @@
 # @jtl-software/create-cloud-app
 
-Scaffold a [JTL Platform](https://www.jtl-software.com/) cloud app in seconds.
+CLI for [JTL Platform](https://www.jtl-software.com/) cloud apps. Scaffolds a new app project and registers/updates its manifest against the cloud.
 
 ## Requirements
 
 Node.js **24** (current LTS) or newer. The scaffolded project sets the same floor via `engines.node`.
 
-## Quick start
+## Commands
+
+The CLI has two entry points:
+
+- The default invocation (no arguments) scaffolds a new project.
+- `register` registers or updates a manifest against the JTL Cloud.
+
+### `npm create @jtl-software/cloud-app@latest`
+
+Scaffold a new app interactively.
 
 ```bash
 npm create @jtl-software/cloud-app@latest
 ```
 
-The CLI prompts you for:
+You'll be prompted for:
 
-- **App name** — directory name, package name, and manifest identifier
-- **Description** — placed in the app manifest
-- **Backend** — Node.js (Express + TypeScript) or .NET (ASP.NET Core + FastEndpoints)
-- **Frontend** — React (Vite + Tailwind + JTL Platform UI)
+- **App name**: directory name, package name, and manifest identifier
+- **Description**: placed in the app manifest
+- **Backend**: Node.js (Express + TypeScript) or .NET (ASP.NET Core + FastEndpoints)
+- **Frontend**: React (Vite + Tailwind + JTL Platform UI)
 
-Then start developing:
+Then:
 
 ```bash
 cd my-app
 npm install
+npm run register
 npm run dev
 ```
 
-## What's included
+The generated project includes:
+
+- A monorepo wired up with [Turborepo](https://turbo.build/)
+- A frontend with welcome pages explaining each app mode and manifest mapping
+- A backend with JWT verification, tenant connection, and ERP API proxy
+- A ready-to-register `manifest.json`
+- An `npm run register` script that delegates to `npx -y @jtl-software/create-cloud-app@latest register`
+
+### `register`
+
+Register a new app or update an existing app's manifest. Reads `manifest.json` from the current working directory and pushes it to the App Service.
+
+```bash
+npx @jtl-software/create-cloud-app register
+```
+
+By default the command is interactive: it opens a browser for OAuth login, then prompts for tenant and whether to update an existing app or create a new one.
+
+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.                                                                              |
+| `--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`.                                                                                                                                                        |
+| `--reauth`                                  | Skip the cached token and open the browser again. Useful after switching accounts.                                                                                                                   |
+| `--yes`, `-y`                               | Non-interactive mode. Auto-confirms prompts and fails if any choice is ambiguous (e.g. multiple tenants match). Required for CI.                                                                     |
+| `--tenant <id-or-slug>`                     | Select a tenant by ID or slug (case-insensitive).                                                                                                                                                    |
+| `--existing-app-id <id>`                    | Update the app with this ID instead of prompting. Errors if it doesn't match this manifest's technical name.                                                                                         |
+| `--new`                                     | Force-create a new app even if a matching one exists. Mutually exclusive with `--existing-app-id`.                                                                                                   |
+| `--on-collision <overwrite\|print\|cancel>` | What to do when an existing credentials file would be overwritten during provisioning. `print` writes the secret to stdout instead of the file. Required in `--yes` mode if a collision is possible. |
+
+Tokens are cached under `~/.config/jtl-cli/tokens.json` (mode `0600`). Override the path with the `JTL_CLI_TOKEN_CACHE_FILE` environment variable.
+
+## CI usage: keep your deployed manifest in sync with the repo
+
+A common setup is to commit `manifest.json` to source control and have CI push it to the cloud whenever it changes, so the deployed app always matches what's on `main`.
+
+The `register` command supports this. You need three things:
+
+1. **Pin the tenant and app ID** so the run is deterministic.
+2. **Run with `--yes`** so prompts don't block.
+3. **Seed the OAuth token cache** so login doesn't open a browser.
+
+### Step 1: capture a refresh token locally
+
+Run `register` once on your machine while signed in as the user (or service account) you want CI to act as:
+
+```bash
+cd path/to/your/app
+npx @jtl-software/create-cloud-app register --scope "openid offline_access"
+```
+
+After it completes, `~/.config/jtl-cli/tokens.json` contains an entry with a `refresh_token`. Copy that file's contents and store it as a CI secret (e.g. `JTL_CLI_TOKENS`).
+
+The cached token will be silently refreshed on every CI run, so it stays valid as long as CI runs often enough that the refresh token doesn't expire.
+
+### Step 2: look up your tenant and app ID
+
+You can read them off the previous interactive run (the CLI prints both). The tenant slug is the stable, human-friendly identifier. The app ID is a UUID printed in the "Review" section.
+
+### Step 3: CI workflow
+
+GitHub Actions example:
+
+```yaml
+name: Update manifest
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - manifest.json
+
+jobs:
+  register:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - name: Write token cache
+        env:
+          JTL_CLI_TOKENS: ${{ secrets.JTL_CLI_TOKENS }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/jtl-cli"
+          printf '%s' "$JTL_CLI_TOKENS" > "$RUNNER_TEMP/jtl-cli/tokens.json"
+          chmod 600 "$RUNNER_TEMP/jtl-cli/tokens.json"
+      - name: Update manifest
+        env:
+          JTL_CLI_TOKEN_CACHE_FILE: ${{ runner.temp }}/jtl-cli/tokens.json
+        run: |
+          npx -y @jtl-software/create-cloud-app@latest register \
+            --yes \
+            --tenant my-tenant-slug \
+            --existing-app-id 00000000-0000-0000-0000-000000000000
+```
 
-- Pre-configured monorepo with [Turborepo](https://turbo.build/)
-- Frontend with welcome pages explaining each app mode and manifest mapping
-- Backend with JWT verification, tenant connection, and ERP API proxy
-- Ready-to-register `manifest.json`
+`--yes` keeps the run non-interactive. `--tenant` and `--existing-app-id` pin the target so the command can't accidentally touch a different tenant or app. The job only runs when `manifest.json` changes, so the deployed manifest tracks `main`.
 
 ## After scaffolding
 
-1. Register your manifest in the [Partner Portal](https://partner.jtl-cloud.com/)
+1. Register your manifest in the [Partner Portal](https://partner.jtl-cloud.com/) or with `npm run register`
 2. Add your Client ID and Secret to the backend config
 3. Install the app from [JTL-Cloud Hub](https://hub.jtl-cloud.com/) under "Apps in development"
 

package/dist/index.js

@@ -999,6 +999,22 @@ function buildShortDescription(description) {
   if (description.length <= SHORT_DESCRIPTION_MAX_LENGTH) return description;
   return description.slice(0, SHORT_DESCRIPTION_MAX_LENGTH - 1).trimEnd() + "\u2026";
 }
+function buildPlaceholders(opts) {
+  return {
+    "{{APP_NAME}}": opts.appName,
+    "{{APP_NAME_PASCAL}}": toPascalCase(opts.appName),
+    "{{APP_TECHNICAL_NAME}}": buildTechnicalName(opts.appName),
+    "{{APP_DESCRIPTION}}": opts.description,
+    "{{APP_DESCRIPTION_SHORT}}": buildShortDescription(opts.description)
+  };
+}
+function applyPlaceholders(content, replacements) {
+  let result = content;
+  for (const [key, value] of Object.entries(replacements)) {
+    result = result.replaceAll(key, value);
+  }
+  return result;
+}
 var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".png",
   ".jpg",
@@ -1022,10 +1038,7 @@ function transformPackageJson(content, appName, templateType, replacements) {
   for (const field of PACKAGE_JSON_STRIP_FIELDS) {
     delete pkg[field];
   }
-  let result = JSON.stringify(pkg, null, 2);
-  for (const [key, value] of Object.entries(replacements)) {
-    result = result.replaceAll(key, value);
-  }
+  const result = applyPlaceholders(JSON.stringify(pkg, null, 2), replacements);
   return result + "\n";
 }
 function copyDir(src, dest, replacements, templateType, appName) {
@@ -1036,9 +1049,7 @@ function copyDir(src, dest, replacements, templateType, appName) {
     if (destName.startsWith("_git")) {
       destName = `.${destName.slice(1)}`;
     }
-    for (const [key, value] of Object.entries(replacements)) {
-      destName = destName.replaceAll(key, value);
-    }
+    destName = applyPlaceholders(destName, replacements);
     const destPath = path2.join(dest, destName);
     if (entry.isDirectory()) {
       copyDir(srcPath, destPath, replacements);
@@ -1053,11 +1064,8 @@ function copyDir(src, dest, replacements, templateType, appName) {
       if (BINARY_EXTENSIONS.has(ext)) {
         fs2.copyFileSync(srcPath, destPath);
       } else {
-        let content = fs2.readFileSync(srcPath, "utf-8");
-        for (const [key, value] of Object.entries(replacements)) {
-          content = content.replaceAll(key, value);
-        }
-        fs2.writeFileSync(destPath, content);
+        const content = fs2.readFileSync(srcPath, "utf-8");
+        fs2.writeFileSync(destPath, applyPlaceholders(content, replacements));
       }
     }
   }
@@ -1066,11 +1074,7 @@ function buildReplacements(base, template) {
   const extra = template.meta.extraReplacements ?? {};
   const resolved = {};
   for (const [key, value] of Object.entries(extra)) {
-    let resolvedValue = value;
-    for (const [baseKey, baseValue] of Object.entries(base)) {
-      resolvedValue = resolvedValue.replaceAll(baseKey, baseValue);
-    }
-    resolved[key] = resolvedValue;
+    resolved[key] = applyPlaceholders(value, base);
   }
   return { ...base, ...resolved };
 }
@@ -1083,14 +1087,7 @@ async function scaffold({
   targetDir: customTargetDir
 }) {
   const targetDir = customTargetDir ?? path2.resolve(process.cwd(), appName);
-  const pascalName = toPascalCase(appName);
-  const baseReplacements = {
-    "{{APP_NAME}}": appName,
-    "{{APP_NAME_PASCAL}}": pascalName,
-    "{{APP_TECHNICAL_NAME}}": buildTechnicalName(appName),
-    "{{APP_DESCRIPTION}}": description,
-    "{{APP_DESCRIPTION_SHORT}}": buildShortDescription(description)
-  };
+  const baseReplacements = buildPlaceholders({ appName, description });
   if (fs2.existsSync(targetDir)) {
     throw new Error(`Directory "${appName}" already exists`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtl-software/create-cloud-app",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "type": "module",
   "description": "CLI tool for scaffolding JTL Platform cloud apps",
   "bin": {
@@ -20,6 +20,7 @@
     "@clack/prompts": "^1.2.0",
     "@jtl-software/cloud-app-template-backend-dotnet": "0.0.12",
     "@jtl-software/cloud-app-template-backend-node": "0.0.14",
+    "@jtl-software/cloud-app-template-backend-php": "0.1.0",
     "@jtl-software/cloud-app-template-frontend-react": "0.0.16",
     "@jtl-software/cloud-app-template-shared": "0.0.6",
     "picocolors": "^1.1.1"