@vectros-ai/cli 0.10.0 → 0.11.0

package/AUTHORING.md

@@ -244,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,26 @@
 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)

package/dist/cli.js

@@ -1614,7 +1614,7 @@ var require_proper_lockfile = __commonJS({
 // src/cli-bootstrap.ts
 var readline = __toESM(require("readline/promises"));
 
-// node_modules/@vectros-ai/sdk/dist/index.mjs
+// ../../node_modules/@vectros-ai/sdk/dist/index.mjs
 var __defProp2 = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -1649,6 +1649,7 @@ __export(api_exports, {
   FileUploadRequest: () => FileUploadRequest,
   ForbiddenError: () => ForbiddenError,
   IdentityLookupRequest: () => IdentityLookupRequest,
+  IndexFailure: () => IndexFailure,
   InternalServerError: () => InternalServerError,
   ListEntitiesRequestOrder: () => ListEntitiesRequestOrder,
   ListUsersRequestOrder: () => ListUsersRequestOrder,
@@ -2170,6 +2171,17 @@ var IdentityLookupRequest;
     Desc: "desc"
   };
 })(IdentityLookupRequest || (IdentityLookupRequest = {}));
+var IndexFailure;
+((IndexFailure2) => {
+  IndexFailure2.Code = {
+    SourceUnavailable: "SOURCE_UNAVAILABLE",
+    TextIndexFailed: "TEXT_INDEX_FAILED",
+    EmbeddingFailed: "EMBEDDING_FAILED",
+    IndexingFailed: "INDEXING_FAILED",
+    VectorLimitExceeded: "VECTOR_LIMIT_EXCEEDED",
+    Internal: "INTERNAL"
+  };
+})(IndexFailure || (IndexFailure = {}));
 var ModelDataVersionResponse;
 ((ModelDataVersionResponse2) => {
   ModelDataVersionResponse2.ChangeType = {
@@ -5686,7 +5698,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user, organization, or client. Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
+   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user or identity entity (in any namespace). Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
    *
    * @param {Vectros.TokenRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5903,7 +5915,7 @@ var ComplianceClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Submits a right-to-erasure request for a single end-subject (a user, client, or organization). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
+   * Submits a right-to-erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
    *
    * @param {Vectros.ErasureRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -12480,19 +12492,21 @@ function extractServerError(err) {
     const statusCode = typeof e.statusCode === "number" ? e.statusCode : void 0;
     let serverMessage;
     let requestId;
+    let errorCode;
     if (e.body && typeof e.body === "object") {
       const b = e.body;
       if (typeof b.message === "string" && b.message.trim()) serverMessage = b.message.trim();
       if (typeof b.requestId === "string" && b.requestId.trim()) requestId = b.requestId.trim();
+      if (typeof b.errorCode === "string" && b.errorCode.trim()) errorCode = b.errorCode.trim();
     } else if (typeof e.body === "string" && e.body.trim()) {
       serverMessage = e.body.trim();
     }
-    if (serverMessage) return { statusCode, message: serverMessage, requestId };
+    if (serverMessage) return { statusCode, message: serverMessage, requestId, errorCode };
     const message = typeof e.message === "string" ? e.message : "";
     const isSdkEnvelope = /\nStatus code:/.test(message);
-    if (message && !isSdkEnvelope) return { statusCode, message, requestId };
-    if (statusCode) return { statusCode, message: `HTTP ${statusCode}`, requestId };
-    if (message) return { statusCode, message, requestId };
+    if (message && !isSdkEnvelope) return { statusCode, message, requestId, errorCode };
+    if (statusCode) return { statusCode, message: `HTTP ${statusCode}`, requestId, errorCode };
+    if (message) return { statusCode, message, requestId, errorCode };
   }
   return { message: String(err) };
 }
@@ -12503,15 +12517,17 @@ async function devRouteError(res, action) {
   const raw = await res.text().catch(() => "");
   let message;
   let requestId;
+  let errorCode;
   try {
     const parsed = JSON.parse(raw);
     if (typeof parsed.message === "string" && parsed.message.trim()) message = parsed.message.trim();
     if (typeof parsed.requestId === "string" && parsed.requestId.trim()) requestId = parsed.requestId.trim();
+    if (typeof parsed.errorCode === "string" && parsed.errorCode.trim()) errorCode = parsed.errorCode.trim();
   } catch {
   }
   const err = new Error(`${action}: HTTP ${res.status}`);
   err.statusCode = res.status;
-  err.body = { message: message ?? `HTTP ${res.status}`, requestId };
+  err.body = { message: message ?? `HTTP ${res.status}`, requestId, errorCode };
   return err;
 }
 function formatCliError(err, opts) {
@@ -12520,14 +12536,28 @@ function formatCliError(err, opts) {
   const block = actionable ?? `  \u2716 ${opts.action}: ${info.message}
 `;
   const debug = opts.debug ?? Boolean(process.env.VECTROS_MCP_DEBUG);
-  if (debug && info.requestId) {
-    return `${block}    (requestId: ${info.requestId} \u2014 quote this to support)
+  if (debug && (info.requestId || info.errorCode)) {
+    const parts = [
+      info.errorCode ? `errorCode: ${info.errorCode}` : null,
+      info.requestId ? `requestId: ${info.requestId}` : null
+    ].filter(Boolean);
+    return `${block}    (${parts.join(", ")} \u2014 quote this to support)
 `;
   }
   return block;
 }
 function renderActionableError(info) {
   const msg = info.message;
+  switch (info.errorCode) {
+    case "SESSION_REFRESH_REQUIRED":
+      return `  \u2716 Your session has expired.
+    Run 'vectros login' to re-authenticate, then retry.
+`;
+    case "RATE_LIMITED":
+      return `  \u2716 ${msg}
+    You're being rate-limited \u2014 wait a moment and retry.
+`;
+  }
   if (/scoped-key limit reached/i.test(msg)) {
     const plan = /plan '([^']+)'/i.exec(msg)?.[1];
     const count = /\((\d+) active keys\)/i.exec(msg)?.[1];
@@ -13076,8 +13106,13 @@ var KNOWN_CONTROL_PLANE_RESOURCES = [
   "users",
   "billing",
   "admin",
-  "clients",
-  "orgs"
+  // Identity/compartment provisioning. The flat `orgs`/`clients` resources were
+  // folded into the generic `entities` (per-namespace) + `namespaces` surfaces,
+  // which is what the API now scopes on — so those are the current spellings a
+  // pack could name. (Cosmetic: any non-data-plane resource hard-rejects whether
+  // or not it is listed here; this list only sharpens the error message.)
+  "entities",
+  "namespaces"
 ];
 var VALID_OPS = /* @__PURE__ */ new Set(["c", "r", "u", "d"]);
 var DATA_PLANE_SET = new Set(DATA_PLANE_ALLOWLIST);
@@ -13524,6 +13559,21 @@ async function runLoader(client, input) {
   let seededCount = 0;
   const seededRecordIds = [];
   const seededDocumentIds = [];
+  const seedIndexFailures = [];
+  const noteIfIndexFailed = (created, rec, surface) => {
+    if (created.indexStatus !== "FAILED") return;
+    seedIndexFailures.push({
+      externalId: rec.externalId,
+      typeName: rec.typeName,
+      surface,
+      code: created.indexFailure?.code,
+      message: created.indexFailure?.message
+    });
+    log.warn(
+      { component: "loader", typeName: rec.typeName, externalId: rec.externalId, code: created.indexFailure?.code },
+      "seed stored but failed to index"
+    );
+  };
   for (const rec of skipSeed ? [] : blueprint.seed ?? []) {
     const schemaId = schemaIds[rec.typeName];
     if (!schemaId) {
@@ -13544,6 +13594,7 @@ async function runLoader(client, input) {
         }
       });
       if (created.id) seededDocumentIds.push(created.id);
+      noteIfIndexFailed(created, rec, "document");
     } else {
       const created = await ctxClient.records.createRecord({
         body: {
@@ -13555,6 +13606,7 @@ async function runLoader(client, input) {
         }
       });
       if (created.id) seededRecordIds.push(created.id);
+      noteIfIndexFailed(created, rec, "record");
     }
     seededCount++;
   }
@@ -13573,7 +13625,8 @@ async function runLoader(client, input) {
     roleIds,
     seededCount,
     seededRecordIds,
-    seededDocumentIds
+    seededDocumentIds,
+    seedIndexFailures
   };
 }
 function buildPlan(blueprint, opts = {}) {
@@ -13828,6 +13881,17 @@ function seedSummaryLine(opts) {
   return opts.seededCount ? `  \u2714 Seeded ${opts.seededCount} record(s)
 ` : "";
 }
+function seedIndexWarningBlock(failures) {
+  if (failures.length === 0) return "";
+  const lines = failures.map((f) => {
+    const reason = f.message ?? f.code ?? "indexing failed";
+    return `      \u2022 ${f.typeName}/${f.externalId} (${f.surface}): ${reason}
+`;
+  });
+  return `  \u26A0 ${failures.length} seed(s) stored but not fully searchable:
+` + lines.join("") + `    They're stored and retrievable by id, but won't appear in search until the issue above is resolved.
+`;
+}
 function reconcileTally(items, noun) {
   if (items.length === 0) return null;
   const created = items.filter((i) => i.action === "created").length;
@@ -14084,7 +14148,7 @@ ${renderPlan(blueprint, planSteps)}
         noSeed,
         declinedInteractively: seedDeclinedInteractively,
         seededCount: result.seededCount
-      })
+      }) + seedIndexWarningBlock(result.seedIndexFailures)
     );
     const entry = buildVectrosServerEntry({ apiKey: result.rawKey, apiBaseUrl: baseUrl });
     const isCode = args.client === "code";
@@ -15365,6 +15429,25 @@ function canonicalDim(key) {
   if (key === "userId" || key === "partnerUserId") return "user";
   return key;
 }
+var FORBIDDEN_SCOPE_NAMESPACES = /* @__PURE__ */ new Set([
+  "user",
+  "record",
+  "document",
+  "entity",
+  "self",
+  "tenant",
+  "context",
+  "scope",
+  "versions",
+  "lookup"
+]);
+var SCOPE_NAMESPACE_RE = /^[a-z][a-z0-9_-]{1,31}$/;
+function isRecognizedOwnershipKey(key) {
+  if (key === "userId" || key === "partnerUserId") return true;
+  if (!key.startsWith("scope:")) return false;
+  const ns = key.slice("scope:".length);
+  return !FORBIDDEN_SCOPE_NAMESPACES.has(ns) && SCOPE_NAMESPACE_RE.test(ns);
+}
 var SELF_TOKEN_RE2 = /^\$\{\{\s*self\.[a-zA-Z.]+\s*\}\}$/;
 function normalizeClauses(raw) {
   const out = [];
@@ -15374,15 +15457,18 @@ function normalizeClauses(raw) {
     const actions = obj.allowed_actions ?? obj.allowedActions ?? [];
     const ds = obj.data_scope ?? obj.dataScope ?? {};
     const dataScope = {};
+    const unrecognizedDims = [];
     for (const [k, v] of Object.entries(ds)) {
+      const dim = canonicalDim(k);
       const values = Array.isArray(v) ? v : [v];
-      dataScope[canonicalDim(k)] = values.map((val) => {
+      dataScope[dim] = values.map((val) => {
         if (val === null) return null;
         const s = String(val);
         return SELF_TOKEN_RE2.test(s) ? SELF : s;
       });
+      if (!isRecognizedOwnershipKey(k)) unrecognizedDims.push(k);
     }
-    out.push({ actions: Array.isArray(actions) ? actions.map(String) : [], dataScope });
+    out.push({ actions: Array.isArray(actions) ? actions.map(String) : [], dataScope, unrecognizedDims });
   }
   return out;
 }
@@ -15393,6 +15479,7 @@ function buildArchetypes(clauses) {
   ];
   const scopeDims = /* @__PURE__ */ new Map();
   for (const c of clauses) {
+    if (c.unrecognizedDims.length > 0) continue;
     for (const [dim, values] of Object.entries(c.dataScope)) {
       if (dim === "user") continue;
       const set = scopeDims.get(dim) ?? /* @__PURE__ */ new Set();
@@ -15416,6 +15503,7 @@ function buildArchetypes(clauses) {
   return rows;
 }
 function clauseMatches(clause, arch) {
+  if (clause.unrecognizedDims.length > 0) return false;
   for (const [dim, allowed] of Object.entries(clause.dataScope)) {
     const recordValue = arch.owners[dim];
     const ok = allowed.some((a) => {
@@ -15481,7 +15569,14 @@ async function runAccessExplain(opts, deps = {}) {
             context: opts.context,
             via,
             identityOverrides: profile.identityOverrides,
-            clauses: clauses.map((c, i) => ({ n: i + 1, actions: c.actions, dataScope: renderDataScope(c.dataScope) })),
+            clauses: clauses.map((c, i) => ({
+              n: i + 1,
+              actions: c.actions,
+              dataScope: renderDataScope(c.dataScope),
+              // Present only on a dead clause — an unrecognized dim the platform
+              // denies (a retired key or a bad scope:<ns>); the matrix omits it.
+              ...c.unrecognizedDims.length > 0 ? { grantsNothing: true, unrecognizedDims: c.unrecognizedDims } : {}
+            })),
             matrix: rows,
             note: "Ownership dimensions only: per-type action qualifiers narrow further, and search/RAG visibility is bounded per row by the same clause's typed read grants. Client-side preview; the platform decides at request time."
           })}
@@ -15500,6 +15595,12 @@ async function runAccessExplain(opts, deps = {}) {
       clauses.forEach((c, i) => {
         process.stdout.write(`    ${i + 1}. [${c.actions.join(", ")}]  where ${renderDataScope(c.dataScope)}
 `);
+        if (c.unrecognizedDims.length > 0) {
+          process.stdout.write(
+            `       \u2716 grants nothing \u2014 unrecognized dimension${c.unrecognizedDims.length > 1 ? "s" : ""}: ${c.unrecognizedDims.join(", ")} (the platform denies a clause keyed on any dim that is not userId or a valid scope:<namespace>)
+`
+          );
+        }
       });
       process.stdout.write(
         "\n" + formatTable(rows, [
@@ -18245,8 +18346,8 @@ function emitJoined(alias, context, principalId, role, keyId, reused) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.10.0" : "dev",
-  sdk: true ? "0.35.0" : "dev",
+  cli: true ? "0.11.0" : "dev",
+  sdk: true ? "0.36.0" : "dev",
   blueprints: true ? "0.8.0" : "dev"
 };
 function formatBuildInfo() {