@plitzi/cli 0.37.8 → 0.37.10

package/README.md

@@ -10,6 +10,17 @@ npx @plitzi/cli pack plugin                    # a plugin built, and zipped the
 npx @plitzi/cli upload plugin                  # that zip, on the space you work in, and installed there
 ```
 
+## What every command does the same way
+
+- **The answer goes to stdout; everything else to stderr** — errors, and the prompts on the way (sign in, open this
+  address). So `--json`, where a command has it, prints one object on one line and nothing more.
+- **It exits 1 when it did not do what it was asked**, with why in red; a check that found something wrong exits 1 too.
+- **A value that is not one is refused**, saying what the flag takes — a width out of range, a scheme that is not
+  `light` or `dark`, a count of 0 — never quietly turned into the default.
+- **The same flag means the same thing everywhere:** `-o, --out` where it writes, `-f, --force` to write over what is
+  there, `-e, --environment` for which version of the space, `--width` for the widths a page is looked at (one, or
+  several separated by commas), `--api` for the platform, `--json` for a tool or an agent.
+
 ## `create`
 
 Scaffolds a project that renders a Plitzi space, installs it, and leaves it ready to start. Three choices shape it —
@@ -35,6 +46,22 @@ plitzi create my-site --yes                                           # at a ter
 plitzi create . --force --no-install --package-manager npm --mode server --source local   # into a directory that has work in it
 ```
 
+### From a space on Plitzi
+
+```bash
+plitzi create my-board --from pizarra                                        # the draft, as code
+plitzi create my-board --from pizarra --environment production --revision 3  # a snapshot, as it was frozen
+plitzi create my-board --from pizarra --source cloud                         # the pages stay on Plitzi
+```
+
+A server project holding everything the space is made of — its pages as authoring code, its actions as `defineAction`
+code (JSON, with the reason said, where one would not read back exactly), its functions, the source of its plugins and
+runtime, and its files downloaded into `public/` with every CDN address rewritten — served by the project with nothing
+of Plitzi's. `.env` gets a signing key made for it and the names of the variables and credentials the space had, never
+their values. It signs in as you and needs a space you may change; the end of `create` says what came across
+differently. What the project was given is recorded in `.plitzi/space.json` — commit it — for [`pull`](#pull). See
+`docs/en/projects-from-spaces.md`.
+
 ## The package manager
 
 `--package-manager npm|yarn|pnpm` says which one the project is written for: what it installs with, and what
@@ -88,7 +115,127 @@ when an install fails the CLI says which setting names it.
   `eslint-config-prettier` keeping the two from arguing on save. `lint` and `format` are scripts from the first
   commit, which is the only moment a repository's style is cheap to decide.
 - **The authoring skill**, in `.claude/skills/`, so an agent working in the project knows how a space is put
-  together before it touches one.
+  together before it touches one: a cheatsheet to start from, references by subject and recipes by intent — each a
+  file that authors with no warning. `.claude` is left out of the project's lint and formatting.
+- **`AGENTS.md`**: the commands, the port, where data goes, how to look at a page, and what not to read.
+- **Quiet output.** `author` prints one line when the space is fine (every problem with its code when it is not), the
+  server only what goes wrong (`npm start -- --verbose` for every request), `typecheck` one line per error. Under the
+  warnings, `author` prints the space's **suggestions**
+  (`[suggest] repeated-on-pages · … (saves 57) · src/pages/docs.ts:291`): a shorter way to the same page — a layout
+  for a header on every page, a component for a card copied with other words, a link's own `content` — the ones that
+  save the most first. Not problems: the space authors either way. `npm run author -- --json` carries them in
+  `suggestions`.
+
+## `create --template blank` and `--template catalog`
+
+A space written in the project starts as the welcome tour, with a plugin of the project's own. `--template blank`
+starts it as tokens for both themes, a layout whose `site-main` the pages render in, and one empty page — with
+`public/data/` and no example plugin — for a project that is about to be a specific site. `--template catalog` starts
+it as a complete small shop to read and change: a layout with a menu, a product card component, the products in
+`public/data/products.json` read as a typed source, a catalog filtered by category, and a page per product — a file
+per part under `src/site/`. Both go with `--source local`.
+
+## `check` and `shot`
+
+```bash
+plitzi check / --width 1440,390            # is the page whole? in text, per width; --json for a tool
+plitzi check /products --state --element catalog-count   # and what it holds: state, sources, one element
+plitzi shot /about --width 390 --scheme dark
+plitzi shot / --frames 4 --every 500       # what moves: a marquee, an autoplay
+plitzi shot / --compare https://example.com --width 1440   # side by side, and how much differs by section
+```
+
+Both run on the project's own Playwright against its running server (`npm start`), and refuse a port that answers as
+another project. `check` reports every element the space owes the page that is missing or hidden (with why), broken
+images, sideways scroll, text in the colour behind it, console errors and refused requests — a page's state in a few
+hundred tokens, where a screenshot costs thousands. `shot --compare` writes the two pictures side by side and the
+differences in red, and says the share that differs in each landmark of the page; `--frames` compares pictures taken
+one after another and names what moved. A project `create` writes has them as `npm run check` and `npm run shot`.
+
+## `fix`
+
+```bash
+plitzi fix            # what authoring would fix, as a diff of your own source
+plitzi fix --write    # written, formatted as the project formats, and checked
+```
+
+The fixes are the ones with a single reading (`fixSpace`'s: a key the element never reads, `'true'` where a boolean
+goes, a URL in page mode, a `state.` prefix on a state key…). Each is made in the call that wrote the element — found
+by the line and column the element remembers — and only where the value is written as a literal; anything else is
+listed with where it is and why it was left. `--write` authors the space again in a fresh process and keeps the edits
+only if every fix is gone and no problem was added; a fix that would add one is put back and said.
+
+## `import`
+
+```bash
+plitzi import https://example.com/pricing                 # into src/imported
+plitzi import https://example.com/ --out src/home --width 1440,390
+```
+
+A page you own or may reuse, measured in the project's own Playwright as a place to start writing from — never a copy
+of it. The widest width is desktop, the others tablet and mobile; the page is measured once more in the dark scheme.
+What lands in `--out`:
+
+- `tokens.ts` — the page's own custom properties by their names, then the colours it shows most, each with the value
+  the same place shows in the dark (the light one again, said in `IMPORT.md`, when it has no dark scheme); the corners
+  and shadows it repeats; its Google fonts. `variables`, `fonts` and `t` to hand to the space.
+- `outline.ts` — `container()`s for its landmarks and blocks, each with its layout per breakpoint written as what the
+  narrower widths change, colours as tokens, and a block hidden at a width as `display: 'none'` there. A repeated block
+  is written once, and its rows go to `data/<name>.json`.
+- `assets.json`, `screens/<width>.png`, and `IMPORT.md`: what was not carried over (the text, states, scripts, fonts
+  not on Google) and what to do next.
+
+It reads only a site that is yours: one served from this machine (a host that resolves to loopback), or one a verified
+domain of one of your spaces covers — the `_plitzi` TXT record a custom domain is verified by, under **Domains** in the
+dashboard, asked of the platform you are signed in to (`--api`). Anything else is refused before a page is opened.
+
+It refuses an `--out` that already has files unless `--force`, and then names the files an earlier import left that it
+did not write again.
+
+## `explain`
+
+```bash
+plitzi explain container        # an element: its attributes and their values, what it fires and answers, its slots
+plitzi explain navigate         # a step: its params and the function that writes it
+plitzi explain onScroll         # a trigger: what it hands its flow, and what fires it
+plitzi explain class-and-css    # a problem's code: what was wrong, what to write instead
+plitzi explain content-attribute # a suggestion's code: what is written the long way, and the short one
+plitzi explain --list steps     # every one of a kind: elements, steps, triggers, codes, transformers
+```
+
+What a name means when authoring, from the catalogues the checks themselves read — the answer to a question that would
+otherwise be a search through the SDK's types. `--json` answers in one object; over MCP it is `plitzi://explain/{name}`.
+
+## `skills update`
+
+The skills `create` copies into `.claude/skills/` say the version of the package they came from (`version:` in
+`SKILL.md`), and `npm run author` says when the authoring skill is older than the `@plitzi/sdk-authoring` installed.
+`plitzi skills update` replaces each Plitzi skill there with the one of the installed package — whole, so a reference it
+no longer has goes with it — and leaves any other skill alone.
+
+## `data describe`
+
+```bash
+plitzi data describe public/data/products.json          # its shape, and one row of its longest list
+plitzi data describe public/data/products.json --json   # { shape, example }
+```
+
+The fields of a JSON file, their types and which rows have them — `price?: number  (in 812 of 879)` — so a page can
+be bound to half a megabyte of data after reading twenty lines of it.
+
+## `pull`
+
+```bash
+plitzi pull                                    # the space's changes in, yours kept
+plitzi pull --force                            # where a file changed on both sides, the space's copy wins
+plitzi pull --environment production --revision latest   # follow another version from now on
+```
+
+In a project `create --from` wrote: a file the space changed and you did not is written, one you changed and the space
+did not is kept, one the space no longer has is removed unless you changed it. A file changed on both makes the pull
+write **nothing** and name them. Both sides are compared as the project's Prettier writes them. `.env` is never touched;
+`package.json` only gains the packages the space's code now asks for. It follows the version the project was made from —
+the draft, an environment's latest, or a pinned revision.
 
 ## `add plugin`
 
@@ -110,6 +257,18 @@ what the builder shows, and what it is for, and checks every folder is free befo
 
 A name that would make a built-in element's type (`button`, `form`) is refused: a space could not tell the two apart.
 
+Told its shape, it writes that shape rather than the counter it writes otherwise — one element at a time:
+
+```bash
+plitzi add plugin ticker --prop interval:number=5000 --prop paused:boolean --trigger onTick:count --callback reset --headless
+```
+
+`--prop name:type=default` (string, number or boolean) is an attribute: in the props, the declaration's defaults and
+`bindingsAllowed`, and a control in `Settings.tsx`. `--trigger onTick:count,at` is an event and what a flow started by
+it reads, fired with the `useTickerEvents()` hook it gets. `--callback reset` is an action a flow can call. `--headless`
+is an element with nothing to see: hidden on a page, a badge in the builder. The files are written as the project's
+Prettier writes them.
+
 ## `create --plugin`
 
 A plugin package: elements any space can load, with a Vite preview to write them in. It builds nothing itself —
@@ -149,12 +308,27 @@ Without folders, outside a package, it offers the elements in `src/plugins` —
 what a manifest is written from. `--out` moves the build, `--no-zip` leaves the zip out, and `--plugin-version` sets the
 version the manifest carries (the project's own by default).
 
+Beside the zip it writes the plugin's **source** (`<name>.source.json.gz`): every file of the project its elements import
+— followed with the project's own TypeScript, `import type` included — and the packages they need. `upload plugin`
+keeps it on the space, which is what `create --from` brings back. `--source-root` names the project those paths are
+relative to, when the elements are not a project of their own. A file outside it, a credentials file or a credential
+in the code keeps it from being written — said, and never stopping the build.
+
+## `pack source`
+
+```bash
+plitzi pack source src/runtime.ts --kind runtime --name runtime -o runtime.source.json.gz
+```
+
+What `upload plugin` and `runtime push` keep, written to a file to look at: the closure of the entries named, gzipped.
+
+
 ## `login`, `space` and `upload plugin`
 
 ```bash
 plitzi login          # sign in, in your browser
 plitzi space          # choose the space to work in, in your browser
-plitzi whoami         # who you are signed in as, and the space
+plitzi whoami         # who you are signed in as, and the space; --json for a tool
 plitzi upload plugin  # the zip pack plugin left, on that space
 plitzi logout         # the session revoked on the platform, and forgotten here
 ```
@@ -174,7 +348,8 @@ asked at a terminal). It is checked for its `plugin-manifest.json` before anythi
 without a space, the browser opens for what is missing, so the first upload is one command too. It goes on one of the
 space's public buckets — `--bucket <identifier>` (narrowed to one CDN with `--cdn <identifier>`), or asked when there
 are several; a private bucket is refused, since no page could load from it — and is installed, as the builder does when
-a zip is dropped under Resources: added, or the plugin already there moved to the new version with its settings kept.
+a zip is dropped under Resources: added, or the plugin already there moved to the new version with its settings kept. The
+source `pack plugin` wrote beside the zip goes up after it, into the space's private bucket.
 
 `--api` (or `PLITZI_API_URL`) points it at another platform, a self-hosted or local one; the CLI trusts the
 certificate authorities the system trusts, as the browser beside it does.
@@ -183,7 +358,7 @@ certificate authorities the system trusts, as the browser beside it does.
 
 ```bash
 plitzi runtime push                                   # pack src/runtime.ts and keep it as the space's draft runtime
-plitzi runtime status                                 # how each environment's runtime is, and its variables' names
+plitzi runtime status                                 # how each environment's runtime is, and its variables' names; --json
 printf %s "$URL" | plitzi runtime vars set REDIS_URL   # a value from stdin stays out of the shell history
 plitzi runtime vars unset REDIS_URL
 plitzi runtime size medium                            # the size the draft runs at (--environment for a published one)
@@ -203,7 +378,8 @@ from, and it runs as a server of its own too.
 `push` packs the module with the project's own `@plitzi/sdk-server` — the module and every package it imports, bar
 `@plitzi/*` and React, which the platform provides — and sends it to the space `plitzi whoami` names. It becomes the
 draft's runtime, which starts on it; **publishing the space** from the builder takes it to the published site. A
-runtime is part of the plans that carry it; on another, the push is refused and says so.
+runtime is part of the plans that carry it; on another, the push is refused and says so. The source it was
+packed from is kept beside it, and a publish freezes it with the code.
 
 **It runs at a size** — small (0.25 CPU, 256 MB), medium (0.5 CPU, 512 MB) or large (1 CPU, 1 GB) — chosen per
 environment among the sizes the space's plan includes. `status` says what each environment runs at and which sizes the
@@ -213,6 +389,21 @@ plan includes; `size` chooses another, and that runtime starts again at it.
 nothing idle, and stays stopped until `start`, the builder, a push or a publish starts it again. `status` says when a
 running one would stop, and why a stopped one is.
 
+## `functions`
+
+```bash
+plitzi functions pull                                              # the space's functions into functions/
+plitzi functions push                                              # functions/ saved as the space's draft, built and checked
+plitzi functions try seismic.feed --params '{"minMagnitude":"4"}'  # one task of the saved draft, in the sandbox
+plitzi functions dev seismic.feed --params '{}' --watch            # on this machine, as the platform runs it
+```
+
+A space's own server code — tasks its actions run as steps, routes under `/fn/` — and `functions/` is a working copy
+of it: `.plitzi/functions.json` keeps what was pulled, so `pull` refuses to overwrite what is not pushed (`--force`
+throws it away) and `push` refuses when the space moved on since. A problem comes back as
+`functions/<file>:<line> <message>`. `dev` runs with the project's own `@plitzi/sdk-server` (`isolated-vm` and
+`core-js` beside it); credentials come from `PLITZI_FUNCTIONS_CREDENTIALS`. See `docs/en/functions.md`.
+
 ## Credentials
 
 `create` never mints one. A cloud project's key comes from Credentials in the builder, is written to `.env`, and