@jtl-software/create-cloud-app 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @jtl-software/create-cloud-app
 
-CLI for [JTL Platform](https://www.jtl-software.com/) cloud apps. Scaffolds a new app project and registers/updates its manifest against the cloud.
+CLI for [JTL Platform](https://www.jtl-software.com/) cloud apps. Scaffolds a new app project, registers it against the cloud, and pushes its store listing.
 
 ## Requirements
 
@@ -8,10 +8,13 @@ Node.js **24** (current LTS) or newer. The scaffolded project sets the same floo
 
 ## Commands
 
-The CLI has two entry points:
+The CLI has three entry points:
 
 - The default invocation (no arguments) scaffolds a new project.
-- `register` registers or updates a manifest against the JTL Cloud.
+- `register` registers or updates the app's identity (`app.json`) against the JTL Cloud — do this when you start building.
+- `listing` pushes the app's store listing (`listing.json`) — do this once you're done building and ready to publish.
+
+Registration and listing are two independent resources on two independent files. `register` must happen first — `listing` pushes against the app that `register` created and will fail with a clear error if it hasn't run yet.
 
 ### `npm create @jtl-software/cloud-app@latest`
 
@@ -24,7 +27,7 @@ npm create @jtl-software/cloud-app@latest
 You'll be prompted for:
 
 - **App name**: directory name, package name, and manifest identifier
-- **Description**: placed in the app manifest
+- **Description**: placed in the listing
 - **Backend**: Node.js (Express + TypeScript) or .NET (ASP.NET Core + FastEndpoints)
 - **Frontend**: React (Vite + Tailwind + JTL Platform UI)
 
@@ -42,12 +45,14 @@ 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`
+- A ready-to-register `app.json` (identity: `technicalName`, `version`, `lifecycle`, `capabilities`)
+- A ready-to-push `listing.json` (store metadata: `name`, `description`, `media`, `pricing`, etc.)
 - An `npm run register` script that delegates to `npx -y @jtl-software/create-cloud-app@latest register`
+- An `npm run listing` script that delegates to `npx -y @jtl-software/create-cloud-app@latest listing`
 
 ### `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.
+Register a new app or update an existing app's manifest. Reads `app.json` from the current working directory and pushes it to the App Service.
 
 ```bash
 npx @jtl-software/create-cloud-app register
@@ -73,11 +78,23 @@ Flags:
 
 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
+### `listing`
+
+Push the app's store listing. Reads `listing.json` and the `technicalName` from `app.json` (both in the current working directory), then pushes the listing for that app.
+
+```bash
+npx @jtl-software/create-cloud-app listing
+```
+
+Like `register`, it's interactive by default: OAuth login, then a tenant prompt. It also asks two questions about the listing itself — distribution type (`PUBLIC`/`PRIVATE`) and default locale — pre-filled from whatever's already in `listing.json` and written back there once answered, so re-running `listing` later remembers your choice. Unlike `register`, there's no create-vs-update choice or local credential file to write — a listing is always pushed against the app `register` already created, keyed by `technicalName`. If no registered app matches, the command fails with a message telling you to run `register` first.
+
+Flags: `--api-host`, `--auth-host`, `--hub-host`, `--client-id`, `--scope`, `--reauth`, `--yes`/`-y`, `--tenant` — same meaning as the equivalent `register` flags above. There's no `--existing-app-id`, `--new`, or `--on-collision` since listing has nothing to disambiguate or overwrite locally.
 
-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`.
+## CI usage: keep your deployed app.json and listing.json in sync with the repo
 
-The `register` command supports this. You need three things:
+A common setup is to commit `app.json` and `listing.json` to source control and have CI push them to the cloud whenever they change, so the deployed app always matches what's on `main`.
+
+Both `register` and `listing` support 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.
@@ -98,23 +115,25 @@ The cached token will be silently refreshed on every CI run, so it stays valid a
 
 ### 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.
+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 — only `register` needs it; `listing` only needs the tenant, since it resolves the app by `technicalName`.
 
 ### Step 3: CI workflow
 
-GitHub Actions example:
+GitHub Actions example — one job per file, each triggered only when its own file changes:
 
 ```yaml
-name: Update manifest
+name: Update app.json and listing.json
 
 on:
   push:
     branches: [main]
     paths:
-      - manifest.json
+      - app.json
+      - listing.json
 
 jobs:
   register:
+    if: contains(github.event.head_commit.modified, 'app.json')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -136,15 +155,41 @@ jobs:
             --yes \
             --tenant my-tenant-slug \
             --existing-app-id 00000000-0000-0000-0000-000000000000
+
+  listing:
+    if: contains(github.event.head_commit.modified, 'listing.json')
+    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 listing
+        env:
+          JTL_CLI_TOKEN_CACHE_FILE: ${{ runner.temp }}/jtl-cli/tokens.json
+        run: |
+          npx -y @jtl-software/create-cloud-app@latest listing \
+            --yes \
+            --tenant my-tenant-slug
 ```
 
-`--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`.
+Note `listing` doesn't take `--existing-app-id` — it only needs `--tenant` to pin the target, since the app is resolved by `technicalName`.
+
+`--yes` keeps each job non-interactive, and the `if:` conditions mean only the file that actually changed gets pushed — an `app.json`-only commit doesn't re-push an unchanged listing, and vice versa.
 
 ## After scaffolding
 
-1. Register your manifest in the [Partner Portal](https://partner.jtl-cloud.com/) or with `npm run register`
+1. Register your app's identity 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"
+4. Once you're done building, push the store listing with `npm run listing`
 
 ## Documentation