@vectros-ai/cli 0.19.0 → 0.20.0

package/AUTHORING.md

@@ -69,6 +69,16 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
    `dataScope: {}` when a shared/tenant-wide resource is what you intend
    (warnings — they print but don't fail).
 
+   A schema may also declare `expectedScopeDims` — the ownership dimensions
+   its records are typically scoped by, e.g. `expectedScopeDims: [org,
+   client]`. Purely advisory (never sent to the platform, never runtime-
+   enforced): it lets the lint warn when a role/`accessProfile` clause grants
+   `r`/`u`/`d` on that typeName (via a type-qualified action like
+   `records:r:case`) but its `dataScope` names only SOME of the declared
+   dims — reads never require full-dimension coverage the way creates do, so
+   a clause naming one of two declared dims silently leaves the other
+   unconstrained. Omit the field entirely and this lint never fires.
+
 `validate` accepts a file path **or** a bundled blueprint name.
 
 ### 3. `plan` — preview before you mint
@@ -196,8 +206,9 @@ accessProfile:
   # capabilities: [member-lifecycle]
   # A SEPARATE gated dimension from allowedActions — named platform effects a
   # resource:ops verb can't express (e.g. creating/removing an identity in
-  # your tenant). Only 'member-lifecycle' is admitted today; every other name
-  # is hard-rejected, same posture as the scope gate. See "Capabilities" below.
+  # your tenant). 'member-lifecycle' and 'delegate-principal-stamp' are
+  # admitted today; every other name is hard-rejected, same posture as the
+  # scope gate. See "Capabilities" below.
   #
   # Instead of allowedActions (+ optional dataScope/capabilities), accessProfile
   # may declare `roleIds: [<roleId>, ...]` — one or more roles declared below,
@@ -456,10 +467,10 @@ boundary, not the file.
 An `accessProfile` or role clause may also declare `capabilities: [...]` —
 named platform effects (like creating or removing an identity in your tenant)
 that a `resource:ops` scope token can't express. This rides its own field,
-separate from `allowedActions`, and has its own allowlist: **only
-`member-lifecycle` is admitted today.** Every other capability name —
-including ones the platform's own registry recognizes — is refused, the same
-fail-closed, deliberately-narrow posture as the scope gate above. `validate`,
+separate from `allowedActions`, and has its own allowlist: **`member-lifecycle`
+and `delegate-principal-stamp` are admitted today.** Every other capability
+name — including ones the platform's own registry recognizes — is refused,
+the same fail-closed, deliberately-narrow posture as the scope gate above. `validate`,
 `plan`, `blueprint-test` and `bootstrap` all report a rejected capability the
 same way they report a rejected scope: nothing mints, and the CLI exits
 non-zero.

package/CHANGELOG.md

@@ -3,6 +3,147 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.20.0 — 2026-08-27
+
+### Added
+
+- **The capability gate now admits `delegate-principal-stamp`**, alongside the
+  existing `member-lifecycle`. Grantable on an `accessProfile` or role clause's
+  `capabilities: [...]`, same as before — a blueprint can now let an admin
+  role create a membership-shaped record on behalf of a known third-party
+  user, once the clause authorizing the write also explicitly names `userId`
+  in its own `dataScope` (the capability itself may be granted on a
+  different clause of the same role, e.g. via a separately-composed
+  `roleIds` entry — only the write's own verb + `userId` admission must be
+  co-located). Bounded by the SAME app context and record type the clause's
+  `dataScope` already confines the write to — unlike `delegate-mint`/
+  `forensic-read`/`context-directory-read`, this is not tenant-wide, and
+  (like `member-lifecycle`) it is self-signup-eligible.
+- **`vectros identity list-all`** — lists every user in the tenant, for the one
+  recovery case `identity list` can't reach: a user created but never granted
+  access anywhere (the gap between creating a principal and binding it to a
+  context). `identity list` is scoped to the caller's own context by design —
+  a user with no access grant at all is invisible there no matter how many
+  times a create is retried, since a retry with the same `--external-id` just
+  collides with the same invisible row. `list-all` authenticates with your own
+  login session (an account owner) instead of a context-scoped credential, so
+  it can see every user regardless of context. Supports `--external-id`,
+  `--tenant`, `--limit`, and `--json`, matching `identity list`'s conventions.
+- **`vectros blueprint validate`/`plan`: new advisory lint —
+  `partial-datascope-dimension-coverage`** (needs `@vectros-ai/blueprints` ≥
+  0.17.0). Warns when a role/`accessProfile` clause grants `r`/`u`/`d` on a
+  typeName (e.g. `records:r:case`) whose schema declares
+  `expectedScopeDims`, but the clause's `dataScope` names only SOME of those
+  dims — the missing dimension(s) are silently unconstrained for that grant,
+  since reads (unlike creates) never require full-dimension `dataScope`
+  coverage. Opt-in: a schema with no `expectedScopeDims` declared never
+  trips it, and it never fires on an untyped (bare `records:r`) grant.
+  Never runtime-enforced — pure authoring-time visibility into a choice
+  that's easy to make by omission rather than intent.
+- **`bootstrap`/`blueprint-test` now catch a FRESH (first-apply) seed index
+  failure, not just a re-apply's.** A seed create's response always carries
+  `PENDING_INDEX` on a first apply (indexing runs async, after the
+  response), so the existing `seedIndexFailures` summary previously only
+  ever saw a terminal `FAILED` on a later idempotent re-apply — a
+  newly-bootstrapped demo whose seeds failed to index looked silently empty
+  in search/RAG until the operator happened to re-run bootstrap. Every seed
+  still `PENDING_INDEX` after seeding is now re-checked with a bounded,
+  concurrent, best-effort poll (default: 3 attempts, 500ms apart, ≤ ~1.5s
+  added to the happy path) and folded into the same run-summary warning if
+  it settles to `FAILED` within the bound. Deliberately NOT a guarantee — a
+  seed still `PENDING_INDEX` when the bound is exhausted stays silent, so a
+  genuinely slow index (reconcile/quarantine can stall for minutes) never
+  turns a one-shot provisioning command into an unbounded wait.
+- **`vectros issuers` gains `register`/`update`/`delete`** — previously
+  read-only (`list`/`get`). Closes the gap where adding a second IdP, or
+  editing one issuer's `selfSignupPolicies` after initial setup, required
+  hand-authoring a blueprint `issuers:` block and re-running a full apply.
+  `register` is idempotent by issuer id (a repeat returns the existing
+  registration unchanged, not an error); `update` only ever sends the safe,
+  mutable fields (`subClaim`/`emailClaim`/`userinfoUri`/`status`/
+  `selfSignupPolicies`) — trust-anchor fields stay immutable via this route,
+  matching the platform; `delete` uses the same re-type-the-id confirmation
+  as `context destroy` (`--force` for non-interactive use), and is refused
+  server-side while any user is bound through the issuer. All three accept
+  `--tenant test|live` (like their `list`/`get` siblings) so a context
+  living in the `test` tenant is reachable, not just `live`.
+- **New `vectros namespace` command group: `register`/`list`/`get`.**
+  Registering a brand-new scope namespace (e.g. a `practice`/`team` entity
+  dimension) was blueprint-apply-only before this; there was also no way to
+  discover which namespaces already exist without already knowing their
+  names. `register --entity-backed` is what makes a namespace a real
+  identity-entity dimension that `identity create --type <name>` can create
+  entities in. No `update`/`delete` verbs — both are gated to a genuine root
+  API key on the platform side with no provisioning-capability door, so
+  neither could ever succeed for any credential the CLI holds (documented in
+  the command's own module header).
+- **`role create` gains `--assumable <json>`** — a role-level `vectros
+  assume` entitlement grant (JSON map of `scope:<namespace>` → allowed
+  values), previously blueprint-`roleAssumable:`-only. Independent of
+  `--data-scope`: holding broad data-scope reach in a namespace does not by
+  itself grant assuming any value in it.
+- **New `vectros assume --context <c> --scope <ns:value>...`** — re-mints
+  the caller's own verb token with one or more `identity.<namespace>` values
+  switched (`POST /v1/auth/token/assume`), for a caller whose role
+  explicitly grants assuming those values. The CLI's first standalone
+  command reaching this endpoint; entitlement is checked live against the
+  caller's current roles, never a copy frozen into a token at mint time. No
+  `--to-keyring` — the response is an ephemeral bearer token with the same
+  remaining lifetime as the verb token this command itself mints to make the
+  call, not a durable secret.
+
+### Changed
+
+- **`runLoader`'s `provisioned` is now REQUIRED — the self-provisioning
+  fallback is gone.** Internal hardening only, no CLI-facing behavior
+  change: every real caller (`vectros bootstrap`, `blueprint-test`) already
+  always ran `provisionContext` first and passed the result in, so the
+  fallback branch was dead in production. Removing it makes the
+  `provisionContext` → (apply-time identity resolution) → `runLoader`
+  ordering structurally required instead of convention-enforced — a future
+  caller can no longer reproduce the ordering bug the original fix
+  closed by skipping the split. `allowTenantWideNamespaces` and
+  `confirmExistingPrincipal` moved with it: both now live only on
+  `provisionContext`'s own input, where their actual checks have run since
+  that original fix — `runLoader`'s own copies of both parameters were already dead
+  plumbing before this change.
+- **Apply-time identity resolution now REQUIRES `provisionContext`'s result.**
+  Internal hardening only, no CLI-facing behavior change. Closes the other
+  half of the ordering gap above: `runLoader` already required
+  `provisionContext`'s output, but the step between them — resolving a
+  blueprint's declared `identities:` — took a bare client with nothing tying
+  it to `provisionContext` having run first, so a caller could still
+  reproduce the original ordering bug (a non-`user` identity in a namespace
+  the same blueprint also registers racing that registration) with no
+  compiler signal. It now derives which client to use internally instead of
+  each caller doing so independently.
+
+### Fixed
+
+- **`bootstrap`'s post-merge hint is now blueprint-specific, and `--client
+  code` always shows the `claude mcp add` command.** The restart hint used to
+  read "list my tasks" / "add a task to …" for EVERY blueprint (a leftover
+  from when only `task-management` existed) — it now names the actual
+  blueprint applied. The `claude mcp add` line (the idiomatic Claude Code
+  install path) used to print only on `--no-merge` / a declined / a failed
+  merge — a successful auto-merge silently hid it; it's now shown there too.
+- Scrubbed internal issue/MR references, review-process citations, and
+  backend class names out of `packages/cli`'s comments — visible in the
+  published npm package's sourcemaps to anyone who reads mapped source.
+  Comment-only; no behavior change.
+- **Keyring secret-store hardening.** A 0-byte salt file removed by
+  something else mid-poll (a concurrent cleanup, a manual delete of the
+  crash remnant) used to throw a raw `ENOENT` out of `setSecret`; it now
+  restarts salt creation instead, since nothing was ever encrypted under an
+  empty salt in the first place. Also fixed an order-dependent assumption
+  in two `keyring prune` tests (they now pin the processing order they
+  depend on, so a future ordering change fails with a diagnosable message
+  instead of a confusing downstream one).
+
+### Changed
+
+- Bundled `@vectros-ai/sdk` refreshed to the current release's staging build.
+
 ## 0.19.0 — 2026-08-27
 
 ### Added

package/README.md

@@ -9,9 +9,11 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`), creds-free.
 - **`vectros blueprint-test`** — apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.
 - **`vectros context`** — create, list, and destroy app contexts.
-- **`vectros issuers`** — inspect registered third-party IdP issuers (token-exchange trust anchors) for a context.
+- **`vectros issuers`** — register, update, delete, and inspect third-party IdP issuers (token-exchange trust anchors) for a context.
+- **`vectros namespace`** — register a new scope namespace, and list/get existing ones.
 - **`vectros identity`** — manage tenant-wide principals (users, orgs, clients, and namespaces you register).
 - **`vectros role`** — define reusable, context-scoped access rules.
+- **`vectros assume`** — switch identity namespace values on your own token, per a role's `assumable` grant.
 - **`vectros access`** — bind principals to contexts, and inspect what a binding grants.
 - **`vectros key`** — issue, list, revoke, and rotate scoped API keys (`ssk_*`).
 - **`vectros keyring`** — hold several identities on one machine, pick which is active, and let other tools resolve keys from one place.
@@ -148,23 +150,60 @@ flags (`--base-url`, `--token`).
 
 ## `vectros issuers` — registered third-party IdP issuers
 
-Read the third-party identity-provider registrations a context trusts for
+Manage the third-party identity-provider registrations a context trusts for
 [RFC 8693 token exchange](https://www.rfc-editor.org/rfc/rfc8693) — the
 `issuer`/`jwksUri`/`audience` a blueprint's `issuers[]` entries register, plus
-any self-signup policy attached to one. Read-only: registering an issuer is
-done through a blueprint (`bootstrap`/`blueprint-test`), not this command.
+any self-signup policy attached to one. Everything a blueprint's `issuers:`
+block can do is available standalone here too — adding a second IdP, or
+editing one issuer's `selfSignupPolicies` after initial setup, no longer
+requires hand-authoring a blueprint and re-running a full apply.
 
 ```bash
+vectros issuers register --context my-app --issuer-id auth0-prod \
+  --issuer https://your-tenant.us.auth0.com/ \
+  --jwks-uri https://your-tenant.us.auth0.com/.well-known/jwks.json \
+  --audience https://api.your-app.example.com
 vectros issuers list --context my-app
 vectros issuers get primary --context my-app
+vectros issuers update primary --context my-app --status suspended
+vectros issuers delete primary --context my-app   # re-types the id to confirm
 ```
 
 | Subcommand | Flags | Notes |
 |---|---|---|
+| `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. |
+| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--tenant test\|live` | Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. |
+| `delete <issuerId>` | `--context <contextId>` (required), `--force`, `--tenant test\|live` | Re-types the issuer id to confirm (mirrors `context destroy`); `--force` skips the prompt and is required when stdin isn't a TTY. Refused server-side while any user was ever created or matched through this issuer. |
 | `list` | `--context <contextId>` (required), `--tenant test\|live` | Every issuer registered in that context. `--context` has no default — an issuer read is confined to the context you name; there's no tenant-wide "every issuer in every context" view. |
 | `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies. |
 
-Both accept `--json`, plus the common auth flags (`--base-url`, `--token`).
+All five accept `--json`, plus the common auth flags (`--base-url`, `--token`).
+
+## `vectros namespace` — scope-namespace registrations
+
+Register and inspect the namespaces a `scope:<namespace>` value can belong
+to — whether values in that namespace must resolve to a real identity entity
+(`entityBacked`, the same field `identity create --type <namespace>`
+relies on) or are free-form strings. Registering a brand-new namespace (e.g.
+a `practice`/`team` entity dimension) was blueprint-apply-only before this
+command existed.
+
+```bash
+vectros namespace register practice --context my-app --specificity-rank 1500 --entity-backed
+vectros namespace list                        # tenant-wide registrations
+vectros namespace list --context my-app       # just my-app's own
+vectros namespace get practice --context my-app
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `register <name>` | `--context`, `--specificity-rank <n>` (both required); `--entity-backed`, `--default-schema-id <id>` | NOT idempotent — a repeat name 400s (unlike `issuers register`). `--context` has no tenant-wide option here — a confined credential may only register against its own bound context. |
+| `list` | `--context <contextId>` (optional) | Omit for every tenant-wide registration; supply for one context's own. |
+| `get <name>` | `--context <contextId>` (optional) | Same two-mode read as `list`. |
+
+No `update`/`delete` — both routes require a genuine root API key on the
+platform side, which this CLI never holds, so neither could ever succeed
+here. All three subcommands accept `--json`.
 
 ## `vectros identity` — tenant-wide principals
 
@@ -190,12 +229,13 @@ vectros identity invite --context my-app --role editor --email bob@example.com \
 | | `--type user` only: `--email <email>`, `--service` (mint a SERVICE principal; default HUMAN) | `--name`/`--scope` are rejected for `--type user`. |
 | | entity namespaces only: `--name <name>`, `--scope <ns:value>` (repeatable, up to 2 parent ownership edges) | `--email`/`--service` are rejected for an entity namespace. |
 | | both: `--metadata <json>` | Free-form JSON object. |
-| `list` | `--type <user\|namespace>` (required), `--external-id <id>` (filter), `--limit <n>` | Omit `--limit` and the CLI drains every page for the complete set; pass `--limit` (1–100) and it returns exactly one page of that size instead. |
+| `list` | `--type <user\|namespace>` (required), `--external-id <id>` (filter), `--limit <n>` | Scoped to your own context — see `list-all` below for a user created but never granted access anywhere. Omit `--limit` and the CLI drains every page for the complete set; pass `--limit` (1–100) and it returns exactly one page of that size instead. |
+| `list-all` | `--external-id <id>` (filter), `--tenant test\|live`, `--limit <n>` | **Users only, and requires an account owner login.** Lists every user in the tenant, regardless of app-context access — for recovering a user `identity list` can never show you: one created but not (yet) granted access anywhere, so no context-scoped view can ever reach it, and a `create` retry with the same `--external-id` just collides with the same invisible row. Find it here by `--external-id`, then grant it access or `identity delete` it with an ordinary credential. |
 | `get` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required) | `--id` is the Vectros-assigned id from `create`/`list`, not the `--external-id`. |
 | `delete` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required) | |
 | `invite` | `--context <c>`, `--role <roleId>`, `--email <e>` (all required); `--first-name <n>`, `--accept-url <url>`, `--no-send-email` | Onboards a person into a context by email (`POST /v1/users/invite`) — no root key required, your `vectros login` session already carries enough scope. `--role` is an existing Role's own id (no separate lookup). `--accept-url` is required unless `--no-send-email` is given, in which case the response carries the raw `inviteToken`/`acceptLink` for you to deliver yourself. |
 
-`create`/`list`/`get`/`invite` accept `--json`; `delete` does not.
+`create`/`list`/`list-all`/`get`/`invite` accept `--json`; `delete` does not.
 
 ## `vectros role` — reusable, context-scoped access rules
 
@@ -210,6 +250,8 @@ vectros role create --context my-app --role-id editor --name Editor \
   --actions records:cru,search:r
 vectros role create --context my-app --role-id own-org --name "Own org" \
   --actions records:r --data-scope '{"scope:org":["<orgId>", null]}'
+vectros role create --context my-app --role-id hr-admin --name "HR Admin" \
+  --actions records:cru --assumable '{"scope:org":["org_engineering", "org_sales"]}'
 vectros role list --context my-app
 vectros role get --context my-app --role-id editor
 vectros role delete --context my-app --role-id editor
@@ -217,13 +259,35 @@ vectros role delete --context my-app --role-id editor
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--description <text>` | Idempotent by `roleId`. `--data-scope` confines the clause to owned data — a JSON map of ownership dimension → allowed values, ANDed across keys (e.g. `{"userId":["${{ self.userId }}"]}`, or `{"scope:org":["<orgId>", null]}` — the `null` entry additionally admits scope-less/tenant-shared records). Keys must be `userId` or `scope:<namespace>` (the legacy flat `orgId`/`clientId` keys are rejected server-side). |
+| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--assumable <json>`, `--description <text>` | Idempotent by `roleId`. `--data-scope` confines the clause to owned data — a JSON map of ownership dimension → allowed values, ANDed across keys (e.g. `{"userId":["${{ self.userId }}"]}`, or `{"scope:org":["<orgId>", null]}` — the `null` entry additionally admits scope-less/tenant-shared records). Keys must be `userId` or `scope:<namespace>` (the legacy flat `orgId`/`clientId` keys are rejected server-side). `--assumable` is a SEPARATE, role-level grant — a JSON map of `scope:<namespace>` → allowed values naming which values a holder of this role may switch into via `vectros assume`; holding broad `--data-scope` reach in a namespace does not by itself grant assuming any value in it. |
 | `list` | `--context <c>` (required) | |
-| `get` | `--context <c>`, `--role-id <id>` (both required) | Also shows the role's `assumable` grant (which values, per namespace, a holder of this role may become via `POST /v1/auth/token/assume`), if any is set. `role create` has no `--assumable` flag today — author it via a blueprint's `roleAssumable:` block or a direct API call. |
+| `get` | `--context <c>`, `--role-id <id>` (both required) | Also shows the role's `assumable` grant, if any is set. |
 | `delete` | `--context <c>`, `--role-id <id>` (both required) | No cascade — any access profile still referencing the role fails to mint (not silently downgraded) until reassigned. |
 
 `create`/`list`/`get` accept `--json`; `delete` does not.
 
+## `vectros assume` — switch identity namespace values on your own token
+
+Re-mints your own verb token with one or more `identity.<namespace>` values
+switched — the "org switcher" flow, named (like the platform endpoint it
+calls) after AWS STS `AssumeRole`. Only works if a role you currently hold
+explicitly grants assuming the requested value(s) via that role's own
+`--assumable` grant (checked live against your CURRENT roles, never a value
+frozen into your token at mint time).
+
+```bash
+vectros assume --context my-app --scope org:org_sales
+```
+
+| Flags | Notes |
+|---|---|
+| `--context <c>` (required), `--scope <ns:value>` (repeatable, at least one required) | Each `--scope` becomes one `scope:<namespace>` entry in the request. No artificial cap on how many namespaces you name — the platform requires a SINGLE role to jointly grant the whole combination and rejects an unsatisfiable one itself. |
+
+Prints the re-minted `access_token`/`expires_in` (accepts `--json`) — there
+is no `--to-keyring` here, since the result is an ephemeral bearer token
+with the same remaining lifetime as the verb token this command itself
+mints to make the call, not a durable secret the keyring is built to hold.
+
 ## `vectros access` — bind principals to contexts
 
 The binding layer between an identity and a context: `access grant` joins a
@@ -437,10 +501,10 @@ A blueprint's `accessProfile` and role clauses may also declare
 `capabilities: [...]` — named platform effects (like creating or removing an
 identity in your tenant) that reach across a partition boundary in a way no
 `resource:ops` verb can express. This rides a field entirely separate from
-`allowedActions`, and it has its own allowlist: **only `member-lifecycle` is
-admitted today.** Every other capability name — including ones the platform's
-own registry recognizes — is refused, the same fail-closed, deliberately-widen
-posture as the scope gate above. `vectros blueprint validate`/`plan` and
+`allowedActions`, and it has its own allowlist: **`member-lifecycle` and
+`delegate-principal-stamp` are admitted today.** Every other capability name —
+including ones the platform's own registry recognizes — is refused, the same
+fail-closed, deliberately-widen posture as the scope gate above. `vectros blueprint validate`/`plan` and
 `bootstrap` all report a rejected capability the same way they report a
 rejected scope: nothing mints, and the CLI exits non-zero.