@datarails-ai/dr-appspace-cli 0.9.1

package/README.md

@@ -0,0 +1,346 @@
+# dr-appspace — the Datarails App Space CLI
+
+One binary, one job: **App Space** — build, try, push and publish App Space
+apps. Nothing else of the Datarails system is exposed here; for everything
+else, use `dr` (dr-cli). (The read-only dr-cli command groups this package
+used to carry were removed — combining CLI capabilities is handled
+elsewhere now.)
+
+```
+npm install -g @datarails-ai/dr-appspace-cli --registry https://datarails.jfrog.io/artifactory/api/npm/dr-cli-virtual
+dr-appspace login -s DEV
+dr-appspace app-space whoami -s DEV
+```
+
+## What's inside
+
+- **Auth — identical to dr-cli** (the code is a port of dr-cli's auth stack):
+  OAuth device-flow `login`, sessions in the OS keychain (service
+  `dr-appspace-cli`, keyed by `(server, email)`), automatic JWT refresh with
+  the full 401 recovery ladder, and the **credential-file store** for
+  keychain-less hosts (CI, containers, managed agents): when
+  `~/.dr/session.json` (or `$DR_CREDENTIALS_FILE`) exists it wins over the
+  keychain. The file contract is byte-compatible with dr-cli's
+  (`{access, refresh, server, email}`), so one provisioning step signs in
+  both CLIs — the same `dr_cli_auth.json` mount ai-service already provides
+  to managed agents works here unchanged.
+- **`app-space` commands** (ported from `dr-dev-cli app-space`, re-based onto
+  this auth): `whoami`, `list`, `get`, `logs`, `try`, `push`, `publish`,
+  `unpublish` — plus `scaffold`, `preview`, `test`, `contract`, `compile` and
+  `eject`.
+
+### A handler that takes a file
+
+`try` and `test` can put a file in front of a handler, the way the page does:
+upload it through the app's upload route, then send the signed reference as
+`{"<field>": {"upload": "…"}}`.
+
+```
+dr-appspace app-space try upload_invoice --file pdf                   # the built-in sample invoice PDF
+dr-appspace app-space try upload_invoice --file pdf=./acme-0417.pdf   # a file of yours
+dr-appspace app-space try upload_invoice --file pdf --payload @./payload.json
+```
+
+`--file <field>[=<path>]` is repeatable; a field that is not a `file` column
+of any table in `data_model.json` gets a warning, not a refusal. `--payload
+@<path>` reads the whole payload from a JSON file. Paths are relative to the
+working directory. The sample invoice (`INV-0417`, Acme Office Supplies Ltd,
+subtotal 165.00, tax 33.00, total 198.00) is a one-page ASCII PDF generated in
+`src/commands/appspace/_samplePdf.ts`.
+
+`test` hands the same sample PDF to every form's file field, and a
+`tests.json` case may upload files before its dry-run:
+
+```json
+{"handlers": {"upload_invoice": [
+  {"name": "reads the sample invoice", "payload": {}, "files": {"pdf": "sample"},
+   "shape": {"row": {"id": "string", "status": "string"}}}
+]}}
+```
+
+A `files` value is `"sample"` (reserved: the built-in sample invoice) or a
+path inside the app folder; a path whose real location is outside the
+folder, through a symlink too, is refused. Every file is read before any is
+uploaded. Each upload stores a real file, as a browser upload does, so a
+handler that hands it to an agent runs that agent on every `test`.
+
+`compile` knows a `chart` component: a root element that draws the rows one
+`list`, `inbox` or `custom` handler answers (`source`), as a `line`, `bar` or
+`area` (`kind`), with `x` on the category axis, the one numeric column `y`,
+an optional `series` column (one line per distinct value) and an optional
+`format` (`currency`, `number`, `percent`; absent, a decimal `y` reads as
+currency). Over a `list` or an `inbox` its columns are checked against the
+table; over a `custom` handler `--check` prints `Not checked: chart columns
+of …`, and `app-space test` checks what the handler answers: a `chart-empty`
+finding when the source answered no rows (ungated for a custom handler; over
+a list or an inbox, only when `seed.json` says it should have rows), no
+`rows` array, or rows that carry no `x`/`series` key or no number under `y` —
+naming the keys it did return (names only; no value leaves the run). Like
+every finding it fails the run only under `--strict`. A page holding a
+chart loads `echarts@5.6.0` and `dr-fmt@1.0.0` from the shelf before
+`dr-app-runtime@1.1.5`. An older CLI's `get` drops the element.
+
+A dashboard can be **assembled** rather than typed. `compile --draft
+<spec-draft.json>` builds `contract.json` from the dashboard's skeleton
+(`--skeleton <file>`, or the draft's own `skeleton` key) and one SPEC draft
+per page — each card's `props` and SPEC `row`, plus its `page`, `reads`,
+`datasets` and `capabilities` — and then compiles it like any other. The
+frame is the CLI's: the first page is `ui/index.html` at `/`, every other
+`ui/<name>.html` at `/<name>.html`, the skeleton's sections and card order,
+a page not built yet carries one card saying it comes next, and — only
+when the draft states it as `page.window` — the window every page opens on
+(`mount.defaults.filters.period`), which `preview` and the post-push load
+apply too. A draft or contract where every card opts out of the period bar
+is refused (`assemble-period-override` / `period-override`). With a `contract.json` already in the folder a draft replaces only its
+own page — except that a draft carrying `page.window` also moves every
+page's opening window, because one `widget.js` serves them all. `--check` assembles in memory and writes nothing; a draft it cannot
+place is `assemble-*`, exit 1. `--app-id <id>` names the app a first pass is
+for, and `--expect <card>=<figure>` holds a card to the figure the user
+confirmed once the package runs (exit 6 when it does not).
+
+```
+app-space ship [dir] --draft spec-draft-cfo.json --app-id app-7k2m3f --expect revenue=870,000
+```
+
+`ship` is one pass of a dashboard build as one command — `compile --push`
+over the assembled contract, R5 over every card, the `--expect` check — and
+after a run that passed it prints the `appspace_app_update` block a build
+agent's reply ends with, from the revision the push printed (`compile
+--update-block` prints it too). After any failure it prints none.
+
+`compile` also knows the two ways a file becomes the author's rather than
+the compiler's, besides a `custom` handler:
+
+- a **`custom` element** — `{"type": "custom", "props": {"module":
+  "components/<name>.js", "source": "<handler>", "args": {…}}}` — drawn by
+  `ui/components/<name>.js`, which calls `drApp.define("components/<name>.js",
+  {render(el, data, ui) {…}})` (`dr-app-runtime@1.1.6`; `ui` carries `args`,
+  `fmt`, `call`, `refresh`, `chart` and `theme`). `args` must be an object;
+  `module` is required.
+- an **owned page** — `pages[i].owned: true` — whose markup is the file at its
+  path, carrying `<meta name="dr-owned" content="true">`. An optional
+  `pages[i].role` gates its nav entry, as a compiled page's screens do.
+
+Both are compiler INPUTS, like a custom handler: they must be in the folder,
+`compile` never writes them (not even under `--force`), records them under
+`inputs` in `.appspace/compile.json`, never removes one as orphaned, and
+`--check` carries them into its scratch package. A `ui/components/*.js` no
+custom element names is refused like a stray handler — a push would ship it.
+`app-space test` reports `custom-undefined` when a module never called
+`drApp.define` for itself, `custom-failed` (with the module and the error)
+when its component threw while drawing and the runtime drew its
+`<module> failed: <message>` panel, and reads no layout rule into an owned
+page. A custom element whose `declares.shows` names a number nothing inside
+it projects once it drew (no `[data-dr-field]` for it) is
+`custom-shows-unprojected` — a counted finding, so `--strict` fails on it: a
+number no grader can read is not a measured one.
+
+A card the contract gives no `props.label` is `card-untitled`, one per
+element: the runtime titles it anyway — after its field, its id, or its
+module, y column, source, entity (a form reads "New") — so a builder who
+never named it ships a card called "Whatif":
+
+```
+[card-untitled]  ui/cockpit.html → ui/cockpit.html#10: custom "whatif" has no label, so its card is titled "Whatif" after its id. Fix: give it props.label (what a reader should call this card). (contract.md §3.4 Pages)
+```
+
+It reads the contract alone, for what a page draws as its own — its roots
+and what sits in a region or a tab panel: `custom`, `chart`, `widget`,
+`stat`, `list`, `queue`, `form`, and the parts that draw their label
+(`dialog`, `number_input`, `select`, `date_picker`; a typed
+`props.props.label`, or a dialog's `props.props.title`, names them). An
+element's `card.title` names any of them (runtime 1.4.0's CardFrame draws
+it); a widget's `props.title` does not — the runtime never reads it. A
+field, a nav, a region, a tab panel, `tabs`, `data_grid` and
+`variance_table` draw no title of their own and are never reported. Apps
+only; counted, so `--strict` fails on it.
+
+A page may declare its own params (`pages[i].params`, the seven kinds
+`dr-app-runtime@1.4.0`'s param store reads) and a source take them by name
+in `honors`. Every source handler of such an app carries `PARAMS` — every
+page's declarations — into `sources.serve(…, TRANSFORMS, PARAMS)`, so a
+transform's `params` holds only values the page declared; an app no page of
+which declares one compiles exactly as before. A `dimensions:<Name>` honour
+fills the source's `filterable`. `compile` refuses, with a pointer:
+`param_custom_multi` / `param_custom_period` (a custom name of kind `multi`
+or `period` — only `scenario`, `dimensions:<Name>` and `period` take those),
+`param_kind_value` (a default, `min`/`max`/`step`, `values` or
+`max_selected` its kind cannot hold), `param_conflict` (one name, two rules)
+and `param_unknown_honor` (a source honours a name no page declares).
+
+The look layer (runtime 1.4.0) is optional and per key: a band may state a
+`subtitle`, a `layout` (`stack | grid | kpi_strip | split | sidebar |
+hero`), a `surface` (`none | tinted | inverse`) and a sidebar's `aside`
+(`start | end`); an element a `card` (`{variant: plain | outlined | elevated
+| accent, title, subtitle}`) and an `emphasis` (`low | normal | high`).
+`app.theme` (`{file: "ui/theme.css", tokens, preset?, density?}`) compiles
+to `ui/theme.css` on `body.dr-app-page` in the `--dr-app-theme: full` form —
+the `--dr-*` tokens and the shadcn triples computed from them by the
+runtime's own map (`contract/themeMap.gen.mjs`, generated from
+`tokens.mjs`) — linked after every shelf stylesheet; `preset` and `density`
+become each page's `data-dr-theme` / `data-dr-density` where the page states
+none. A theme `compile` cannot write is `theme_shape`.
+
+`app-space test` holds every declared param to two counted findings, read
+statically from the embedded contract and the pushed modules
+(`contract/levers.mjs`, the App kit's A3.17/A3.18): `control-unbound` — no
+control on the page writes it (no part in param mode, no custom whose module
+calls `ui.setParam("<name>", …)` or whose `declares.produces` names it), so the
+page only ever shows its default — and `param-unread` — no source a component
+on the page reads honours it, directly or through what it is composed of, and
+no custom module reads it off `ui.params`: moving it changes nothing. A page
+with a module the run could not read, or a `ui.setParam` whose name is not a
+literal, is not reported on. The App kit reports A3.18 as a violation and
+A3.17 as a warning until dr-components ships param-mode controls.
+
+It then RUNS each lever. On every page that declares params, once the page
+has loaded (and before any form is submitted), `app-space test` moves one
+param at a time through the page's own URL — `#p=` +
+`encodeURIComponent(JSON)` of that one param, then `hashchange`, which
+runtime 1.4.0's param store reads — and compares what the page draws with
+what it drew at the defaults, NUMBERS only: every `data-dr-value` a part or
+custom projects that reads as a number (never a control's own value, nor a
+value whose field is the moved param), the figures in a stat's text (only
+when the stat projects no `data-dr-value`; its dates and periods — `2026-01`,
+`01/2026`, `Aug 2026`, `Q1 2026` — dropped, and any figure equal to the value
+the param was at or moved to dropped as an echo), and the numbers in each
+chart's series `data` as handed to echarts, gaps dropped. Labels never count
+— a chart's categories, its series names, a month or a name in a cell or a
+stat — so a start month that only relabels the months, every value the same,
+is static. A number moves to its `max` (else double its default,
+else default + `step`), a month one month on, a toggle flips, a select takes
+another value, a multi another subset. A param whose first value moved no
+number is moved once more — the other end of its range (else default +
+`step`), a month one month back, another select value or subset — since a
+lever can be inert at one end. Only a param neither value moved is
+`lever-static`, counted: `ui/index.html: moving param "hires" (5 → 20, and
+5 → 0) changed no number on the page — its sources honour it, but nothing
+drawn depends on it. Fix: Check the transform reads params.get("hires")
+(transforms/plan.py) …`. `--json` carries `levers: [{page, param, from, to,
+second?, moved: [uid…]}]` (plus `inconclusive` for a lever it could not
+judge). The moved reads go to the pushed app's real handlers, so the
+transforms run with the moved params; a lever this run could not judge —
+`--skip-ui`, a page that did not load, a move no source that honours the
+param re-read after (a missed `hashchange`, a debounce past the grace — a
+refetch of some other source does not count), a read that failed or was
+still running with the param moved, a page that drew no number at its
+defaults, a budget that ran out before the second value — is a `Not checked` line naming the param, never a pass and never
+`lever-static`. Cost: one settle per declared param,
+a second for each that moved nothing at its first value, plus one to move
+back, on the page already mounted (the first render of each page only).
+
+Roles are declared least senior first and the app's creator holds the last
+one. `compile` refuses a list that reads the other way (`role-order`: the
+default not first, or a creator's role that cannot call a handler the default
+can), and `app-space test` reports `role-sees-nothing` when the app gates
+components to roles and none of them to the role you hold — the page you open
+is then only the ungated rest, although every render as the other roles
+passes.
+
+Before its findings, `app-space test` says how much of the pushed app is the
+registry's and how much the builder's own code:
+
+```
+parts: 5 registry, 0 custom UI (0 lines), 0 custom handlers (0 lines), 2 transforms (30 lines) — 0% custom
+```
+
+Custom UI is each `custom` element (with its modules' lines), a custom handler
+each `custom`-role handler (with its lines), and a transform each file under
+`transforms/` that `data.sources` names (once, however many sources share it,
+by its non-blank lines — read out of the generated source handlers, which carry
+it). The percent is custom UI's share of the components and nothing else.
+`--json` carries the same counts as `parts`, the transforms as
+`parts.transforms: {count, lines}`. A dashboard's line names no transforms.
+
+`app-space eject <target> [--dir <dir>]` writes the starting file:
+
+```
+dr-appspace app-space eject handler:list_my_invoices      # handlers/<name>.py as compiled, role "custom"
+dr-appspace app-space eject page:ui/queue.html            # the compiled page, marked owned; its elements leave the contract
+dr-appspace app-space eject element:ui/overview.html#13   # a chart or a stat becomes a custom element + its module
+```
+
+It compiles in memory, writes only the ejected file and `contract.json`,
+refuses a file already at that path unless it holds exactly what the
+compiler would write, and refuses an eject after which the folder would not
+compile (a page holding the only form a `by` handler is called from, a
+handler a picker needs as a list). `page:` keeps the page's nav gate as
+`pages[i].role`; an ejected handler's docstring says the file is yours.
+The next `compile` carries the file as yours, and the one after writes
+nothing.
+
+### Which kit made the app: `push --kit`
+
+`push` can name the builder kit that made the package, so the platform's
+contract record (`app_contract.kit_version`) says which kit built each app
+rather than the extractor's stamp, `dashboard-kit/contract@1`, which every
+kit shares:
+
+```
+dr-appspace app-space push --kit appspace-app-kit@12
+DR_APPSPACE_KIT=appspace-app-kit@12 dr-appspace app-space push
+```
+
+The value travels as the push body's optional `kit` field. `--kit` wins over
+`DR_APPSPACE_KIT`; with neither set (or either left blank) the field is left
+out, and the platform records the contract's `generated_by` as before.
+`compile --push`, `ship` and `compile --check` build the same body, so they
+honour the variable too; they have no `--kit` flag of their own. The platform
+checks the shape: `<name>@<number>`, the name in `a-z`, `0-9` and `-`, 64
+characters at most. Anything else is a 422 naming that shape. The field is a
+column on the record and nothing else: the contract document, the compiled
+pages and the dashboard are the same with or without it. The builder flows
+set `DR_APPSPACE_KIT` in their sandboxes.
+
+**Push before `get`**: `get` replaces `handlers/` and `ui/` with what the
+platform holds, and refuses (unless `--force`) while the compile record lists
+files as yours that the pushed package does not hold as written.
+
+This package ships **no skill and no generator**. The guidance an agent reads
+lives in dr-assets-service, attached to the agent by id — see the repo's
+`CLAUDE.md`. Nothing here installs, prints or bundles a `SKILL.md`, and no
+command calls a model: the builders write `contract.json` themselves and run
+`app-space compile`.
+
+## Development
+
+This package lives inside the dr-app-space repo but is independent of the
+Python service: its own `package.json`, pnpm lockfile, and CI
+(`.github/workflows/cli-checks.yml`).
+
+```
+cd cli
+pnpm install
+pnpm dev -- --help     # run from source
+pnpm typecheck && pnpm test
+pnpm build             # dist/cli.js
+```
+
+## Releasing
+
+`.github/workflows/cli-release.yml` releases automatically on every push to
+main that touches `cli/` (patch bump); manual dispatch remains for
+minor/major or an explicit version. Flow: tests → resolve version → build →
+publish to the `dr-cli-public` JFrog repo with `--ignore-scripts` → push a
+`cli-v<semver>` tag (best-effort, traceability only). Versioning is
+stateless because main's ruleset forbids direct pushes: no bump commit is
+ever made — the next version is derived from the latest one already on the
+registry, and `package.json`'s version only seeds the very first publish.
+Consumers
+install through `dr-cli-virtual`, which fronts `dr-cli-public` + public npm
+with anonymous read — the same registry managed agents already use for
+dr-cli, so no new JFrog infrastructure is needed.
+
+Squat protection: like dr-cli, the scoped name means federation with public
+npm is safe; if an unscoped placeholder is ever wanted on npmjs, publish it
+manually (`0.0.1-locked`), as was done for `@datarails-ai/dr-cli`.
+
+## Managed agents (later)
+
+To expose this CLI on a managed agent the ai-service side needs the same
+wiring dr-cli got under DR-50929 (`cliAgentDefinition.ts` and friends):
+an install preamble (`npm install -g @datarails-ai/dr-appspace-cli --registry
+.../dr-cli-virtual`), the mounted credential file (this CLI reads the exact
+same `~/.dr/session.json` contract), and a token-refresh custom tool. Nothing
+in this package blocks that — the credential-file store is the piece that
+makes it possible, and it ships here from day one.