@vectros-ai/cli 0.25.0 → 0.26.0

package/AUTHORING.md

@@ -8,7 +8,7 @@ ready-to-use data model + a narrow `ssk_*` scoped key — no root key, no manual
 admin steps. `vectros blueprint apply <file> --tenant test|live` applies the same
 blueprint WITHOUT minting a key, for re-applying a change from CI.
 
-This guide is the authoring loop. Everything here except `bootstrap` and `blueprint apply` is
+This guide is the authoring loop. Everything here except `blueprint-test`, `bootstrap` and `blueprint apply` is
 **creds-free and offline** — you can iterate on a blueprint with no account.
 
 > The examples use the bare `vectros` binary — install it once with
@@ -22,7 +22,7 @@ vectros blueprint init my-thing        # 1. scaffold a starter
 # …edit ./my-thing.blueprint.yaml…
 vectros blueprint validate ./my-thing.blueprint.yaml   # 2. structural + scope-gate + lint (offline)
 vectros blueprint plan     ./my-thing.blueprint.yaml   # 3. preview what it provisions (offline)
-vectros blueprint-test     ./my-thing.blueprint.yaml --env staging  # 4. prove it live (creds; auto-teardown)
+vectros blueprint-test     ./my-thing.blueprint.yaml --tenant test  # 4. prove it live (creds; auto-teardown)
 vectros bootstrap --blueprint ./my-thing.blueprint.yaml # 5. apply for real + mint a key (needs a bridge token)
 vectros blueprint apply ./my-thing.blueprint.yaml --tenant test  # 5'. apply for real, no key (CI: add --yes --confirm-existing-principal)
 ```
@@ -50,7 +50,7 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 `validate` runs three layers and exits non-zero on any failure:
 
 1. **Structural** — the file parses against the blueprint schema (readable
-   `path: message` errors, e.g. `schemas[0].fields[1]: Required`).
+   `path: message` errors, e.g. `schemas[0].fields[1].fieldType: Required`).
 2. **Scope + capability gates** — the requested `allowedActions` are data-plane
    only. This is the trust boundary: `keys`/`users`/`admin`/`app-contexts`/
    `namespaces` and the `*` wildcard are **hard-rejected, no override**.
@@ -97,12 +97,14 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 
 ```
   Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
-    + schema 'thing' (1 field, HYBRID) lookup: [title]
-    + context 'mcp' (MCP — my-thing)
+  ...
     + principal 'my-thing-sp' (SERVICE)
+    + context 'mcp' (MCP — my-thing)
+    + schema 'thing' (1 field, HYBRID) lookup: [title]
     + profile scopes [records:r, records:c, records:u, search:r, schemas:r] (data-plane ✓)
     + key my-thing-<machine> (mint 1 scoped ssk_*)
-    + seed 1 record(s)
+    + seed 1 record
+  6 step(s). This is a preview — nothing was minted.
 ```
 
 **A blueprint whose `accessProfile` composes roles (`roleIds:`) previews every
@@ -111,9 +113,10 @@ sharing an action set can still carry different `dataScope`:
 
 ```
   Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
-    + schema 'thing' (1 field, HYBRID) lookup: [title]
-    + context 'mcp' (MCP — my-thing)
+  ...
     + principal 'my-thing-sp' (SERVICE)
+    + context 'mcp' (MCP — my-thing)
+    + schema 'thing' (1 field, HYBRID) lookup: [title]
     + role 'case-handler' (1 clause, actions [records:cru])
       clause 1: actions [records:cru], dataScope: scope:org=[${{ self.scope.org }}]
     + role 'hr-admin' (1 clause, actions [records:r])
@@ -121,7 +124,8 @@ sharing an action set can still carry different `dataScope`:
       assumable: scope:org=[org_engineering, org_sales]
     + profile via role(s) [case-handler, hr-admin] (composed — each role's own clauses, concatenated in order)
     + key my-thing-<machine> (mint 1 scoped ssk_*)
-    + seed 1 record(s)
+    + seed 1 record
+  8 step(s). This is a preview — nothing was minted.
 ```
 
 A role's `assumable` line only appears when the blueprint's top-level
@@ -164,13 +168,13 @@ everything it created:
 
 ```
 vectros login                                            # sign in once (or pass --token)
-vectros blueprint-test ./my-thing.blueprint.yaml --env staging
+vectros blueprint-test ./my-thing.blueprint.yaml --tenant test
 vectros blueprint-test task-management --keep            # leave the graph in place to inspect it
 ```
 
 Teardown is the default and runs even if an assertion fails. It is **created-only** — a pre-apply
 snapshot means it never deletes a schema or AccessProfile that already existed, so it's safe to point at
-a shared staging tenant. (It does **not** delete the app-context: that's idempotent and reused.) Exit
+a tenant other people use. (It does **not** delete the app-context: that's idempotent and reused.) Exit
 `0` = applied + every assertion passed; `1` = an assertion failed or apply errored; `2` = no credential,
 or the blueprint asked for control-plane scope (the same gate `validate` enforces). Run this before you
 ship a blueprint — it catches an unusable or mis-scoped credential that the offline checks can't.
@@ -367,6 +371,16 @@ identities:
 YAML or JSON are both accepted (chosen by extension). The bundled library is
 authored in TypeScript; YAML is the authoring affordance for your own.
 
+### Inputs — values you supply when you install
+
+A blueprint can declare a top-level `inputs:` block (each input has a `type` of `string`, `number` or `boolean`, and may
+have `required`, `default` and `description`) and use the values in any string with `${{ inputs.<name> }}`. The built-ins
+`${{ vectros.context }}` and `${{ vectros.suffix }}` are the blueprint's literal `contextId` and a short stable token derived
+from it. Supply values to `validate`, `plan` and `apply` with `--set name=value` (repeatable) or `--values <file>` (a YAML or
+JSON map); `--set` wins over `--values`, which wins over the declared `default`. An unknown input, a missing value with no
+default, or a value of the wrong type stops the command before any request is sent. Write `$${{` for a literal `${{`. The
+`@vectros-ai/blueprints` README describes the block in full.
+
 ### Choosing lookup indexes — a permanent decision
 
 `lookupFields` are how you reach records *directly* — by exact value, by an
@@ -424,7 +438,6 @@ each tell you "records with this status" or "records with this area", but never
 
 ```yaml
 lookupFields:
-  - externalId
   - { fieldNames: [status, area], sortBy: createdAt, allowOverflow: true }
 ```
 

package/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.26.0 — 2026-10-25
+
+### Added
+
+- **`vectros whoami --tenant test|live`** shows the session for that tenant (default `live`). The output gains a `tenant type`
+  line and `--json` gains `tenantType`. The test tenant shows your own user id there, which needs platform 0.47.0 or later and
+  shows `—` on an earlier platform. Any other value stops with a usage error (exit 2).
+- **`vectros access list --principal` prints a note on standard error naming the context it searched.** The command searches
+  the `default` context, and depending on the caller the platform may not look beyond it, so an empty result means none in
+  `default`; the note gives the `vectros access get --principal … --context <c>` command to check another. Standard output
+  and `--json` are unchanged. A `2>&1 | jq` pipeline fails on the note; redirect standard error instead.
+
+### Fixed
+
+- **A blueprint file whose trigger `dataScope` uses `${{ input.userId }}` or `${{ input.scope.<namespace> }}` loads in
+  `validate`, `plan`, `apply` and `bootstrap`.** The platform resolves these placeholders against the record that fires the
+  trigger.
+
+### Changed
+
+- **`vectros --version` reports SDK 0.48.0.**
+- **`vectros blueprint apply` stops with the platform's message when another request changes the same item at the same
+  moment.** When apply updates a schema, role or trigger rule, the platform answers `409` (`VERSION_CONFLICT`) instead of
+  overwriting the other change. Run apply again once the other change has finished.
+- **`vectros provider-config create` and `update` stop with the platform's `503` when it cannot store the provider key.**
+  Nothing is saved; run the command again shortly.
+- **The bundled `@vectros-ai/blueprints` is 0.20.3, and the package description covers the whole command set.**
+- **The comments in the shipped code describe the code as it is today.** Behaviour is unchanged, except for the text of the
+  error for a missing Cognito client id.
+
+### Documentation
+
+- **The README documents `vectros login`, `logout`, `whoami` and `switch`, and `vectros keyring prune --dry-run`.**
+- **The README says `vectros blueprint-test` exits `1` for a blueprint that cannot be read, and that
+  `vectros provider-config create` and `update` stop with the platform's `503` when it cannot store the provider key.**
+- **The authoring guide describes the `inputs:` block of a blueprint: its types, `required` and `default`, `--set` and
+  `--values`, and the `vectros.context` and `vectros.suffix` built-ins.**
+- **The authoring guide shows an abbreviated `plan` output, with the steps in the order they run and the closing step count, and
+  uses `--tenant test` for `blueprint-test`.**
+
 ## 0.25.0 — 2026-10-12
 
 ### Breaking changes

package/README.md

@@ -5,6 +5,8 @@
 
 The Vectros provisioning CLI — the `vectros` binary:
 
+- **`vectros login`** / **`logout`** / **`whoami`** — sign in through your browser (`--no-browser` prints the URL instead, for headless machines), clear the stored session, and show the signed-in session for a tenant (`--tenant test|live`, default `live`; `--json`).
+- **`vectros switch <alias>`** — shortcut for `keyring use`.
 - **`vectros bootstrap`** — provision a least-privilege MCP credential (+ optional blueprint).
 - **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`, creds-free), and
   **`apply`** one into a tenant without minting a key (for CI).
@@ -210,8 +212,8 @@ vectros blueprint-test ./my-thing.blueprint.yaml --tenant test
 vectros blueprint-test task-management --keep
 ```
 
-Exit `0` = applied and every assertion passed; `1` = an assertion failed or apply
-errored; `2` = no credential, or the scope gate or the capability gate refused the blueprint.
+Exit `0` = applied and every assertion passed; `1` = an assertion failed, apply
+errored, or the blueprint could not be read; `2` = no credential, or the scope gate or the capability gate refused the blueprint.
 The app-context is intentionally **not** deleted (it's idempotent and reused).
 
 ## `vectros context` — app contexts
@@ -317,7 +319,7 @@ config up itself is refused by the platform with a `400` for anything but `--bil
 `byo-model-inference:customer-key` waiver type, and a plain `https://` endpoint on port 443 (no credentials,
 query or fragment). On `update`, only a **change** to one of those is refused; a value the config already
 holds is accepted. Changing an endpoint's host needs the key again (`--api-key-secret-file`). The key must
-be printable ASCII, at most 4096 characters. A tenant holds at most 25 provider configs.
+be printable ASCII, at most 4096 characters. A tenant holds at most 25 provider configs. If the platform cannot store the key it answers `503`, nothing is saved, and the command stops with that message; run it again shortly.
 
 The CLI does not sign the risk waiver: an account owner signs it in the developer portal, under **Model
 Providers**, for each environment (live or test). A config is usable only while that waiver is in force for
@@ -541,12 +543,24 @@ vectros access grant --principal me --context my-app --role editor
 vectros access grant --principal usr_<id> --context my-app --actions records:r,search:r \
   --scope org:<orgId>
 vectros access list --context my-app        # who's in this context
-vectros access list --principal me          # which contexts I'm bound to
+vectros access list --principal me          # which contexts I'm bound to (see the note below)
 vectros access get --principal me --context my-app
 vectros access explain --principal me --context my-app
 vectros access revoke --principal usr_<id> --context my-app
 ```
 
+`access list --principal` searches one context, `default`, because the command's token is pinned to it:
+depending on the caller the platform may not look beyond that context, so a grant you hold in another
+context can be missing from the list, and an empty list means no grant in `default`, not no grants
+anywhere. The command says so on standard error, so `--json` output on standard output stays a bare array,
+and it drops the line when a row from another context shows the lookup did span contexts. To see a grant
+in a specific context, run `vectros access get --principal me --context <context-id>` (add `--tenant test`
+for the test tenant), or `vectros access list --context <context-id>` for everyone in it.
+
+The line is also written with `--json`, and there is no switch to turn it off. A script that merges standard
+error into standard output (`2>&1`) will see one extra line and a `2>&1 | jq` pipeline will fail on it;
+redirect standard error (`2>/dev/null`) to drop it.
+
 `--principal` accepts `usr_<userId>`, `key_<keyId>`, or the alias `me` (your
 own signed-in user, resolved from your login) — every `access` subcommand
 shares this grammar. In the **test tenant** your principal has a different id from your live user, so `me` resolves it per tenant: add `--tenant test` and it still works, e.g. `vectros access grant --principal me --context <context-id> --role <role> --tenant test`. This needs platform 0.47.0 or later; on an earlier platform the command typically stops and points you to `vectros identity list-all --tenant test` (an owner login), which shows the id to pass as `--principal usr_<id>`.
@@ -612,7 +626,7 @@ is optional and stripped if present) — narrower than `access`'s grammar: there
 is no `me` alias on any `key` subcommand, and a key never authenticates as a
 `key_*` principal. Look your own id up first with `vectros identity list
 --type user` (or `vectros whoami`; both show your live tenant, and for the test tenant
-use `vectros identity list-all --tenant test`), or grant/issue via `vectros join`, which
+use `vectros whoami --tenant test` or `vectros identity list-all --tenant test`), or grant/issue via `vectros join`, which
 does resolve `--as me`.
 
 A minted secret has exactly two destinations, and the flags for choosing one
@@ -630,7 +644,7 @@ are shared by `issue` and `rotate`:
 | `issue` | `--principal <p>`, `--context <c>` (required); `--name <n>` (default `default`), `--label <l>`, `--tenant test\|live`, destination flags above | Idempotent on `(tenant, context, principal, name)` — re-issuing an existing tuple returns the key **without** the secret (never re-disclosed); the CLI detects that and points you at `rotate`. |
 | `list` | `--principal <p>`, `--context <c>`, `--tenant test\|live` **or** `--all-contexts` (owner-only; spans both tenants, not combinable with `--tenant`) | **The default lists only ONE context's keys** (the token's context — `default`, or `--context`), not your whole account — easy to miss since the active-key limit is tenant-wide across all contexts. `--all-contexts` is the true account-wide view. |
 | `get <keyId>` | `--context <c>`, `--tenant test\|live` | `--context` pins the verb token to the key's context — omit it for a key bound to a non-default context (e.g. one `bootstrap` minted) and the lookup 404s. |
-| `revoke <keyId>` | `--context <c>`, `--tenant test\|live` | Soft-delete; ~5 minutes to take effect (authorizer cache). Same `--context` pinning caveat as `get`. |
+| `revoke <keyId>` | `--context <c>`, `--tenant test\|live` | Soft-delete; it takes about 5 minutes to take effect. Same `--context` pinning caveat as `get`. |
 | `rotate` | `--principal <p>`, `--context <c>` (required); `--name <n>`, `--force-new`, `--tenant test\|live`, destination flags above | Revokes the matching active key (by the exact `(context, principal, name)` tuple), then mints a fresh one — there is no dedicated rotate endpoint. **Default-name guard:** if no key is currently active under `--name` (default `default`) but the principal/context has *other* active keys, `rotate` refuses rather than silently minting an unrelated second key — pass the right `--name` or `--force-new` to proceed anyway. |
 
 `issue`/`rotate` have no `--json` (use `--format json` instead); `list`/`get`
@@ -652,6 +666,7 @@ vectros keyring show                 # the active entry's fields + its key
 vectros keyring show --format raw    # JUST the secret, for scripts (see below)
 vectros keyring doctor               # is the keyring healthy? which keys are live?
 vectros keyring prune                # drop entries whose stored secret is gone
+vectros keyring prune --dry-run      # report what would be removed, remove nothing
 vectros keyring remove <alias>       # drop one entry + its secret
 ```