commercebuild-cli 0.0.31 → 0.0.33-rc.0

package/README.md

@@ -0,0 +1,111 @@
+# commercebuild-cli
+
+Command-line companion to the commercebuild store admin's app editor: it
+downloads a custom app to your machine, saves it back to the online draft,
+and builds or releases a version — the editor's Save / Deploy / Release
+buttons, as commands.
+
+Run it through `npx`; nothing needs installing globally:
+
+```
+npx commercebuild-cli@rc extension open <appId> --store https://<your-store>/
+```
+
+(`npm install -g commercebuild-cli` works too if you prefer a global
+install.)
+
+## Open an app in VS Code or Cursor (`extension open`)
+
+The store admin's app editor has an open-in-editor button (VS Code by
+default; the dropdown next to it picks Cursor, and the choice is
+remembered). With the **commercebuild App Studio** extension installed in that
+editor it opens
+`vscode://commercebuild.vscode-store-app/open?app=<appId>&store=<url>`
+(`cursor://…` for Cursor); the extension confirms the working folder, runs
+`extension open` in the background (with `--no-editor --json`) and opens
+the result in the current window. Without the extension the button shows
+the same command to copy (with `--editor cursor` when Cursor was picked).
+
+What `open` does:
+
+- Downloads a **complete, fresh copy** of the app's current online
+  **draft** (falling back to the released upload, then the latest upload)
+  into `./<name>` under the current directory. If that folder already has
+  content, the copy goes to `./<name>(1)`, `(2)`, … — an earlier download
+  is never touched. `--dir` picks another location (same suffix rule),
+  `COMMERCEBUILD_APPS_DIR` a fixed root.
+- Writes `.env` (`COMMERCEBUILD_STORE_URL`) and `.npmrc`
+  (`node-linker=hoisted`, for pnpm); makes sure `.gitignore` covers
+  `node_modules`, `dist`, `.env`, `.DS_Store`, `*.log`, vite's `.vite/` and
+  Yarn Berry's `.pnp.*` / `.yarn/{cache,unplugged,install-state.gz,build-state.yml}`
+  — never lockfiles (the file is created when the app has none — apps made
+  in the online editor don't — otherwise only the missing lines are
+  appended); adds `save` / `deploy` / `release` scripts to `package.json`
+  when they are missing. Then launches VS Code (`--editor cursor` or
+  `$COMMERCEBUILD_EDITOR` for another editor, `--no-editor` to skip).
+  Files the project already has are never changed.
+- Adds a `type-check` script (`commercebuild-extension type-check`, the
+  SDK's own `tsc --noEmit`) **only** when the project's declared
+  `@commercebuild/extension` range can resolve to a version that has it
+  (0.0.21 or newer) — an older SDK exits 0 on the unknown subcommand, which
+  would look like a passing check. A pinned old range (`0.0.18`, `^0.0.18`)
+  or a missing declaration gets a warning with the upgrade command instead;
+  an existing `type-check` script is never touched. Lockfiles are never
+  downloaded, so `^0.*` resolves to the newest SDK on `npm install`.
+- Creates `README.md` (how to develop locally, the editor's Save / Deploy /
+  Release as npm scripts, how to use the AI files), `AGENTS.md` and
+  `CLAUDE.md` at the project root when the download lacks them (the
+  editor's scaffold, its Export and `extension create` write the same
+  files). They are project source: saved in the draft, included in
+  deploys, never overwritten. They point Claude Code, Cursor, Codex and
+  Copilot at the platform guide in
+  `node_modules/@commercebuild/extension/AGENTS.md` and hold a "Project
+  notes" section for app-specific rules that the online assistant reads
+  too. Gemini CLI reads `GEMINI.md` unless `.gemini/settings.json` sets
+  `{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }`.
+- **Never installs dependencies.** The source comes from a shared draft, so
+  nothing from it is executed; run `npm install` (or yarn / pnpm) yourself
+  after looking at the project.
+- No editor installed? The download still succeeds (exit 0); the command
+  prints the folder and a warning instead of launching anything.
+- `--json` prints `{dir, source, files}` on stdout (errors as `{error}`);
+  the commercebuild App Studio extension uses it with `--no-editor` to open the
+  folder in its own window.
+
+## Signing in (`auth`)
+
+`auth login --store <url>` signs in through the store admin's consent page
+in your browser and keeps the token pair in your operating system's
+keychain; `auth info` lists the stores you are signed in to and `auth
+logout` signs out.
+
+`auth token [--store <url>] [--json]` prints a current access token for a
+signed-in store (the current one by default), renewed first when it has
+less than 5 minutes left. Only the token goes to stdout; `--json` prints
+`{accessToken, expiresAt, storeUrl, adminUrl, storeId}` instead, and an
+error as `{error, code}` (`code` is `not-signed-in` when there is no
+sign-in to use), with exit code 1. The commercebuild App Studio
+extension's assistant panel gets its token this way. Treat the output like
+a password.
+
+## Working locally
+
+The online editor's actions have these equivalents, all run in the
+project folder (npm shown; yarn and pnpm work the same — the project
+declares no package manager, and `open` writes an `.npmrc` so pnpm hoists
+like npm):
+
+| Online editor    | Local                                   | What it does                                                                                                                                                                                                                                                                                                                                        |
+| ---------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (build errors)   | `npm run type-check`                    | The SDK's TypeScript over the project (`tsc --noEmit`), exit code = tsc's. Run after every change; the online editor's compile errors are the equivalent.                                                                                                                                                                                           |
+| Save             | `npm run save` (`extension save`)       | Zips the project (minus `node_modules`, `dist`, `.git`, `.env*`, `.npmrc`, lockfiles, logs, binary files) and **replaces** the online draft — the editor shows it on next load. A save based on an older revision than the online one is refused unless `--force` is given. Held to the platform's draft cap (5 MB by default), same as the editor. |
+| Deploy           | `npm run deploy` (`extension commit`)   | Builds a new version from `src/**` plus the root manifests, `.gitignore` and the AI / README files. `-m "…"` gives the build's description; without it the CLI asks (a script must pass it).                                                                                                                                                        |
+| Deploy → Release | `npm run release` (`extension release`) | Builds and makes the version live. Waits up to 15 min for the build, retrying failed status polls; if it stops waiting, the build continues on the server — finish with `npx commercebuild-cli@rc extension release --build <buildRef>` (printed in the message) or release the version in the store admin.                                         |
+
+`npm run dev` previews the app against your store (open the storefront with
+`?devSource=http://localhost:25521`).
+
+The editor's **Export** button produces the same project as `extension
+open` (one zip, ready to run), and its **Import** takes such a folder back
+— minus the machine-local files (`.env*`, `.npmrc`, lockfiles), which it
+never reads from a zip.