@plitzi/cli 0.38.3 → 0.38.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +528 -0
  2. package/README.md +251 -49
  3. package/dist/index.js +8603 -3918
  4. package/package.json +4 -3
  5. package/skills/plitzi-cli/SKILL.md +59 -55
  6. package/skills/plitzi-cli/reference/from-space.md +16 -4
  7. package/skills/plitzi-cli/reference/functions.md +18 -4
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plitzi/cli",
3
- "version": "0.38.3",
3
+ "version": "0.38.5",
4
4
  "license": "AGPL-3.0",
5
5
  "description": "Command line for Plitzi: scaffold a project that renders a space, a plugin package, or an element of your own.",
6
6
  "files": [
@@ -21,17 +21,18 @@
21
21
  },
22
22
  "sideEffects": false,
23
23
  "dependencies": {
24
- "@plitzi/sdk-authoring": "0.38.3",
24
+ "@plitzi/sdk-authoring": "0.38.5",
25
25
  "chalk": "^6.0.1",
26
26
  "commander": "^15.0.0",
27
27
  "esbuild": "^0.28.2",
28
28
  "fflate": "^0.8.3"
29
29
  },
30
30
  "devDependencies": {
31
- "@plitzi/sdk-shared": "0.38.3",
31
+ "@plitzi/sdk-shared": "0.38.5",
32
32
  "@types/node": "^26.6.4",
33
33
  "eslint": "^9.39.5",
34
34
  "eslint-plugin-import": "^2.32.0",
35
+ "prettier": "^3.9.9",
35
36
  "typescript": "^6.0.3",
36
37
  "vite": "^8.3.2",
37
38
  "vitest": "^5.0.3"
package/skills/plitzi-cli/SKILL.md CHANGED
@@ -2,12 +2,11 @@
2
2
  name: plitzi-cli
3
3
  description: >-
4
4
  Use the Plitzi command line (@plitzi/cli, `plitzi …` or `npx @plitzi/cli …`) instead of hand-writing what it
5
- generates: scaffold a project that renders a space, add elements of your own (plugins) to it, create a plugin package,
6
- build a plugin into the module + manifest + zip the platform takes, sign in to upload and install it on a space, and
7
- edit a space's own server code (its functions) in the project, and take a space on Plitzi out as a self-hosted project
8
- of its own (`create --from`, kept in step with `pull`). Use whenever the task is to start a Plitzi project, create or
9
- change a plugin/custom element, pack, upload or install one, pull/push/try a space's functions, move a space to a
10
- server of its own, or work out which space the CLI is connected to.
5
+ generates: scaffold a project that renders a space, add plugins to it or build a plugin package, pack, upload and
6
+ install one, edit a space's functions, take a space on Plitzi out as a self-hosted project and back (`create --from`,
7
+ `pull`, `push`), and check a project (`doctor`) or how its space's source is written (`lint`). Use whenever the task is
8
+ to start a Plitzi project, create or change a plugin, pack, upload or install one, pull/push/try a space's functions,
9
+ move a space to a server of its own and back, or work out which space the CLI is connected to.
11
10
  ---
12
11
 
13
12
  # The Plitzi CLI
@@ -20,39 +19,42 @@ a signed-in upload. **Reach for it before writing any of those yourself.**
20
19
  npx @plitzi/cli create my-site # a project that renders a space (--template blank | catalog)
21
20
  npx @plitzi/cli create my-board --from pizarra # a space on Plitzi, as a project that serves it alone
22
21
  npx @plitzi/cli pull # that project brought up to date with its space
22
+ npx @plitzi/cli push # its changes back as the draft (or: push space functions)
23
23
  npx @plitzi/cli add plugin seat-picker legend # elements of your own, in the project you are in
24
24
  npx @plitzi/cli create seat-picker --plugin # a plugin package any space can load
25
25
  npx @plitzi/cli pack plugin # a plugin built, and zipped the way the builder takes it
26
26
  npx @plitzi/cli upload plugin # that zip, on the space you work in, and installed there
27
27
  npx @plitzi/cli whoami # who the CLI is signed in as, and the space it works in
28
- npx @plitzi/cli data describe public/data/products.json # a JSON file's fields, types and one row — not read whole
28
+ npx @plitzi/cli data describe src/data/x.json # a JSON file's fields, types and one row
29
29
  npx @plitzi/cli upgrade # the project up to this CLI: files, package.json, skills, renames (--write)
30
- npx @plitzi/cli upgrade skills --write # only one part: files | packages | skills | renames
31
- npx @plitzi/cli explain navigate # what a name means: element, step, trigger, problem or suggestion code (--list steps)
32
- npx @plitzi/cli functions pull # the space's functions (its own server code) into functions/
33
- npx @plitzi/cli functions push # functions/ back as the space's draft, built and checked
30
+ npx @plitzi/cli explain navigate # what a name means: element, step, trigger, code, helper (bindTemplate, motion)
31
+ npx @plitzi/cli functions pull # the space's functions (its own server code) into src/functions/
32
+ npx @plitzi/cli functions push # src/functions/ back as the space's draft, built and checked
34
33
  npx @plitzi/cli functions try feed.read --params '{"limit":3}' # one task of the saved draft, in the sandbox
35
- npx @plitzi/cli functions dev feed.read --watch # the same, from functions/, on this machine
34
+ npx @plitzi/cli functions dev feed.read --watch # the same, from src/functions/, on this machine
36
35
  ```
37
36
 
38
- `plitzi --help` and `plitzi <command> --help` list every flag; what follows is what the help does not say.
37
+ `plitzi <command> --help` lists every flag; what follows is what the help does not say.
39
38
 
40
39
  ## Running it as an agent
41
40
 
41
+ - **Which check.** The space as a document: `npm run author`. How its source is written: `npm run lint:space`. A
42
+ rendered page: `check`. The project around them (packages, configs, imports, plugins, data): `doctor`, before
43
+ `push`; `--fix` repairs the simple ones (an older project: `npx @plitzi/cli@latest doctor --fix`).
44
+
42
45
  - **After the SDK moves, `upgrade`.** It shows the CLI's files, scripts, versions and skills as they should be now, and
43
- every renamed name at its line. `--write` replaces what nobody changed, merges `package.json` and installs; a file
46
+ each renamed name at its line. `--write` replaces what nobody changed, merges `package.json` and installs; a file
44
47
  you changed comes as a diff — `--take <file>` once read.
45
48
 
46
49
  - **`create` never decides for the person.** Three choices shape a project — package manager, `--mode`
47
50
  (`server`: SSR + RSC on a Node tier, `client`: browser only) and `--source` (`local`: the space lives in the project,
48
51
  `cloud`: it lives in Plitzi). With nobody at the terminal it writes NOTHING and prints each missing choice as a
49
- question: ask the user, then run again with their answers as flags. `--yes` does not get around it — it only takes
50
- the defaults for a person at a terminal. Do not guess the answers.
52
+ question: ask the user, then run again with their answers as flags. `--yes` only takes the defaults for a person at
53
+ a terminal; never guess the answers.
51
54
  - **Signing in happens in the browser.** `login`, `space` and a first `upload` open one; the person completes it (MFA
52
- and social sign-in included — the CLI never sees a password). Tell them a browser tab is waiting, and wait.
55
+ and social sign-in included — the CLI never sees a password). Tell them a tab is waiting, and wait.
53
56
  - **One space at a time.** Everything goes to the space `whoami` names; `plitzi space` switches it. No command takes a
54
57
  space as a flag, so check `whoami --json` (`{ api, user, space }`) before an upload.
55
- - **`--no-install`** writes the files without installing, **`--force`** writes into a directory that has work in it.
56
58
  - **Read stdout, exit code and stderr apart.** The answer is on stdout (`--json`: one object, one line); errors and
57
59
  sign-in prompts are on stderr; exit 1 means it did not do what was asked, or a check found something. A flag value
58
60
  that is not one is refused with what it takes — read the message rather than retrying without the flag.
@@ -63,18 +65,18 @@ Where the space lives decides which one an agent uses — the two never take tur
63
65
 
64
66
  | The space | Use |
65
67
  | --- | --- |
66
- | In a project, written in code (`src/space.ts`, `--source local`) | this CLI and `@plitzi/sdk-authoring`. No account and no MCP |
68
+ | In a project, written in code (`src/space/`, `--source local`) | this CLI and `@plitzi/sdk-authoring`. No account and no MCP |
67
69
  | 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 |
68
- | On Plitzi, and wanted in code from now on | `create --from <space>`, then `pull` to keep the project in step |
70
+ | On Plitzi, and wanted in code from now on | `create --from <space>`, then `pull` and `push` keep both in step |
69
71
 
70
- The MCP needs a signed-in account. If it asks for authentication and nobody can give it, do not wait on it: a project
71
- with `--source local` needs neither.
72
+ The MCP needs a signed-in account; when nobody can give one, do not wait on it: a `--source local` project needs
73
+ neither.
72
74
 
73
75
  ## Projects (`create`)
74
76
 
75
77
  | | `--source local` | `--source cloud` |
76
78
  | --- | --- | --- |
77
- | `--mode server` | A page server of your own, rendering the space in `src/space.ts`. No account | Your page server, rendering the live space from Plitzi (secret self-hosting key in `.env`) |
79
+ | `--mode server` | A page server of your own, rendering the space in `src/space/`. No account | Your page server, rendering the live space from Plitzi (secret self-hosting key in `.env`) |
78
80
  | `--mode client` | Vite + the SDK in the browser, no server, no account | The SDK fetches the space with the public render key |
79
81
 
80
82
  What a project gives you, so you use it rather than rebuild it:
@@ -82,27 +84,30 @@ What a project gives you, so you use it rather than rebuild it:
82
84
  | Script | What it is for |
83
85
  | --- | --- |
84
86
  | `start` | serve it — in client mode Vite, which hot-replaces on save. The server prints only what goes wrong; `-- --verbose` adds every request |
85
- | `start:dev` | server mode: the server, restarted on save |
86
- | `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 |
87
+ | `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 |
88
+ | `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 |
89
+ | `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` |
87
90
  | `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 |
88
- | `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` |
89
- | `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 |
90
- | `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>` how much differs from another site by section; refused if the port is another project's |
91
+ | `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` |
92
+ | `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 |
93
+ | `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 |
91
94
  | `visual` | a browser asserts every element the space names is visible |
92
95
  | `typecheck`, `lint`, `format` | before calling a change done |
93
96
 
94
- **Which port.** `start` takes 8080, or the next free one when something else holds it — printed, and written to
95
- `.plitzi/dev-server.json`, where `check`, `shot` and `visual` look for it. Set `PORT` to choose one (then a taken port is an
96
- error). `/health` answers with the space's name: a server that answers as something else is not this project.
97
+ **Which port.** `start` takes 8080, or the next free one — printed, and written to `tmp/dev-server.json` for `check`,
98
+ `shot` and `visual`. `PORT` chooses one (a taken one is then an error). `/health` answers with the space's name.
99
+
100
+ Data with no backend, server mode: `src/data/*.json`, never served — a provider with `runtime: 'server'` and `query:
101
+ '/data/x.json'` reads it on the server. Client mode: `public/data/`, fetched — public. Learn a file's fields with
102
+ `data describe`, never by reading it.
97
103
 
98
- The data a page reads with no backend goes in `public/data/*.json`, served by the project as it is; in server mode a
99
- provider with `runtime: 'server'` reads it on the server, so the page arrives with it. To bind to a file, learn its fields
100
- with `data describe` rather than reading it: a catalogue is half a megabyte, its shape twenty lines.
104
+ **`public/` is on the internet**: never a secret there. `tmp/`, `state/` (its `kv`) ignored; `.plitzi/` committed.
105
+ `--dry-run` on a command that writes or sends says what it would do, and does none of it.
101
106
 
102
- A local space starts as a tour of the platform with a plugin of the project's own; **`--template blank`** starts it as
103
- tokens, a layout and one empty page instead — the one to pick when the project is about to be a specific site; and
104
- **`--template catalog`** as a complete small shop (layout, card component, data in `public/data`, a filtered list, a
105
- page per product), a file per part — the one to read when unsure how a whole site is put together.
107
+ A local space starts as a tour of the platform with a plugin of the project's own; **`--template blank`** as tokens, a
108
+ layout and one empty page — for a project about to be a specific site; **`--template catalog`** as a small shop
109
+ (layout, card component, data in `src/data`, a filtered list, a page per product), a file per part — the one to read
110
+ when unsure how a whole site is put together.
106
111
 
107
112
  The space itself is written with `@plitzi/sdk-authoring` — see the `plitzi-authoring` skill, which `create` copies into
108
113
  `.claude/skills/` beside this one.
@@ -126,11 +131,10 @@ plitzi add plugin seat-picker --title "Seat Picker" --description "Pick a seat f
126
131
  plitzi add plugin ticker --prop interval:number=5000 --prop paused:boolean --trigger onTick:count --callback reset --headless
127
132
  ```
128
133
 
129
- **Say its shape and it is written in it**, with nothing to delete: `--prop name:type=default` (string, number,
130
- boolean) for each attribute — typed, defaulted, bindable, with a control in its panel; `--trigger onTick:count` for
131
- each event and what a flow reads from it, fired with the `use<Name>Events()` hook it gets; `--callback reset` for
132
- each action a flow can call; `--headless` for one with nothing to see (hidden on a page, a badge in the builder).
133
- Without them it writes a counter that shows the three ways an element talks to a space — to be rewritten.
134
+ **Say its shape and it is written in it**: `--prop name:type=default` (string, number, boolean; `list`/`json` for data
135
+ a binding fills) per attribute — typed, bindable, with a control in its panel; `--trigger onTick:count` per event and
136
+ what a flow reads, fired with its `use<Name>Events()` hook; `--callback reset` per action a flow calls; `--headless`
137
+ for one with nothing to see. Without them it writes a counter showing the three ways an element talks to a space.
134
138
 
135
139
  Each is a folder (`src/plugins/SeatPicker/` in a project `create` wrote):
136
140
 
@@ -143,15 +147,16 @@ Each is a folder (`src/plugins/SeatPicker/` in a project `create` wrote):
143
147
 
144
148
  - **Registered by itself**: every folder of `src/plugins` is, under its name in camelCase (`SeatPicker` → `seatPicker`).
145
149
  Elsewhere the command prints the line that registers it (for `render()`, `<PlitziSdk>` or a page server).
146
- - **Host it** with `custom({ renderType: 'seatPicker', … })` in `src/space.ts` — or a Custom element in the builder.
147
- - **Checked like a built-in element**: `add plugin` also lists its declaration in `src/plugins/declarations.ts`, which
148
- every place the project authors the space hands to `authorSpace(space, { plugins: declarations })`. Flows on its
149
- events, steps to its actions and its attributes are refused when wrong; `declaredTrigger(declaration, 'onPick')` and
150
- `declaredCallback(declaration, 'reset', { on: 'seats' })` build those steps, typed from the declaration. A plugin
151
- written by hand is added to that list with its `declaration.ts`.
150
+ - **Host it** with `custom({ renderType: 'seatPicker', … })` in `src/space/` — or a Custom element in the builder.
151
+ - **Checked like a built-in element**: its folder's `declaration.ts` is found by itself and handed to
152
+ `authorSpace(space, { plugins })`: flows on its events, steps to its actions and its attributes are
153
+ refused when wrong; `declaredTrigger(declaration, 'onPick')` and `declaredCallback(declaration, 'reset', { on: 'seats' })`
154
+ build them typed. A plugin written by hand is added to that list.
152
155
  - **A new event or action** is declared in `declaration.ts` and registered by the component FROM there — never only
153
156
  in the component, or neither the builder nor the linter knows it exists.
154
157
  - A name that is a built-in type (`button`, `form`) is refused: a space could not tell the two apart.
158
+ - **A server half** (`--server`): `functions/index.ts` in its folder — routes under `/fn/plugins/<type>/`
159
+ (`usePluginRoute`), steps `<type>.<action>`, its own `kv`, none of the space's credentials.
155
160
 
156
161
  ## Plugin packages (`create --plugin`)
157
162
 
@@ -189,10 +194,10 @@ The same server decides its own say over the space's **feature flags**: `createS
189
194
  flags the space declares — and is overridden by the SDK's `flags` prop and a tester's dev tools. Declaring the flags
190
195
  themselves is the space's (`flags` in the spec; see the authoring skill's feature flags).
191
196
 
192
- ## A space's functions (`functions`)
197
+ ## Server code (`functions`, `runtime`)
193
198
 
194
- A space's own server code, edited in `functions/` with `pull`, `push`, `try` and `dev`: read
195
- [reference/functions.md](reference/functions.md) when the task names its functions.
199
+ A space's own server code, edited in `src/functions/` (`pull`, `push`, `try`, `dev`) or run as its runtime
200
+ (`src/runtime/`, `add runtime`, `runtime push`): read [reference/functions.md](reference/functions.md) for either.
196
201
 
197
202
 
198
203
  ## When something does not work
@@ -201,9 +206,8 @@ A space's own server code, edited in `functions/` with `pull`, `push`, `try` and
201
206
  | --- | --- |
202
207
  | `create` printed questions and wrote nothing | nobody answered the three choices — ask the user, pass them as flags |
203
208
  | `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 |
204
- | 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 |
205
- | An element renders "Custom Component … Not Found" | the `renderType` names no registered plugin — check the folder name's camelCase |
206
- | 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` |
209
+ | 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 |
210
+ | "Custom Component … Not Found", or a flow on a plugin's event never runs | `doctor` names the folder whose type or declaration is off |
207
211
  | `upload` opens a browser | there is no session, or no space chosen — the person completes it there |
208
212
  | The upload went to the wrong space | `plitzi space` chooses another; check `whoami` first |
209
213
  | `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/from-space.md CHANGED
@@ -1,4 +1,4 @@
1
- # A space on Plitzi, as a project (`create --from`, `pull`)
1
+ # A space on Plitzi, as a project (`create --from`, `pull`, `push`)
2
2
 
3
3
  `create --from <space>` (its permanent URL or id) writes a server project holding everything the space is made of, and
4
4
  serving it with nothing of Plitzi's — neither its servers nor its CDN:
@@ -6,18 +6,30 @@ serving it with nothing of Plitzi's — neither its servers nor its CDN:
6
6
  - its pages as authoring code in `src/space/` (`--source cloud` writes none: they stay on Plitzi, read with a key);
7
7
  - its actions in `src/actions/` — each a `defineAction` call where the document reads back exactly, JSON where it does
8
8
  not (the report says why) — and its connectors as JSON;
9
- - its functions in `functions/`, its runtime and plugins as the source they were built from, under `src/`;
10
- - its files downloaded into `public/`, every CDN address rewritten to the project's own;
9
+ - its functions in `src/functions/`, its runtime and plugins as the source they were built from, under `src/`;
10
+ - its data in `src/data/` (read by its server providers, never served);
11
+ - its files downloaded into `public/assets/`, every CDN address rewritten to the project's own;
11
12
  - `.env` with a signing key made for it, and the names of the variables and credentials it needs — never their values.
12
13
 
13
14
  It takes a signed-in CLI and a space the person may change (owner, admin or writer). It takes out the draft unless
14
15
  `--environment production` (that environment's latest snapshot) or `--environment production --revision 3` (that one,
15
16
  pinned) says otherwise. Read the report it prints: a
16
17
  plugin or runtime uploaded before Plitzi kept sources comes across built only (`vendor/`), and a space with visitor
17
- roles needs sign-in of its own (the note in `src/main.ts`).
18
+ roles needs sign-in of its own (the report says how).
18
19
 
19
20
  `pull` brings the project up to date: what changed on the space alone is written, what changed here alone is kept,
20
21
  and when one file changed on both it writes **nothing** and names them — keep your changes aside and pull again, or
21
22
  `--force` to take the space's copy. It never touches `.env`, and only adds to `package.json`. What the project was given
22
23
  is recorded in `.plitzi/space.json`: commit it. It follows the version the project was made from; `pull --environment
23
24
  … --revision …` moves it to another, `--revision latest` lets go of a pin.
25
+
26
+ `push` is the way back: what changed in the project, as the space's **draft** — publishing stays the builder's. At a
27
+ terminal it lists the parts with what changed ticked; otherwise it sends what changed, or the parts named:
28
+ `push space functions` (`space`, `functions`, `data`, `runtime`, `plugins`, `files`). Plugins and the files of
29
+ `public/assets/` go up first (each file at the same path under the space's `assets/`), then the functions, the data, the
30
+ runtime, and the pages, actions and connectors last. Only `public/assets/` reaches the space's CDN: put a file the space
31
+ names there, never elsewhere in `public/`. It is refused when the draft was edited in the builder since the
32
+ project last had it — pull first, or `--force` to replace it — and a project that never had the space may only take a
33
+ space nobody has worked on without `--force`. It pushes to the space the CLI is connected to, which must be the one
34
+ the project came from, and records what it sent in `.plitzi/space.json`, so `pull` works afterwards — on a project that
35
+ started on its own too.
package/skills/plitzi-cli/reference/functions.md CHANGED
@@ -1,18 +1,32 @@
1
- # A space's functions (`functions`)
1
+ # A space's server code (`functions`, `runtime`)
2
2
 
3
3
  A space's own server code — TypeScript tasks its actions run as steps, and routes under `/fn/` — lives in the space;
4
- `functions/` in a project is a **working copy** of it. The contract (`defineFunctions`, `ctx`) is typed in
4
+ `src/functions/` in a project is a **working copy** of it. The contract (`defineFunctions`, `ctx`) is typed in
5
5
  `@plitzi/sdk-server/functions`, whose `.d.ts` documents every field; what matters for the CLI:
6
6
 
7
7
  - **Pull before you edit, push when done.** `pull` refuses to overwrite what is not pushed (`--force` throws it
8
8
  away); `push` refuses when the space changed since the pull — someone saved in the builder. Then: keep your changes
9
9
  aside, `pull`, apply them again, `push`. Never `--force` over somebody else's work to get past it.
10
- - **A push is checked, not just stored.** A problem comes back as `functions/<file>:<line> <message>` and nothing is
10
+ - **A push is checked, not just stored.** A problem comes back as `src/functions/<file>:<line> <message>` and nothing is
11
11
  saved — fix it and push again. `index.ts` must default-export `defineFunctions({ … })`; files import each other by
12
12
  relative path and `@plitzi/sdk-server/functions`, nothing else.
13
- - **`try` runs the saved draft for real** (its fetches and writes happen). `dev` runs `functions/` on this machine with
13
+ - **`try` runs the saved draft for real** (its fetches and writes happen). `dev` runs `src/functions/` on this machine with
14
14
  the project's own `@plitzi/sdk-server` — `npm install -D @plitzi/sdk-server isolated-vm core-js` first — and sends
15
15
  nothing to the space; `PLITZI_FUNCTIONS_CREDENTIALS='{"stripe":{"apiKey":"…"}}'` gives it credentials to name.
16
16
  - **A run gets 100 ms of CPU and 10 s.** A task that needs more asks with `limits: { cpuMs, wallMs }` (or
17
17
  `defineFunctions({ limits })` for all), up to the plan's ceiling; asking above it is a problem the push reports.
18
18
  - **The live site runs what the space was last published with.** A push changes the draft; publishing is the person's.
19
+
20
+ ## A space's runtime (`runtime`)
21
+
22
+ What a function cannot be — Node packages, a connection held open, state across requests — is the space's **runtime**:
23
+ `src/runtime/index.ts` (`plitzi add runtime`), default-exporting `defineRuntime` from `@plitzi/sdk-server/runtime` (its
24
+ `.d.ts` documents it). The project's server runs it as Plitzi does, so try it with `npm start` before pushing.
25
+
26
+ - `runtime push` packs it (`--entry` for another file) as the draft's runtime; publishing deploys it. Its source goes
27
+ up with it, so `create --from` brings it back.
28
+ - `runtime status` (`--json`) says how each environment's runs, and its variables' names. `runtime vars set NAME`
29
+ reads the value from stdin (`printf %s "$V" | …`), never echo it in a command line; `vars unset NAME` removes one.
30
+ - `runtime size small|medium|large`, `stop`, `start` — the draft's unless `--environment` names a published one.
31
+ - It needs a plan that includes runtimes and a private bucket on the space's CDN; a refusal says which is missing.
32
+