@vectros-ai/cli 0.9.0 → 0.11.0

package/AUTHORING.md

@@ -142,8 +142,9 @@ accessProfile:
   allowedActions: [records:r, records:c, records:u, search:r, schemas:r]
   # dataScope binds the key to specific owners. Include `null` to ALSO grant
   # tenant-level (shared) records — without it the key sees ONLY the listed
-  # owners' records, not shared/seed data:
-  # dataScope: { orgId: [<org-uuid>, null] }
+  # owners' records, not shared/seed data. Keys are userId + namespaced scopes
+  # (scope:org, scope:client, ...):
+  # dataScope: { "scope:org": [<org-uuid>, null] }
 
 servicePrincipal:
   externalId: my-thing-sp   # stable; the principal the profile + key bind to
@@ -214,7 +215,7 @@ than one surface, so the surface disambiguates which lookup resolves the link):
 - fieldId: establishedByDecision
   fieldType: reference
   targetTypeName: decision      # the typeName it points at
-  targetSurface: record         # record | document | user | org | client (REQUIRED)
+  targetSurface: record         # record | document | user | a namespace (org, client, ...) — REQUIRED
   targetField: externalId       # the target's UNIQUE lookup to match (defaults to externalId)
   cardinality: one              # one (a single id) | many (an array of ids)
 ```
@@ -243,6 +244,13 @@ principal's `externalId`, the per-machine key name, and each seed record's
 `externalId`. Bump `version` when you evolve a blueprint. (Note: schema
 `typeName` is immutable after first apply.)
 
+**Pair `:r` with every `:c` you request.** Being handed back an existing item
+on a re-apply collision is a read of that item, not part of create authority —
+so a `records:c`-only `accessProfile.allowedActions` converges on first apply
+but fails on every re-apply with an "already exists" error instead of the
+existing record. Request `:r` alongside `:c` on every resource your blueprint
+creates (the bundled blueprints all do this — see the example above).
+
 ## Distribution
 
 - **Bundled** — reviewed, versioned blueprints shipped in the library

package/CHANGELOG.md

@@ -3,6 +3,95 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.11.0
+
+### Fixed
+
+- **`access explain` no longer previews access that the platform denies.** A clause keyed on an
+  unrecognized ownership dimension — a retired `orgId`/`clientId`, or an invalid
+  `scope:<namespace>` — now shows as granting nothing, matching how the server evaluates it,
+  instead of appearing to grant records the credential cannot actually reach. The dead clause is
+  shown explicitly rather than silently dropped.
+
+### Changed
+
+- **Clearer errors for expired sessions and rate limits.** When a command fails because your
+  login has expired, the CLI now tells you to run `vectros login` and retry; a rate-limited
+  request tells you to wait and retry. Failures that carry a typed error code surface it on the
+  support line alongside the request id.
+- **`bootstrap` warns when seeded sample data could not be indexed.** If a seed record or document
+  is stored but not (fully) searchable, the run summary now says so — and why — instead of
+  reporting it as fully seeded.
+
+## 0.10.0
+
+### Changed (breaking)
+
+- **Organization and client identities are now namespaces.** `org` and `client`
+  join any namespace you define (teams, projects, …), so the `identity` command
+  and ownership flags generalize:
+  - `identity create|list|get|delete --type <user|namespace>` — `user` for a
+    user, or a namespace (`org`, `client`, or one you define). `--type org` and
+    `--type client` keep working.
+  - `--scope <namespace>:<value>` (repeatable) replaces `--org <id>` on
+    `identity create`, `access grant`, and `join` — e.g. `--scope org:<id>`.
+  - Schema ownership in blueprints uses `scopes` instead of `orgId` / `clientId`,
+    and `--data-scope` keys use the `scope:<namespace>` form. The old `orgId` /
+    `clientId` keys are no longer accepted.
+
+### Added
+
+- **Keys are now kept in your OS credential store** (Windows Credential Manager,
+  Linux Secret Service) instead of an encrypted file, on machines that have one —
+  so a copy of your `~/.vectros` directory no longer gives up a key. Existing
+  secrets migrate automatically the first time each key is used. Where no store is
+  usable (a headless Linux box, or no prebuilt for the optional native package) the
+  encrypted file remains the fallback. Set `VECTROS_KEYRING_BACKEND=file` to opt
+  out. macOS keeps using the encrypted file for now. Note: `vectros bootstrap`
+  still writes its key as plain JSON to `~/.vectros/<pack>.key.json`, so treat
+  `~/.vectros` as a secret if you use it.
+- **The keyring is now a credential helper.** `keyring show --format raw` prints
+  the bare secret and is the contract other tools resolve through:
+  `@vectros-ai/mcp-server` 0.10.0+ runs it when `VECTROS_API_KEY` is unset, so a
+  key lives in the keyring instead of being copied into each tool's config. Set
+  `VECTROS_KEYRING_ALIAS` to target a specific entry.
+- **`vectros keyring doctor`** — a health check for the keyring: the active entry,
+  whether each secret is readable, where each lives, and which hold live keys.
+  Exits non-zero when it finds anything to fix; `--json` for scripts.
+- **`vectros keyring prune`** — drop orphaned entries (an index entry with no
+  stored secret). Narrow by design: an entry whose secret is merely unreadable or
+  locked is reported, never removed. `--dry-run` previews; `--force` skips the prompt.
+- **`vectros context list` now enumerates the whole tenant**, not just contexts you
+  have joined, with an `active`/`purging` status column. `--mine` limits it to the
+  contexts you hold an access profile in. Now account-owner-only (a sub-user reads a
+  single context with `context get`).
+- **`vectros key list --all-contexts`** — every active scoped key across all your
+  contexts and both tenants, the account-wide view a context-scoped `key list`
+  cannot show. Owner-only.
+- **Actionable error messages** for known server errors — the active-key limit
+  (enumerate → revoke → retry), a 403 (owner/scope), a 404 (`context list`) —
+  instead of the raw SDK error. Correlation id under `VECTROS_MCP_DEBUG`.
+- **`bootstrap` apply is now legible** — the preview states that apply is a
+  non-destructive reconcile, and each resource reports `created` vs `reconciled`.
+
+### Fixed
+
+- **Two `vectros` commands running at once can no longer lose each other's keyring
+  entries** — index updates now take a lock and queue instead of overwriting. A
+  process killed mid-write leaves a lock the next command clears automatically.
+- **`vectros keyring remove` refuses instead of silently stranding a key.** If it
+  cannot confirm the secret was deleted (a locked store), it declines and prints the
+  key id rather than discarding the only local record of a still-live key.
+- **`vectros join` now reports a key it had to abandon** — when a replaced key's
+  secret cannot be deleted, it prints that key's id and the `vectros key revoke`
+  command, the last time you will see the id.
+
+### Changed
+
+- The internal `--env` flag is no longer advertised in customer-facing output (help
+  text, examples, the post-login hint). It remains fully functional; production is
+  the default.
+
 ## 0.9.0
 
 ### Added

package/README.md

@@ -3,15 +3,17 @@
 [![npm](https://img.shields.io/npm/v/@vectros-ai/cli)](https://www.npmjs.com/package/@vectros-ai/cli)
 [![license](https://img.shields.io/npm/l/@vectros-ai/cli)](https://www.apache.org/licenses/LICENSE-2.0)
 
-The Vectros provisioning CLI — the `vectros` binary. Two command groups:
+The Vectros provisioning CLI — the `vectros` binary:
 
 - **`vectros bootstrap`** — provision a least-privilege MCP credential (+ optional blueprint).
 - **`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 keyring`** — hold several identities on one machine, pick which is active, and let other tools resolve keys from one place.
 
 ```bash
 npx -y @vectros-ai/cli bootstrap          # provision a credential
 npx -y @vectros-ai/cli blueprint --help   # the authoring commands
+npx -y @vectros-ai/cli keyring list       # the identities on this machine
 ```
 
 Every command has `--help`. The authoring loop is documented in
@@ -108,6 +110,76 @@ Exit `0` = applied and every assertion passed; `1` = an assertion failed or appl
 errored; `2` = no credential, or the blueprint requested control-plane scope.
 The app-context is intentionally **not** deleted (it's idempotent and reused).
 
+## `vectros keyring` — one home for your keys
+
+A machine can hold several Vectros identities (one per context or principal).
+The keyring stores them as named entries plus one **active** pointer, so you can
+switch between them without re-issuing keys. `vectros join <context>` adds an
+entry and activates it; `vectros switch <alias>` flips the active one.
+
+```bash
+vectros keyring list                 # the entries; * marks the active one
+vectros switch <alias>               # make <alias> active  (= keyring use)
+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 remove <alias>       # drop one entry + its secret
+```
+
+These are local — no network, no auth. The index itself never holds a secret.
+
+**Where your keys are kept.** In your **OS credential store** (Windows Credential
+Manager, Linux Secret Service) where one is available, so they are protected by
+your OS login. Where none is — a headless Linux box with no Secret Service, or a
+platform with no prebuilt for the optional native package — the CLI falls back to
+an encrypted file under `~/.vectros/secrets` rather than failing. Be aware of what
+that fallback does and doesn't buy you: it protects a single stray `.enc` file, but
+its encryption key is derived from material stored alongside it, so anyone with a
+copy of your **whole `~/.vectros` directory** can decrypt it. Treat that directory
+as a secret in its own right. `vectros keyring doctor` tells you which store you
+are on and why; `VECTROS_KEYRING_BACKEND=file` forces the fallback (existing keychain keys keep
+working and move back to the file as you use them).
+
+On **macOS** the encrypted file is used for now. A Keychain item grants access to
+the application that created it and prompts for anything else — and the
+"application" here is the `node` binary running this CLI, which is not stable
+across installs. We expect that to put a password prompt in the startup path of
+any tool resolving a key unattended, which on a headless host nobody can answer.
+We have not yet verified it on real hardware, and would rather ship the honest
+fallback than a claim we haven't tested.
+
+Upgrading from an older CLI needs no action: an existing encrypted secret moves
+into the credential store the first time that key is used.
+
+**Resolving a key from another tool.** `keyring show --format raw` prints the bare
+secret and nothing else, which makes it a credential helper in the shape of
+`git credential` / `docker-credential-*` / `aws credential_process`:
+
+```bash
+export VECTROS_API_KEY=$(vectros keyring show --format raw)                      # active
+export VECTROS_API_KEY=$(vectros keyring show --format raw --alias support-bot)  # a specific entry
+```
+
+[`@vectros-ai/mcp-server`](https://www.npmjs.com/package/@vectros-ai/mcp-server)
+does this for you: leave `VECTROS_API_KEY` unset and it resolves the key from
+this keyring, so you don't paste a copy into its config. Exit codes: `0` secret
+printed, `2` no such (or no active) entry, `1` the entry exists but its secret
+can't be read.
+
+**When something's off**, `vectros keyring doctor` is the first stop — it shows
+which entry is active, whether each secret is readable, which entries are live
+keys (the ones that act on real data), and which store is holding them, exiting
+non-zero when it finds something to fix.
+
+`vectros keyring prune` drops entries whose secret is gone, but only where "gone"
+is knowable — that is, on the encrypted-file store. **Entries kept in the OS
+credential store are never pruned.** That store can't tell us "no such secret"
+apart from "couldn't read it right now", so a locked keychain would otherwise
+look like a keyring full of dead entries; deleting one would throw away the key
+id you need to revoke a key that may still be live. Use
+`vectros keyring remove <alias>` to drop one deliberately.
+
 ## The scope gate (the trust boundary)
 
 Blueprints are **untrusted input** (agent- or community-authored) and the

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,117 @@
+# Third-party notices
+
+`@vectros-ai/cli` compiles the following third-party packages directly into its
+published binary (`dist/cli.js`). Their licenses require that these notices travel
+with the code, so they are reproduced in full below.
+
+This file is GENERATED by `pipelines/third_party_notices.mjs` from the `noExternal`
+lists in `packages/*/tsup.config.ts`. Do not edit it by hand — run
+`node pipelines/third_party_notices.mjs --write`. CI fails if it is stale, because a
+notices file that silently drifts is worse than none: it asserts a compliance that
+nobody checked.
+
+Packages resolved at RUNTIME (ordinary dependencies) are not listed here — the
+consumer's own install carries their licenses.
+
+---
+
+## graceful-fs 4.2.11
+
+License: ISC
+
+```
+The ISC License
+
+Copyright (c) 2011-2022 Isaac Z. Schlueter, Ben Noordhuis, and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+## proper-lockfile 4.1.2
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## retry 0.12.0
+
+License: MIT
+
+```
+Copyright (c) 2011:
+Tim Koschützki (tim@debuggable.com)
+Felix Geisendörfer (felix@debuggable.com)
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.
+```
+
+## signal-exit 3.0.7
+
+License: ISC
+
+```
+The ISC License
+
+Copyright (c) 2015, Contributors
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyright notice and this permission notice
+appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE
+LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```