primitive-admin 1.0.61 → 1.0.62

package/README.md

@@ -5,9 +5,13 @@ Command-line interface for administering Primitive applications. This CLI provid
 ## Installation
 
 ```bash
-npm install -g primitive-admin
+pnpm add -g primitive-admin
 ```
 
+pnpm is the recommended package manager. If you use npm instead, run
+`npm install -g primitive-admin` — install with one manager only, or you end up
+with two global copies.
+
 ### Development Setup
 
 From the **worklet root directory**:
@@ -133,17 +137,20 @@ Manage applications (requires admin access).
 
 ```bash
 primitive apps list                    # List all accessible apps
-primitive apps create "My App"         # Create a new app
+primitive apps create "My App"         # Create a new app (mints the app id)
 primitive apps get <app-id>            # Get app details
-primitive apps update <app-id> [opts]  # Update app settings
 primitive apps delete <app-id>         # Delete an app
 ```
 
-**Update options:**
-- `--name <name>` - App display name
-- `--mode <mode>` - Access mode: public, invite-only, waitlist
-- `--base-url <url>` - Application base URL
-- `--waitlist` / `--no-waitlist` - Enable/disable waitlist
+App settings are configuration, so they are authored in `app.toml` and applied
+with `config push` (issue #2645) — there is no `apps update`:
+
+```bash
+primitive apps get                       # what the server is running
+primitive config pull --only app         # write those settings into app.toml
+primitive config set app app.mode=invite-only
+primitive config push --only app         # apply the edit
+```
 - `--google-oauth` / `--no-google-oauth` - Enable/disable Google OAuth
 - `--passkey` / `--no-passkey` - Enable/disable passkey auth
 - `--magic-link` / `--no-magic-link` - Enable/disable magic link auth
@@ -180,34 +187,27 @@ Manage HTTP integrations (external API connections).
 
 ```bash
 primitive integrations list [app-id]              # List integrations
-primitive integrations create [app-id] [options]  # Create integration
 primitive integrations get <integration-id>       # Get details
-primitive integrations update <id> [options]      # Update integration
-primitive integrations delete <id>                # Soft delete
 primitive integrations test <id>                  # Test connection
 primitive integrations logs <id>                  # View invocation logs
 ```
 
-**Create options:**
-- `--from-file <path>` - Load from TOML file
-- `--key <key>` - Integration key (identifier)
-- `--name <name>` - Display name
-- `--base-url <url>` - Base URL for API calls
-- `--timeout <ms>` - Request timeout in milliseconds
-
-**Secrets management:**
-
-Integration-scoped secrets are **deprecated** and can no longer be created. Use
-app-level secrets instead (`primitive secrets set <KEY> --value <value>`) and reference
-them in integration config via `{{secrets.KEY}}`. See the **Secrets** section
-below. The remaining integration-secret commands only list/archive legacy
-secrets:
+An integration is authored in `integrations/<key>.toml` and applied with
+`config push` — creating, updating and deleting one are all edits to that file:
 
 ```bash
-primitive integrations secrets list <integration-id>
-primitive integrations secrets archive <id> <secret-id>
+primitive config fields integration               # its keys, types, defaults
+primitive config create integration weather-api      # scaffold the file
+primitive config push --only integration/weather-api
 ```
 
+**Secrets management:**
+
+Integration-scoped secrets are **retired** — the `primitive integrations secrets`
+command group no longer exists. Use app-level secrets instead
+(`primitive secrets set <KEY> --value <value>`) and reference them in integration
+config via `{{secrets.KEY}}`. See the **Secrets** section below.
+
 ### Secrets
 
 Manage encrypted app secrets (API keys, tokens, credentials). Values are encrypted at rest and never displayed after creation.
@@ -234,29 +234,25 @@ Manage LLM prompt configurations.
 
 ```bash
 primitive prompts list [app-id]             # List prompts
-primitive prompts create [app-id] [options] # Create prompt
 primitive prompts get <prompt-id>           # Get details
-primitive prompts update <id> [options]     # Update prompt
-primitive prompts delete <id>               # Soft delete
 primitive prompts execute <id> --vars '{}'  # Execute prompt
 primitive prompts preview <id> --vars '{}'  # Preview rendered template
 ```
 
-**Create options:**
-- `--from-file <path>` - Load from TOML file
-- `--key <key>` - Prompt key (identifier)
-- `--name <name>` - Display name
-- `--provider <provider>` - LLM provider (openrouter, gemini)
-- `--model <model>` - Model name
-- `--system-prompt <text>` - System prompt
-- `--user-template <text>` - User prompt template
+A prompt is authored in `prompts/<key>.toml` and applied with `config push`:
+
+```bash
+primitive config create prompt summarizer
+primitive config push --only prompt/summarizer
+```
+
+**Configs (prompt variations)** are `[[configs]]` entries in that same file —
+`active = true` marks the live one, `status = "archived"` retires one, and
+duplicating is copying the block under a new `name`. The CLI reads them:
 
-**Configs (prompt variations):**
 ```bash
 primitive prompts configs list <prompt-id>
-primitive prompts configs create <prompt-id> [options]
-primitive prompts configs activate <prompt-id> <config-id>
-primitive prompts configs duplicate <prompt-id> <config-id>
+primitive prompts configs get <prompt> <config>
 ```
 
 ### Workflows
@@ -265,24 +261,34 @@ Manage multi-step workflow definitions.
 
 ```bash
 primitive workflows list [app-id]                  # List workflows
-primitive workflows create [app-id] --from-file wf.toml  # Create workflow
 primitive workflows get <workflow-id>              # Get details
-primitive workflows update <id> [options]          # Update metadata
-primitive workflows draft update <id> --from-file wf.toml  # Update draft
-primitive workflows publish <id>                   # Publish draft
 primitive workflows preview <id> --input '{}'      # Preview execution
+primitive workflows disable <id>                   # Take it out of service now
+primitive workflows enable <id>                    # Put it back
+```
+
+A workflow is authored in `workflows/<key>.toml` (named config bodies in
+`workflows/<key>.configs/<name>.toml`) and applied with `config push`:
+
+```bash
+primitive config create workflow process-doc
+primitive config push --only workflow/process-doc
 ```
 
+Revisions are read-only history from the retired legacy path (issue #2768:
+`workflows publish` and its endpoint are gone). A workflow created before the
+configuration model — one with no active config — is migrated by authoring
+`workflows/<key>.configs/<name>.toml`, setting `activeConfigName = "<name>"` in
+`workflows/<key>.toml`, and pushing.
+
 **Run management:**
 ```bash
 primitive workflows runs list <workflow-id>
 primitive workflows runs status <workflow-id> <run-id>
 ```
 
-**Workflow TOML push-time validation (issue #685):** Every command that
-pushes a workflow TOML (`workflows create --from-file`,
-`workflows draft update --from-file`, `workflows configs create --from-file`,
-`workflows configs update --from-file`, and `primitive sync push`) runs the
+**Workflow TOML push-time validation (issue #685):** `primitive config push` —
+the only command that sends a workflow TOML since #2645 — runs the
 file through `cli/src/lib/workflow-toml-validator.ts` before sending it to
 the server. For a step whose `kind` the CLI knows about, the validator
 rejects any top-level field outside the allowlist — most commonly catching
@@ -312,6 +318,46 @@ drift (#685/#802/#971) cannot recur. When you add a new step kind or a runner
 starts reading a new field, just regenerate and commit the artifact — there is
 no hand-maintained list to update.
 
+**A configuration object's field surface has ONE definition (issue #2644):**
+`src/config-surface/` on the server records, per configuration object, which
+`models.yaml` fields exist, which TOML key each carries, which modes the server
+accepts it in, and — for a field with real behavior — the handler that owns it.
+The server's create/update handlers take their accepted key set from it
+(`pickWritableFields`), and `cli/scripts/gen-config-surfaces.mjs` vendors the
+same modules into the committed artifact
+`cli/src/lib/generated-config-surfaces.ts`, which the CLI's push builder, pull
+serializer and TOML key validation read. The generator runs automatically at CLI
+`prebuild`; regenerate manually with `node cli/scripts/gen-config-surfaces.mjs`
+(or `pnpm -C cli gen:config-surfaces`).
+
+Three hard-fail checks live in `cli/tests/unit/config-surface-drift-guard.test.ts`:
+freshness (`--check`, a byte comparison), coverage (every model field of every
+registered object is either exposed or classified `notExposed` **with a
+reason**), and registry existence (every `SYNC_RESOURCE_TYPES` label has a
+definition — the migration's `PENDING_MIGRATION` exemption list is gone, so
+there is nowhere to park one). Add a
+field to `models.yaml` and the CLI unit suite fails until you regenerate and
+classify it — so the CLI can no longer silently drop a new server-side field.
+This supersedes the workflow-only descriptor and generator from #2326.
+
+**Template expressions are linted at push time (issue #2689):** the validator
+also inspects every `{{ }}` expression on a step and rejects the ones that can
+never resolve — an unknown root (`{{ inputs.userId }}`; the valid roots are
+`input`, `steps`, `outputs`, `meta`, `secrets`, `vars`, plus the contextual
+`selected`/`user`/`md`, the built-ins `now`/`today`/`uuid`/`ulid`, and — inside a
+forEach step's body only — `iteration`/`loop` and the loop's binding name) or a
+reference to a `steps.<id>` / `outputs.<name>` the file does not declare. An
+expression that is only sometimes present is marked optional with
+`| default: ''` or a trailing `|| ''`, and anything statically undecidable (a
+dynamic bracket key) is left to the run-time check. The lint itself is a
+verbatim generated copy of the server module
+`src/workflows/runner/template-static-lint.ts` at
+`cli/src/lib/generated-template-lint.ts` (`cli/scripts/gen-template-lint.mjs`,
+run at `prebuild`, with a `--check` freshness mode asserted by
+`cli/tests/unit/template-lint-drift-guard.test.ts`), so the CLI's push-time
+verdict and the server's save-time verdict come from the same code.
+
+
 ### Tokens
 
 Manage long-lived API access tokens for headless/server authentication.
@@ -364,6 +410,8 @@ primitive databases operations execute <database-id> <op-name> --token <jwt>   #
 
 The `--token` flag lets you execute an operation as a specific user using a test JWT from `users mint-jwt`. Useful for testing access rules.
 
+Under `--json`, the printed shape is the operation's own. A `query` — and a `pipeline` whose `returnField` names a query step — prints the CLI's list envelope `{ items, hasMore, nextCursor? }`, the same shape as `databases records query --json`. Every other operation type prints unchanged: `count` → `{ count }`, `aggregate` → `{ result }`, mutation → `{ results }`, `applyToQuery` → `{ matched, affected, failed, … }`, and a `returnField = "all"` pipeline → `{ steps: { … } }` with each step's own keys left alone. `--timing` adds `_timing` alongside whichever shape you get.
+
 **Records (schema introspection):**
 ```bash
 primitive databases records models <database-id> [app-id]            # List model names
@@ -383,7 +431,7 @@ primitive databases export [app-id] <database-id> --output <dir>      # Export r
 primitive databases import [app-id] <path> --overwrite --dry-run      # Import from export directory
 ```
 
-Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records and indexes into a new or existing database. Database type config (operations, triggers, access rules) is managed separately via `primitive sync` — run `sync push` on the target app before importing.
+Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records and indexes into a new or existing database. Database type config (operations, triggers, access rules) is managed separately via `primitive config` — run `config push` on the target app before importing.
 
 ### Documents
 
@@ -512,15 +560,15 @@ primitive catalog integrations update <catalog-id> [options]
 primitive catalog integrations delete <catalog-id>
 ```
 
-### Sync (TOML Configuration)
+### Config (TOML Configuration)
 
-Sync app configuration to/from TOML files for version control.
+Author app configuration as TOML files and reconcile them with the server.
 
 ```bash
-primitive sync init [app-id] --dir ./config    # Initialize config directory
-primitive sync pull [app-id] --dir ./config    # Pull remote config to local
-primitive sync push [app-id] --dir ./config    # Push local config to remote
-primitive sync diff [app-id] --dir ./config    # Show differences
+primitive config init [app-id] --dir ./config    # Initialize config directory
+primitive config pull [app-id] --dir ./config    # Pull remote config to local
+primitive config push [app-id] --dir ./config    # Push local config to remote
+primitive config diff [app-id] --dir ./config    # Show differences
 ```
 
 **Options:**
@@ -556,8 +604,7 @@ baseUrl = "https://myapp.com"
 [auth]
 googleOAuthEnabled = true
 passkeyEnabled = true
-magicLinkEnabled = false
-otpEnabled = true                      # email one-time-passcode sign-in
+emailSignInEnabled = true              # one email carrying a code and a link
 appleSignInEnabled = true              # Sign in with Apple
 appleAudiences = ["com.example.MyApp"] # allowed Apple audiences
 
@@ -571,7 +618,7 @@ Notes on `[auth]`:
 
 - Only keys you actually list are pushed. Omitting a key leaves the server's
   current value untouched — it is **not** reset to `false`. To turn a method
-  off, set it explicitly (e.g. `magicLinkEnabled = false`).
+  off, set it explicitly (e.g. `emailSignInEnabled = false`).
 - An unrecognized `[auth]` key (for example a typo like `googleOauthEnabled`)
   produces a warning on `push` and is ignored, rather than being silently
   dropped. The push still applies the recognized keys.
@@ -587,7 +634,6 @@ Notes on `[auth]`:
 key = "weather-api"
 displayName = "Weather API"
 description = "OpenWeatherMap integration"
-status = "active"
 timeoutMs = 30000
 
 [requestConfig]
@@ -603,7 +649,6 @@ allowedPaths = ["/weather", "/forecast"]
 key = "summarizer"
 displayName = "Text Summarizer"
 description = "Summarizes input text"
-status = "active"
 
 [[configs]]
 name = "default"
@@ -687,7 +732,7 @@ Shape (`schemaVersion: 1`):
   "schemaVersion": 1,
   "name": "primitive",
   "version": "1.0.49",
-  "globalOptions": [ { "flags": "-e, --env <name>", "description": "…", "required": true, "defaultValue": null } ],
+  "globalOptions": [ { "flags": "-e, --env <name>", "description": "…", "required": true, "defaultValue": null, "hidden": false } ],
   "commands": [
     {
       "name": "sync",
@@ -701,7 +746,7 @@ Shape (`schemaVersion: 1`):
           "description": "…",
           "aliases": [],
           "args": [ { "name": "app-id", "required": false, "variadic": false, "description": "…" } ],
-          "options": [ { "flags": "--dir <path>", "description": "…", "required": true, "defaultValue": null } ],
+          "options": [ { "flags": "--dir <path>", "description": "…", "required": true, "defaultValue": null, "hidden": false } ],
           "commands": []
         }
       ]
@@ -710,6 +755,10 @@ Shape (`schemaVersion: 1`):
 }
 ```
 
+`hidden` marks a deprecated alias that still works but is not part of the
+supported surface (it is omitted from human `--help` too). Tooling that treats
+the manifest as an allowlist — the docs CLI gate does — should skip those flags.
+
 `schemaVersion` is the contract knob: consumers assert the shape they understand
 and fail loud if a future CLI bumps it (a breaking change for downstream tooling
 such as docs CI that drift-gates documented invocations against the published
@@ -717,7 +766,7 @@ CLI).
 
 ### `primitive-admin/validators` — TOML validators
 
-The TOML validators that `sync push` runs as its load-bearing gate are exported
+The TOML validators that `config push` runs as its load-bearing gate are exported
 from the `primitive-admin/validators` subpath (ESM-only, with types) so external
 tooling can validate exactly the way the published CLI does — instead of
 re-implementing the flow and silently drifting.
@@ -737,8 +786,8 @@ Two contracts:
 - **`validateWorkflowTomlSource(raw, filePath)`** — pass the **raw TOML source
   string** and the workflow's path. It runs the *identical* parse →
   `expandWorkflowTomlData()` (`include` fragment expansion) → `validateWorkflowToml`
-  → `formatWorkflowTomlErrors` path that `sync push` runs, so it cannot diverge
-  from `sync push` on workflow `include` fragments. Returns
+  → `formatWorkflowTomlErrors` path that `config push` runs, so it cannot diverge
+  from `config push` on workflow `include` fragments. Returns
   `{ errors, formatted }` (`formatted` is `null` when valid). Fragment files
   resolve relative to `<filePath>/../../workflow-fragments/`, matching the CLI.
 
@@ -771,8 +820,10 @@ Internal helpers (`collectParamRefs`, `declaredParamNames`,
 
 **Login server resolution:**
 1. Project mode (`.primitive/config.json` present): the active environment's
-   `apiUrl`. Select the environment with `-e <name>`, `PRIMITIVE_ENV`, or
-   `defaultEnvironment`. An unresolvable environment fails loudly — `login`
+   `apiUrl`. Select the environment with `-e <name>`, `PRIMITIVE_ENV`,
+   `primitive env use <name>` (this machine's selection, stored in the
+   gitignored `.primitive/local.json`), or the committed `defaultEnvironment`
+   — in that order. An unresolvable environment fails loudly — `login`
    never silently falls back to production.
 2. Legacy mode (no project config): `PRIMITIVE_SERVER_URL`, else the default
    `https://primitiveapi.com`.
@@ -784,6 +835,11 @@ Internal helpers (`collectParamRefs`, `declaredParamNames`,
 
 ## Development
 
+Before adding or changing a command, read [`docs/cli-design.md`](../docs/cli-design.md)
+in the repo root — the CLI's design rules (which verbs each kind of noun carries,
+TOML-only authoring, deletion and naming rules, what a breaking change obliges).
+It is internal maintainer guidance and is not published.
+
 ```bash
 # Run without building (uses tsx)
 pnpm run cli:dev -- login