@plitzi/cli 0.37.9 → 0.37.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/cli",
-  "version": "0.37.9",
+  "version": "0.37.10",
   "license": "AGPL-3.0",
   "description": "Command line for Plitzi: scaffold a project that renders a space, a plugin package, or an element of your own.",
   "files": [
@@ -21,14 +21,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/sdk-authoring": "0.37.9",
+    "@plitzi/sdk-authoring": "0.37.10",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "esbuild": "^0.28.2",
     "fflate": "^0.8.3"
   },
   "devDependencies": {
-    "@plitzi/sdk-shared": "0.37.9",
+    "@plitzi/sdk-shared": "0.37.10",
     "@types/node": "^26.6.2",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",

package/skills/plitzi-cli/SKILL.md

@@ -17,7 +17,7 @@ test wired together; a plugin's four files in the shape Plitzi's own elements us
 a signed-in upload. **Reach for it before writing any of those yourself.**
 
 ```bash
-npx @plitzi/cli create my-site                 # a project that renders a space
+npx @plitzi/cli create my-site                 # a project that renders a space (--template blank | catalog)
 npx @plitzi/cli create my-board --from pizarra # a space on Plitzi, as a project that serves it alone
 npx @plitzi/cli pull                           # that project brought up to date with its space
 npx @plitzi/cli add plugin seat-picker legend  # elements of your own, in the project you are in
@@ -25,6 +25,9 @@ npx @plitzi/cli create seat-picker --plugin    # a plugin package any space can
 npx @plitzi/cli pack plugin                    # a plugin built, and zipped the way the builder takes it
 npx @plitzi/cli upload plugin                  # that zip, on the space you work in, and installed there
 npx @plitzi/cli whoami                         # who the CLI is signed in as, and the space it works in
+npx @plitzi/cli data describe public/data/products.json   # a JSON file's fields, types and one row — not read whole
+npx @plitzi/cli skills update                  # the skills in .claude/skills, up to the SDK installed
+npx @plitzi/cli explain navigate               # what a name means: element, step, trigger, problem or suggestion code (--list steps)
 npx @plitzi/cli functions pull                 # the space's functions (its own server code) into functions/
 npx @plitzi/cli functions push                 # functions/ back as the space's draft, built and checked
 npx @plitzi/cli functions try feed.read --params '{"limit":3}'   # one task of the saved draft, in the sandbox
@@ -43,8 +46,24 @@ npx @plitzi/cli functions dev feed.read --watch                   # the same, fr
 - **Signing in happens in the browser.** `login`, `space` and a first `upload` open one; the person completes it (MFA
   and social sign-in included — the CLI never sees a password). Tell them a browser tab is waiting, and wait.
 - **One space at a time.** Everything goes to the space `whoami` names; `plitzi space` switches it. No command takes a
-  space as a flag, so check `whoami` before an upload.
+  space as a flag, so check `whoami --json` (`{ api, user, space }`) before an upload.
 - **`--no-install`** writes the files without installing, **`--force`** writes into a directory that has work in it.
+- **Read stdout, exit code and stderr apart.** The answer is on stdout (`--json`: one object, one line); errors and
+  sign-in prompts are on stderr; exit 1 means it did not do what was asked, or a check found something. A flag value
+  that is not one is refused with what it takes — read the message rather than retrying without the flag.
+
+## The Plitzi MCP or this CLI
+
+Where the space lives decides which one an agent uses — the two never take turns on one space.
+
+| The space | Use |
+| --- | --- |
+| In a project, written in code (`src/space.ts`, `--source local`) | this CLI and `@plitzi/sdk-authoring`. No account and no MCP |
+| On Plitzi — edited in the builder, with collaborators, published from there | the Plitzi MCP server: it reads and edits the live space, previews a page and checks every edit with the same linter |
+| On Plitzi, and wanted in code from now on | `create --from <space>`, then `pull` to keep the project in step |
+
+The MCP needs a signed-in account. If it asks for authentication and nobody can give it, do not wait on it: a project
+with `--source local` needs neither.
 
 ## Projects (`create`)
 
@@ -57,39 +76,37 @@ What a project gives you, so you use it rather than rebuild it:
 
 | Script | What it is for |
 | --- | --- |
-| `start` | serve it — in client mode Vite, which hot-replaces on save |
+| `start` | serve it — in client mode Vite, which hot-replaces on save. The server prints only what goes wrong; `-- --verbose` adds every request |
 | `start:dev` | server mode: the server, restarted on save |
-| `author` | author `src/space.ts` and print every warning — the check after each change (local projects) |
-| `shot -- /path --width 390 --scheme dark` | a picture of one page |
+| `author` | author `src/space.ts`: one line when it is fine, every problem at once (file:line, what to change) when not, then the suggestions (`[suggest]`: a shorter way to the same page, the most elements saved first); `-- --json` for a tool |
+| `npx plitzi fix` | what `author` reports that has one fix, as a diff of your source; `--write` writes it, formatted, and keeps it only if the space then authors with it gone and nothing new |
+| `check -- /path --width 1440,390` | whether a page is whole, in text: elements on screen, overflow, console, refused requests, failed flows; `--state` and `--element <id>` say what it holds; `--json` |
+| `npx plitzi import <url>` | a page the user owns, measured as a place to start from: `tokens.ts` (colours light and dark, corners, shadows, Google fonts), `outline.ts` (its blocks and their layout per breakpoint), its repeated lists as `data/*.json`, screenshots per width, and `IMPORT.md` saying what was not carried over. Never the words. Only a site whose domain the user verified on one of their spaces (`_plitzi` TXT, under Domains in the dashboard), or one served from this machine — anything else is refused |
+| `shot -- /path --width 390 --scheme dark` | a picture of one page — `--frames 4` says what moves, `--compare <url>` how much differs from another site by section, `--wait-for <element>`; refused when the port answers as another project |
 | `visual` | a browser asserts every element the space names is visible |
 | `typecheck`, `lint`, `format` | before calling a change done |
 
+**Which port.** `start` takes 8080, or the next free one when something else holds it — printed, and written to
+`.plitzi/dev-server.json`, where `check`, `shot` and `visual` look for it. Set `PORT` to choose one (then a taken port is an
+error). `/health` answers with the space's name: a server that answers as something else is not this project.
+
+The data a page reads with no backend goes in `public/data/*.json`, served by the project as it is; in server mode a
+provider with `runtime: 'server'` reads it on the server, so the page arrives with it. To bind to a file, learn its fields
+with `data describe` rather than reading it: a catalogue is half a megabyte, its shape twenty lines.
+
+A local space starts as a tour of the platform with a plugin of the project's own; **`--template blank`** starts it as
+tokens, a layout and one empty page instead — the one to pick when the project is about to be a specific site; and
+**`--template catalog`** as a complete small shop (layout, card component, data in `public/data`, a filtered list, a
+page per product), a file per part — the one to read when unsure how a whole site is put together.
+
 The space itself is written with `@plitzi/sdk-authoring` — see the `plitzi-authoring` skill, which `create` copies into
 `.claude/skills/` beside this one.
 
 ## A space on Plitzi, as a project (`create --from`, `pull`)
 
-`create --from <space>` (its permanent URL or id) writes a server project holding everything the space is made of, and
-serving it with nothing of Plitzi's — neither its servers nor its CDN:
-
-- its pages as authoring code in `src/space/` (`--source cloud` writes none: they stay on Plitzi, read with a key);
-- its actions in `src/actions/` — each a `defineAction` call where the document reads back exactly, JSON where it does
-  not (the report says why) — and its connectors as JSON;
-- its functions in `functions/`, its runtime and plugins as the source they were built from, under `src/`;
-- its files downloaded into `public/`, every CDN address rewritten to the project's own;
-- `.env` with a signing key made for it, and the names of the variables and credentials it needs — never their values.
-
-It takes a signed-in CLI and a space the person may change (owner, admin or writer). It takes out the draft unless
-`--environment production` (that environment's latest snapshot) or `--environment production --revision 3` (that one,
-pinned) says otherwise. Read the report it prints: a
-plugin or runtime uploaded before Plitzi kept sources comes across built only (`vendor/`), and a space with visitor
-roles needs sign-in of its own (the note in `src/main.ts`).
+Taking a space out of Plitzi as a server project of its own, and keeping it in step: read
+[reference/from-space.md](reference/from-space.md) when the task names `--from` or `pull`.
 
-`pull` brings the project up to date: what changed on the space alone is written, what changed here alone is kept,
-and when one file changed on both it writes **nothing** and names them — keep your changes aside and pull again, or
-`--force` to take the space's copy. It never touches `.env`, and only adds to `package.json`. What the project was given
-is recorded in `.plitzi/space.json`: commit it. It follows the version the project was made from; `pull --environment
-… --revision …` moves it to another, `--revision latest` lets go of a pin.
 
 ## Elements of your own (`add plugin`)
 
@@ -101,8 +118,15 @@ read.
 plitzi add plugin seat-picker                                  # one; asks what the builder calls it and what it is for
 plitzi add plugin seat-picker legend                           # several at once
 plitzi add plugin seat-picker --title "Seat Picker" --description "Pick a seat from a venue map"
+plitzi add plugin ticker --prop interval:number=5000 --prop paused:boolean --trigger onTick:count --callback reset --headless
 ```
 
+**Say its shape and it is written in it**, with nothing to delete: `--prop name:type=default` (string, number,
+boolean) for each attribute — typed, defaulted, bindable, with a control in its panel; `--trigger onTick:count` for
+each event and what a flow reads from it, fired with the `use<Name>Events()` hook it gets; `--callback reset` for
+each action a flow can call; `--headless` for one with nothing to see (hidden on a page, a badge in the builder).
+Without them it writes a counter that shows the three ways an element talks to a space — to be rewritten.
+
 Each is a folder (`src/plugins/SeatPicker/` in a project `create` wrote):
 
 | File | What it holds |
@@ -155,30 +179,24 @@ is what `create --from` brings back; `plitzi pack source` writes what would be k
 A self-hosted page server does not need `pack`: it compiles a plugin from its source
 (`plugins: { seatPicker: { js: 'src/plugins/SeatPicker/index.ts', action: 'compile' } }` in `createServer`).
 
+The same server decides its own say over the space's **feature flags**: `createServer({ flags: { newCheckout: true } })`
+(or a function of `{ spaceId, environment }` when it serves several). It overrides what the space declares — only for
+flags the space declares — and is overridden by the SDK's `flags` prop and a tester's dev tools. Declaring the flags
+themselves is the space's (`flags` in the spec; see the authoring skill's feature flags).
+
 ## A space's functions (`functions`)
 
-A space's own server code — TypeScript tasks its actions run as steps, and routes under `/fn/` — lives in the space;
-`functions/` in a project is a **working copy** of it. The contract (`defineFunctions`, `ctx`) and every rule are in
-`docs/en/functions.md` of the workspace; what matters for the CLI:
-
-- **Pull before you edit, push when done.** `pull` refuses to overwrite what is not pushed (`--force` throws it
-  away); `push` refuses when the space changed since the pull — someone saved in the builder. Then: keep your changes
-  aside, `pull`, apply them again, `push`. Never `--force` over somebody else's work to get past it.
-- **A push is checked, not just stored.** A problem comes back as `functions/<file>:<line> <message>` and nothing is
-  saved — fix it and push again. `index.ts` must default-export `defineFunctions({ … })`; files import each other by
-  relative path and `@plitzi/sdk-server/functions`, nothing else.
-- **`try` runs the saved draft for real** (its fetches and writes happen). `dev` runs `functions/` on this machine with
-  the project's own `@plitzi/sdk-server` — `npm install -D @plitzi/sdk-server isolated-vm core-js` first — and sends
-  nothing to the space; `PLITZI_FUNCTIONS_CREDENTIALS='{"stripe":{"apiKey":"…"}}'` gives it credentials to name.
-- **A run gets 100 ms of CPU and 10 s.** A task that needs more asks with `limits: { cpuMs, wallMs }` (or
-  `defineFunctions({ limits })` for all), up to the plan's ceiling; asking above it is a problem the push reports.
-- **The live site runs what the space was last published with.** A push changes the draft; publishing is the person's.
+A space's own server code, edited in `functions/` with `pull`, `push`, `try` and `dev`: read
+[reference/functions.md](reference/functions.md) when the task names its functions.
+
 
 ## When something does not work
 
 | What you see | What it is |
 | --- | --- |
 | `create` printed questions and wrote nothing | nobody answered the three choices — ask the user, pass them as flags |
+| `start` says the port is in use | `PORT` is set to a taken port — unset it to take the next free one, or choose another |
+| A page that is not this project's, or `shot` refuses the port | another server answers there — `curl 127.0.0.1:<port>/health` names it; `.plitzi/dev-server.json` has this project's port |
 | An element renders "Custom Component … Not Found" | the `renderType` names no registered plugin — check the folder name's camelCase |
 | A flow on the plugin's event is refused, or never runs | the event is not in `declaration.ts`, or the plugin is missing from `src/plugins/declarations.ts` |
 | `upload` opens a browser | there is no session, or no space chosen — the person completes it there |

package/skills/plitzi-cli/reference/from-space.md

@@ -0,0 +1,23 @@
+# A space on Plitzi, as a project (`create --from`, `pull`)
+
+`create --from <space>` (its permanent URL or id) writes a server project holding everything the space is made of, and
+serving it with nothing of Plitzi's — neither its servers nor its CDN:
+
+- its pages as authoring code in `src/space/` (`--source cloud` writes none: they stay on Plitzi, read with a key);
+- its actions in `src/actions/` — each a `defineAction` call where the document reads back exactly, JSON where it does
+  not (the report says why) — and its connectors as JSON;
+- its functions in `functions/`, its runtime and plugins as the source they were built from, under `src/`;
+- its files downloaded into `public/`, every CDN address rewritten to the project's own;
+- `.env` with a signing key made for it, and the names of the variables and credentials it needs — never their values.
+
+It takes a signed-in CLI and a space the person may change (owner, admin or writer). It takes out the draft unless
+`--environment production` (that environment's latest snapshot) or `--environment production --revision 3` (that one,
+pinned) says otherwise. Read the report it prints: a
+plugin or runtime uploaded before Plitzi kept sources comes across built only (`vendor/`), and a space with visitor
+roles needs sign-in of its own (the note in `src/main.ts`).
+
+`pull` brings the project up to date: what changed on the space alone is written, what changed here alone is kept,
+and when one file changed on both it writes **nothing** and names them — keep your changes aside and pull again, or
+`--force` to take the space's copy. It never touches `.env`, and only adds to `package.json`. What the project was given
+is recorded in `.plitzi/space.json`: commit it. It follows the version the project was made from; `pull --environment
+… --revision …` moves it to another, `--revision latest` lets go of a pin.

package/skills/plitzi-cli/reference/functions.md

@@ -0,0 +1,18 @@
+# A space's functions (`functions`)
+
+A space's own server code — TypeScript tasks its actions run as steps, and routes under `/fn/` — lives in the space;
+`functions/` in a project is a **working copy** of it. The contract (`defineFunctions`, `ctx`) is typed in
+`@plitzi/sdk-server/functions`, whose `.d.ts` documents every field; what matters for the CLI:
+
+- **Pull before you edit, push when done.** `pull` refuses to overwrite what is not pushed (`--force` throws it
+  away); `push` refuses when the space changed since the pull — someone saved in the builder. Then: keep your changes
+  aside, `pull`, apply them again, `push`. Never `--force` over somebody else's work to get past it.
+- **A push is checked, not just stored.** A problem comes back as `functions/<file>:<line> <message>` and nothing is
+  saved — fix it and push again. `index.ts` must default-export `defineFunctions({ … })`; files import each other by
+  relative path and `@plitzi/sdk-server/functions`, nothing else.
+- **`try` runs the saved draft for real** (its fetches and writes happen). `dev` runs `functions/` on this machine with
+  the project's own `@plitzi/sdk-server` — `npm install -D @plitzi/sdk-server isolated-vm core-js` first — and sends
+  nothing to the space; `PLITZI_FUNCTIONS_CREDENTIALS='{"stripe":{"apiKey":"…"}}'` gives it credentials to name.
+- **A run gets 100 ms of CPU and 10 s.** A task that needs more asks with `limits: { cpuMs, wallMs }` (or
+  `defineFunctions({ limits })` for all), up to the plan's ceiling; asking above it is a problem the push reports.
+- **The live site runs what the space was last published with.** A push changes the draft; publishing is the person's.