@plitzi/cli 0.38.2 → 0.38.4

package/package.json

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

package/skills/plitzi-cli/SKILL.md

@@ -5,9 +5,9 @@ description: >-
   generates: scaffold a project that renders a space, add elements of your own (plugins) to it, create a plugin package,
   build a plugin into the module + manifest + zip the platform takes, sign in to upload and install it on a space, and
   edit a space's own server code (its functions) in the project, and take a space on Plitzi out as a self-hosted project
-  of its own (`create --from`, kept in step with `pull`). Use whenever the task is to start a Plitzi project, create or
-  change a plugin/custom element, pack, upload or install one, pull/push/try a space's functions, move a space to a
-  server of its own, or work out which space the CLI is connected to.
+  of its own (`create --from`, kept in step with `pull` and `push`). Use whenever the task is to start a Plitzi project,
+  create or change a plugin/custom element, pack, upload or install one, pull/push/try a space's functions, move a space
+  to a server of its own and back, or work out which space the CLI is connected to.
 ---
 
 # The Plitzi CLI
@@ -20,14 +20,16 @@ a signed-in upload. **Reach for it before writing any of those yourself.**
 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 push                           # its changes back as the draft (or: push space functions)
 npx @plitzi/cli add plugin seat-picker legend  # elements of your own, in the project you are in
 npx @plitzi/cli create seat-picker --plugin    # a plugin package any space can load
 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 upgrade                        # the project up to this CLI: files, package.json, skills, renames (--write)
+npx @plitzi/cli upgrade skills --write         # only one part: files | packages | skills | renames
+npx @plitzi/cli explain navigate               # what a name means: element, step, trigger, code, helper (bindTemplate, motion)
 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
@@ -38,6 +40,10 @@ npx @plitzi/cli functions dev feed.read --watch                   # the same, fr
 
 ## Running it as an agent
 
+- **After the SDK moves, `upgrade`.** It shows the CLI's files, scripts, versions and skills as they should be now, and
+  every 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.
+
 - **`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,
   `cloud`: it lives in Plitzi). With nobody at the terminal it writes NOTHING and prints each missing choice as a
@@ -47,7 +53,6 @@ npx @plitzi/cli functions dev feed.read --watch                   # the same, fr
   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 --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.
@@ -60,7 +65,7 @@ Where the space lives decides which one an agent uses — the two never take tur
 | --- | --- |
 | 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 |
+| On Plitzi, and wanted in code from now on | `create --from <space>`, then `pull` and `push` keep both 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.
@@ -80,20 +85,21 @@ What a project gives you, so you use it rather than rebuild it:
 | `start:dev` | server mode: the server, restarted on save |
 | `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 |
+| `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` |
+| `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 a space (`_plitzi` TXT, Domains in the dashboard) or served from this machine |
+| `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 |
 | `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.
+**Which port.** `start` takes 8080, or the next free one — printed, and written to `tmp/dev-server.json` for `check`,
+`shot` and `visual`. `PORT` chooses one (a taken one is then an error). `/health` answers with the space's name.
 
 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.
 
+**`public/` is on the internet** — never a secret there. `tmp/` (ignored) and `.plitzi/` (committed): `AGENTS.md`.
+
 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
@@ -184,10 +190,10 @@ The same server decides its own say over the space's **feature flags**: `createS
 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`)
+## Server code (`functions`, `runtime`)
 
-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.
+A space's own server code, edited in `functions/` (`pull`, `push`, `try`, `dev`) or run as its runtime
+(`src/runtime.ts`, `runtime push`): read [reference/functions.md](reference/functions.md) for either.
 
 
 ## When something does not work
@@ -196,7 +202,7 @@ A space's own server code, edited in `functions/` with `pull`, `push`, `try` and
 | --- | --- |
 | `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 |
+| 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 |
 | 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

@@ -1,4 +1,4 @@
-# A space on Plitzi, as a project (`create --from`, `pull`)
+# A space on Plitzi, as a project (`create --from`, `pull`, `push`)
 
 `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:
@@ -21,3 +21,12 @@ and when one file changed on both it writes **nothing** and names them — keep
 `--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.
+
+`push` is the way back: what changed in the project, as the space's **draft** — publishing stays the builder's. At a
+terminal it lists the parts with what changed ticked; otherwise it sends what changed, or the parts named:
+`push space functions` (`space`, `functions`, `runtime`, `plugins`). Plugins go up first, then the functions, the
+runtime, and the pages, actions and connectors last. It is refused when the draft was edited in the builder since the
+project last had it — pull first, or `--force` to replace it — and a project that never had the space may only take a
+space nobody has worked on without `--force`. It pushes to the space the CLI is connected to, which must be the one
+the project came from, and records what it sent in `.plitzi/space.json`, so `pull` works afterwards — on a project that
+started on its own too.

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

@@ -1,4 +1,4 @@
-# A space's functions (`functions`)
+# A space's server code (`functions`, `runtime`)
 
 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
@@ -16,3 +16,16 @@ A space's own server code — TypeScript tasks its actions run as steps, and rou
 - **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 runtime (`runtime`)
+
+What a function cannot be — Node packages, a connection held open, state across requests — is the space's **runtime**:
+`src/runtime.ts`, default-exporting `defineRuntime` from `@plitzi/sdk-server/runtime` (its `.d.ts` documents it).
+
+- `runtime push` packs it (`--entry` for another file) as the draft's runtime; publishing deploys it. Its source goes
+  up with it, so `create --from` brings it back.
+- `runtime status` (`--json`) says how each environment's runs, and its variables' names. `runtime vars set NAME`
+  reads the value from stdin (`printf %s "$V" | …`), never echo it in a command line; `vars unset NAME` removes one.
+- `runtime size small|medium|large`, `stop`, `start` — the draft's unless `--environment` names a published one.
+- It needs a plan that includes runtimes and a private bucket on the space's CDN; a refusal says which is missing.
+