@plitzi/cli 0.38.5 → 0.38.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/cli",
-  "version": "0.38.5",
+  "version": "0.38.7",
   "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.38.5",
+    "@plitzi/sdk-authoring": "0.38.7",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "esbuild": "^0.28.2",
     "fflate": "^0.8.3"
   },
   "devDependencies": {
-    "@plitzi/sdk-shared": "0.38.5",
+    "@plitzi/sdk-shared": "0.38.7",
     "@types/node": "^26.6.4",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",

package/skills/plitzi-cli/SKILL.md

@@ -39,12 +39,15 @@ npx @plitzi/cli functions dev feed.read --watch                   # the same, fr
 ## Running it as an agent
 
 - **Which check.** The space as a document: `npm run author`. How its source is written: `npm run lint:space`. A
-  rendered page: `check`. The project around them (packages, configs, imports, plugins, data): `doctor`, before
-  `push`; `--fix` repairs the simple ones (an older project: `npx @plitzi/cli@latest doctor --fix`).
+  rendered page: `check`. The project around them (layout, packages, configs, imports, plugins, data): `doctor`,
+  before `push`; `--fix` repairs the simple ones (an older project: `npx @plitzi/cli@latest doctor --fix`).
 
-- **After the SDK moves, `upgrade`.** It shows the CLI's files, scripts, versions and skills as they should be now, and
-  each renamed name at its line. `--write` replaces what nobody changed, merges `package.json` and installs; a file
-  you changed comes as a diff — `--take <file>` once read.
+- **Reporting to Plitzi: `feedback`.** It writes the report's page and says how to fill and publish it; give the
+  person the link.
+
+- **After the SDK moves, `upgrade`.** It shows the CLI's files, scripts, versions, skills and renamed names as they
+  should be. `--write` replaces what nobody changed, merges `package.json` and installs; a file you changed comes as a
+  diff — `--take <file>` once read.
 
 - **`create` never decides for the person.** Three choices shape a project — package manager, `--mode`
   (`server`: SSR + RSC on a Node tier, `client`: browser only) and `--source` (`local`: the space lives in the project,
@@ -56,8 +59,8 @@ npx @plitzi/cli functions dev feed.read --watch                   # the same, fr
 - **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 --json` (`{ api, user, space }`) before an upload.
 - **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.
+  sign-in prompts are on stderr; exit 1 means it did not do what was asked, or a check found something. A bad flag
+  value is refused with what it takes: read it, do not drop the flag.
 
 ## The Plitzi MCP or this CLI
 
@@ -86,9 +89,9 @@ What a project gives you, so you use it rather than rebuild it:
 | `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: restarted on a save to its code; a plugin is swapped in the open page. Options in `src/config/serverOptions.ts`, actions in `src/actions/`; `plitzi/` is the CLI's, never edit it |
 | `author` | author `src/space/`: every problem at once (file:line, what to change), then the suggestions (`[suggest]`: a shorter way to the same page, the most elements saved first); `-- --json` for a tool |
-| `lint:space` | how `src/space/` is written, at file:line: long files, inline data, colours not tokens, copied CSS, and authoring's suggestions; `-- --max-warnings 0`. On purpose: `// plitzi-lint-disable-next-line <code> -- why` |
+| `lint:space` | how `src/space/` is written, at file:line, and authoring's suggestions; `-- --max-warnings 0`. On purpose: `// plitzi-lint-disable-next-line <code> -- why` (a suggestion: `quiet` on its element) |
 | `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, a binding its data lacks; `--state`, `--element <id>`: what it holds; `--ssr`: what SSR misses; `--json` |
+| `check -- /path --width 1440,390` | whether a page is whole, in text: elements on screen, overflow, console, refused requests, failed flows, a binding its data lacks; `--state`, `--element <id>`: what it holds; `--ssr`: SSR misses; `--as <user>`; `--json` |
 | `npx plitzi import <url>` | a page the user owns, as a start: `tokens.ts`, `outline.ts` (blocks and layout per breakpoint), lists as `data/*.json`, screenshots, `IMPORT.md`. Never the words. **Only when the user asks.** A site not on this machine needs `--account` (their Plitzi account, its domain verified on a space): ask first |
 | `shot -- /path --width 390 --scheme dark` | a picture of one page — `--clip <element>` one element, `--scroll-to <element>` / `--viewport` the screen there, `--frames 4` what moves, `--compare <url>` what differs from another site, by section and by text |
 | `visual` | a browser asserts every element the space names is visible |
@@ -117,7 +120,6 @@ The space itself is written with `@plitzi/sdk-authoring` — see the `plitzi-aut
 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`.
 
-
 ## Elements of your own (`add plugin`)
 
 A plugin is a React component the space renders — a map, a chart, a seat picker: whatever is not text in a box. **Never
@@ -127,7 +129,6 @@ read.
 ```bash
 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
 ```
 
@@ -186,8 +187,7 @@ its settings kept. `--plugin-version` sets the version the manifest carries. The
 imports, followed from its entry — is kept beside it on the space (`runtime push` does the same for a runtime), which
 is what `create --from` brings back; `plitzi pack source` writes what would be kept to a file, to look at.
 
-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`).
+A self-hosted page server does not need `pack`: it compiles a plugin from its source (`action: 'compile'`).
 
 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
@@ -208,6 +208,7 @@ A space's own server code, edited in `src/functions/` (`pull`, `push`, `try`, `d
 | `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; `tmp/dev-server.json` has this project's port |
 | "Custom Component … Not Found", or a flow on a plugin's event never runs | `doctor` names the folder whose type or declaration is off |
+| "not laid out as Plitzi reads it" | each misplaced part, with its fix; `doctor --fix` |
 | `upload` opens a browser | there is no session, or no space chosen — the person completes it there |
 | The upload went to the wrong space | `plitzi space` chooses another; check `whoami` first |
 | `pull` wrote nothing and named files | they changed here and on the space — set your changes aside and pull again, or `--force` |

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

@@ -9,7 +9,8 @@ A space's own server code — TypeScript tasks its actions run as steps, and rou
   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 `src/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.
+  relative path and `@plitzi/sdk-server/functions`, nothing else. `src/data/` is read with `ctx.data('x.json')`, never
+  imported (`dev` reads the project's).
 - **`try` runs the saved draft for real** (its fetches and writes happen). `dev` runs `src/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.