@plitzi/cli 0.37.8 → 0.37.9

package/package.json

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

package/skills/plitzi-cli/SKILL.md

@@ -4,9 +4,10 @@ description: >-
   Use the Plitzi command line (@plitzi/cli, `plitzi …` or `npx @plitzi/cli …`) instead of hand-writing what it
   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. 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, or work out
-  which space the CLI is connected to.
+  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.
 ---
 
 # The Plitzi CLI
@@ -17,6 +18,8 @@ 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-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
 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
@@ -64,6 +67,30 @@ What a project gives you, so you use it rather than rebuild it:
 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`).
+
+`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`)
 
 A plugin is a React component the space renders — a map, a chart, a seat picker: whatever is not text in a box. **Never
@@ -121,14 +148,16 @@ plitzi upload plugin                            # the zip pack left, onto the sp
 `pack` writes one ES module (React and the SDK kept out — the page provides them), `plugin-manifest.json` from the
 declarations with integrity hashes, and the zip the builder takes under Resources. `upload` checks the manifest,
 sends the zip to one of the space's CDNs (`--cdn`) and installs it — a plugin already there moves to the new version with
-its settings kept. `--plugin-version` sets the version the manifest carries.
+its settings kept. `--plugin-version` sets the version the manifest carries. The plugin's source — every file it
+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 space's functions (`functions`)
 
-A space's own server code — TypeScript tasks its actions run as steps, and routes under `/api/` — lives in the space;
+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:
 
@@ -141,6 +170,8 @@ A space's own server code — TypeScript tasks its actions run as steps, and rou
 - **`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.
 
 ## When something does not work
@@ -152,3 +183,4 @@ A space's own server code — TypeScript tasks its actions run as steps, and rou
 | 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 |
 | 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` |