@vectros-ai/cli 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.6.6 — 2026-07-03
+
+### Changed
+
+- **Bundled blueprint library updated to `@vectros-ai/blueprints` 0.6.4.** The
+  `agentic-sdlc` blueprint's record schemas (`control` / `convention` / `gotcha` /
+  `term`) now carry a `sourceRef` provenance field — the sync-back index that lets a
+  knowledge base stay in sync with the repo it mirrors — and its bundled guide and
+  agent prompt document that sync pattern. No CLI command or flag changes.
+- Updated the bundled `@vectros-ai/sdk` to **0.32.0**, keeping the CLI aligned with
+  the current Vectros API. Documents gained a lifecycle `status` (archive/restore
+  without deleting) and their processing state moved to `indexStatus`; no CLI
+  command or flag changes.
+
+## 0.6.5 — 2026-07-01
+
+### Added
+
+- **Find your own user id without hunting for it.** `vectros whoami` now shows
+  **`your user id`** (`usr_<...>`), and `vectros access grant`/`revoke`/`list`/`get`
+  accept **`--principal me`** as an alias for your own user — so joining yourself to
+  a context is a one-liner with no id lookup:
+  `vectros access grant --principal me --context <ctx> --role <role>`.
+  Resolution is client-side (your login's email matched against the tenant's users);
+  if it can't be resolved, `whoami` shows `—` and `--principal me` prints how to pass
+  the id explicitly (`vectros identity list --type user`).
+
 ## 0.6.4 — 2026-06-29
 
 ### Fixed

package/dist/cli.js

@@ -504,10 +504,18 @@ var DocumentRequest;
     Text: "TEXT",
     None: "NONE"
   };
+  DocumentRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
 })(DocumentRequest || (DocumentRequest = {}));
 var DocumentResponse;
 ((DocumentResponse2) => {
   DocumentResponse2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
+  DocumentResponse2.IndexStatus = {
     PendingUpload: "PENDING_UPLOAD",
     Uploaded: "UPLOADED",
     Extracting: "EXTRACTING",
@@ -5278,7 +5286,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/versions");
   }
   /**
-   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body; `?upsert=true` requires the `documents:u` scope). Requires the `documents:c` scope.
+   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata).
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9671,9 +9679,22 @@ var codingAgentMemory = {
   ]
 };
 var coding_agent_memory_default = codingAgentMemory;
+var DATA_PLANE_ACTIONS = [
+  "records:r",
+  "records:c",
+  "records:u",
+  "search:r",
+  "schemas:r",
+  "inference:r",
+  "documents:r",
+  "documents:c",
+  "folders:r",
+  "folders:c"
+];
+var EDITOR_ACTIONS = [...DATA_PLANE_ACTIONS, "records:d", "documents:d", "folders:d"];
 var agenticSdlc = {
   name: "agentic-sdlc",
-  version: "1.0.0",
+  version: "1.2.0",
   description: "A whole-SDLC system of record for an AI development team \u2014 decisions, designs, references, runbooks, post-mortems (as documents) plus controls, conventions, gotchas, and a glossary (as records), cross-linked and recalled by meaning.",
   contextId: "agentic-sdlc",
   contextName: "Agentic SDLC Knowledge Base",
@@ -10108,6 +10129,19 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 last-reviewed date. Range-queryable.",
           renderHints: { label: "Reviewed on", widget: "date", order: 12 }
+        },
+        {
+          // Provenance for sync: the source file this record was distilled from. A
+          // record can't carry an in-file marker the way a document can (many records
+          // come from one file), so it names its source instead — a change to that file
+          // finds (equality lookup) and re-extracts exactly its records. Equality, not
+          // range: file-level is the sync unit (re-extraction reprocesses the whole file),
+          // and the schema keeps its single range lookup for the date row.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 13 }
         }
       ],
       lookupFields: [
@@ -10117,7 +10151,8 @@ var agenticSdlc = {
         "area",
         "verifiedBy",
         "relatedDecision",
-        { fieldName: "reviewedOn", rangeEnabled: true }
+        { fieldName: "reviewedOn", rangeEnabled: true },
+        "sourceRef"
       ]
     },
     {
@@ -10194,9 +10229,23 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 \u2014 when last revised. Range-queryable.",
           renderHints: { label: "Updated on", widget: "date", order: 9 }
+        },
+        {
+          // Provenance for sync — see the note on `control.sourceRef`.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 10 }
         }
       ],
-      lookupFields: ["area", "status", "establishedBy", { fieldName: "updatedOn", rangeEnabled: true }]
+      lookupFields: [
+        "area",
+        "status",
+        "establishedBy",
+        { fieldName: "updatedOn", rangeEnabled: true },
+        "sourceRef"
+      ]
     },
     {
       // A GOTCHA / sharp edge: a symptom, its cause, and the fix. A tight typed
@@ -10250,9 +10299,22 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 \u2014 when first hit. Range-queryable.",
           renderHints: { label: "Discovered on", widget: "date", order: 7 }
+        },
+        {
+          // Provenance for sync — see the note on `control.sourceRef`.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 8 }
         }
       ],
-      lookupFields: ["area", "status", { fieldName: "discoveredOn", rangeEnabled: true }]
+      lookupFields: [
+        "area",
+        "status",
+        { fieldName: "discoveredOn", rangeEnabled: true },
+        "sourceRef"
+      ]
     },
     {
       // A glossary TERM — a definition keyed by the term itself. Structure-dominant:
@@ -10312,6 +10374,14 @@ var agenticSdlc = {
           fieldType: "date",
           description: "ISO-8601 \u2014 when last revised. Range-queryable.",
           renderHints: { label: "Updated on", widget: "date", order: 7 }
+        },
+        {
+          // Provenance for sync — see the note on `control.sourceRef`.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          filterable: true,
+          description: "The source file (repo path) this record was extracted from \u2014 its provenance; a change to that file re-extracts its records. The specific section is encoded in the record externalId.",
+          renderHints: { label: "Source ref", widget: "text", order: 8 }
         }
       ],
       // `term` is a UNIQUE equality lookup — exact "define X" + a one-per-term
@@ -10320,27 +10390,32 @@ var agenticSdlc = {
         { fieldName: "term", unique: true },
         "area",
         "relatedDecision",
-        { fieldName: "updatedOn", rangeEnabled: true }
+        { fieldName: "updatedOn", rangeEnabled: true },
+        "sourceRef"
       ]
     }
   ],
-  // Least-privilege, data-plane only. r/c/u records + search + schema discovery +
-  // inference:r (grounded recall over the document bodies) + document/folder r/c
-  // (the content artifacts are documents). NO :d — knowledge is superseded/retired
-  // via a status flip, so the trail of how the team's thinking evolved stays intact.
+  // Least-privilege, data-plane only. The scope of the `ssk_*` key the bootstrap
+  // mints for THIS blueprint's service principal (the MCP/API runtime). See
+  // DATA_PLANE_ACTIONS above for the action set + rationale.
   accessProfile: {
-    allowedActions: [
-      "records:r",
-      "records:c",
-      "records:u",
-      "search:r",
-      "schemas:r",
-      "inference:r",
-      "documents:r",
-      "documents:c",
-      "folders:r",
-      "folders:c"
-    ]
+    allowedActions: DATA_PLANE_ACTIONS
+  },
+  // A reusable `editor` role for the HUMAN owner — DISTINCT from `accessProfile`
+  // (which scopes only the service-principal key). `bootstrap` provisions this
+  // role in the context but binds it to no one; the owner joins themselves so the
+  // data-plane app (app.vectros.ai) shows their KB — its switcher lists only
+  // contexts the signed-in user holds an active access profile in, and bootstrap
+  // grants the human none by default. Bind it after bootstrap with:
+  //   vectros access grant --principal usr_<your-user-id> --context agentic-sdlc --role editor
+  // (or the admin app's Access > Contexts > agentic-sdlc > Profiles > Create).
+  // The editor gets the full data plane so a human curator can browse, write/correct,
+  // AND hard-delete the KB (EDITOR_ACTIONS = the service key's set + delete). The
+  // service key deliberately lacks delete and archives instead; the trusted human
+  // owner may permanently remove genuine strays. Still no control-plane action, so
+  // the scope gate accepts it as a data-plane-only role.
+  roles: {
+    editor: [{ allowedActions: EDITOR_ACTIONS }]
   },
   servicePrincipal: {
     externalId: "agentic-sdlc",
@@ -12625,12 +12700,63 @@ function splitCsv(csv) {
   return csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 }
 
+// src/paginate.ts
+var PAGE_LIMIT = 100;
+async function drainPages(fetch2) {
+  const out = [];
+  let startFrom;
+  for (; ; ) {
+    const page = await fetch2(startFrom);
+    if (page.data) out.push(...page.data);
+    const next = page.nextCursor;
+    if (!next) break;
+    startFrom = next;
+  }
+  return out;
+}
+
+// src/self-principal.ts
+var PRINCIPAL_PREFIX_USER = "usr_";
+function emailFromJwt(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return void 0;
+  try {
+    const payload = Buffer.from(parts[1], "base64url").toString("utf8");
+    const claims = JSON.parse(payload);
+    return typeof claims.email === "string" && claims.email.trim() ? claims.email.trim() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function resolveSelfPrincipal(client, cognitoToken) {
+  const email = emailFromJwt(cognitoToken);
+  if (!email) return null;
+  const target = email.toLowerCase();
+  const users = await drainPages(
+    (startFrom) => client.identity.listUsers(
+      startFrom === void 0 ? { limit: PAGE_LIMIT } : { startFrom, limit: PAGE_LIMIT }
+    )
+  );
+  const match = users.find(
+    (u) => u.id && typeof u.email === "string" && u.email.toLowerCase() === target
+  );
+  if (!match?.id) return null;
+  return { principalId: `${PRINCIPAL_PREFIX_USER}${match.id}`, userId: match.id, email };
+}
+
 // src/commands/whoami.ts
 async function runWhoami(options, deps = {}) {
   return withAuth(options, deps, async (auth) => {
     const { identity, baseUrl } = auth;
+    let self2 = null;
+    try {
+      self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
+    } catch {
+      self2 = null;
+    }
     if (options.json) {
-      process.stdout.write(`${formatJson(identity)}
+      const out = self2 ? { ...identity, userId: self2.userId, userPrincipalId: self2.principalId } : identity;
+      process.stdout.write(`${formatJson(out)}
 `);
       return 0;
     }
@@ -12642,6 +12768,7 @@ async function runWhoami(options, deps = {}) {
         ["principal", identity.principalType],
         ["principal id", identity.principalKeyId],
         ["label", identity.principalLabel],
+        ["your user id", self2?.principalId],
         ["allowed actions", identity.allowedActions?.length ? identity.allowedActions.join(", ") : void 0],
         ["token expires", expiry],
         ["api", baseUrl]
@@ -12651,21 +12778,6 @@ async function runWhoami(options, deps = {}) {
   });
 }
 
-// src/paginate.ts
-var PAGE_LIMIT = 100;
-async function drainPages(fetch2) {
-  const out = [];
-  let startFrom;
-  for (; ; ) {
-    const page = await fetch2(startFrom);
-    if (page.data) out.push(...page.data);
-    const next = page.nextCursor;
-    if (!next) break;
-    startFrom = next;
-  }
-  return out;
-}
-
 // src/commands/key.ts
 var DEFAULT_KEY_NAME = "default";
 function emitMintedKey(key, format) {
@@ -13055,6 +13167,17 @@ function assertPrincipalShape(principal) {
     throw new Error(`--principal must be 'usr_<userId>' or 'key_<keyId>' (got '${principal}').`);
   }
 }
+var SELF_PRINCIPAL_ALIAS = "me";
+async function resolvePrincipalArg(raw, auth) {
+  if (raw !== SELF_PRINCIPAL_ALIAS) return raw;
+  const self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
+  if (!self2) {
+    throw new Error(
+      "Could not resolve your own user id from your login. Pass --principal usr_<id> explicitly (find the id with `vectros identity list --type user`)."
+    );
+  }
+  return self2.principalId;
+}
 function renderProfile(p) {
   return formatKeyValues([
     ["context", p.contextId],
@@ -13071,21 +13194,24 @@ async function runAccessGrant(opts, deps = {}) {
     process.stderr.write("  \u2716 Provide exactly one of --role <roleId> or --actions <csv>.\n");
     return 2;
   }
-  try {
-    assertPrincipalShape(opts.principal);
-  } catch (err) {
-    process.stderr.write(`  \u2716 ${formatError(err)}
+  if (opts.principal !== SELF_PRINCIPAL_ALIAS) {
+    try {
+      assertPrincipalShape(opts.principal);
+    } catch (err) {
+      process.stderr.write(`  \u2716 ${formatError(err)}
 `);
-    return 2;
+      return 2;
+    }
   }
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
+      const principal = await resolvePrincipalArg(opts.principal, auth);
       const scopes = hasActions ? [{ allowed_actions: splitCsv(opts.actions) }] : void 0;
       const profile = await client.auth.createAccessProfile({
         contextId: opts.context,
         body: {
-          principalId: opts.principal,
+          principalId: principal,
           roleId: opts.role,
           scopes
         }
@@ -13097,7 +13223,7 @@ async function runAccessGrant(opts, deps = {}) {
       }
       process.stdout.write(
         `
-  \u2714 Granted ${opts.principal} in '${opts.context}'` + (hasRole ? ` via role '${opts.role}'` : ` with ${splitCsv(opts.actions).length} action(s)`) + `
+  \u2714 Granted ${principal} in '${opts.context}'` + (hasRole ? ` via role '${opts.role}'` : ` with ${splitCsv(opts.actions).length} action(s)`) + `
 ${renderProfile(profile)}
 `
       );
@@ -13110,18 +13236,21 @@ ${renderProfile(profile)}
   });
 }
 async function runAccessRevoke(opts, deps = {}) {
-  try {
-    assertPrincipalShape(opts.principal);
-  } catch (err) {
-    process.stderr.write(`  \u2716 ${formatError(err)}
+  if (opts.principal !== SELF_PRINCIPAL_ALIAS) {
+    try {
+      assertPrincipalShape(opts.principal);
+    } catch (err) {
+      process.stderr.write(`  \u2716 ${formatError(err)}
 `);
-    return 2;
+      return 2;
+    }
   }
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
-      await client.auth.deleteAccessProfile({ contextId: opts.context, principalId: opts.principal });
-      process.stdout.write(`  \u2714 Revoked ${opts.principal} from '${opts.context}'
+      const principal = await resolvePrincipalArg(opts.principal, auth);
+      await client.auth.deleteAccessProfile({ contextId: opts.context, principalId: principal });
+      process.stdout.write(`  \u2714 Revoked ${principal} from '${opts.context}'
 `);
       return 0;
     } catch (err) {
@@ -13136,7 +13265,7 @@ async function runAccessList(opts, deps = {}) {
     process.stderr.write("  \u2716 Provide exactly one of --context <c> or --principal <p>.\n");
     return 2;
   }
-  if (opts.principal) {
+  if (opts.principal && opts.principal !== SELF_PRINCIPAL_ALIAS) {
     try {
       assertPrincipalShape(opts.principal);
     } catch (err) {
@@ -13148,10 +13277,11 @@ async function runAccessList(opts, deps = {}) {
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
+      const principal = opts.principal ? await resolvePrincipalArg(opts.principal, auth) : void 0;
       const rows = opts.context ? await drainPages(
         (startFrom) => client.auth.listAccessProfiles({ contextId: opts.context, startFrom, limit: PAGE_LIMIT })
       ) : await drainPages(
-        (startFrom) => client.auth.listProfilesForPrincipal({ principalId: opts.principal, startFrom, limit: PAGE_LIMIT })
+        (startFrom) => client.auth.listProfilesForPrincipal({ principalId: principal, startFrom, limit: PAGE_LIMIT })
       );
       if (opts.json) {
         process.stdout.write(`${formatJson(rows)}
@@ -13175,17 +13305,20 @@ async function runAccessList(opts, deps = {}) {
   });
 }
 async function runAccessGet(opts, deps = {}) {
-  try {
-    assertPrincipalShape(opts.principal);
-  } catch (err) {
-    process.stderr.write(`  \u2716 ${formatError(err)}
+  if (opts.principal !== SELF_PRINCIPAL_ALIAS) {
+    try {
+      assertPrincipalShape(opts.principal);
+    } catch (err) {
+      process.stderr.write(`  \u2716 ${formatError(err)}
 `);
-    return 2;
+      return 2;
+    }
   }
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
-      const p = await client.auth.getAccessProfile({ contextId: opts.context, principalId: opts.principal });
+      const principal = await resolvePrincipalArg(opts.principal, auth);
+      const p = await client.auth.getAccessProfile({ contextId: opts.context, principalId: principal });
       if (opts.json) {
         process.stdout.write(`${formatJson(p)}
 `);
@@ -13961,9 +14094,9 @@ async function runBlueprintTest(fileOrName, opts, deps = {}) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.6.4" : "dev",
-  sdk: true ? "0.31.0" : "dev",
-  blueprints: true ? "0.6.2" : "dev"
+  cli: true ? "0.6.6" : "dev",
+  sdk: true ? "0.32.0" : "dev",
+  blueprints: true ? "0.6.4" : "dev"
 };
 function formatBuildInfo() {
   return `vectros ${BUILD_INFO.cli} (sdk ${BUILD_INFO.sdk}, blueprints ${BUILD_INFO.blueprints})`;
@@ -14082,7 +14215,7 @@ function registerRoleCommands(program, deps) {
 }
 function registerAccessCommands(program, deps) {
   const access2 = program.command("access").description("Manage access bindings: principal \u2194 context \u2194 role/scopes.");
-  const grant = access2.command("grant").description("Bind a principal to a context via a role or inline actions.").requiredOption("--principal <p>", "principal: 'usr_<userId>' or 'key_<keyId>'").requiredOption("--context <c>", "app context").option("--role <roleId>", "reference a Role (XOR --actions)").option("--actions <csv>", "inline single-clause actions, comma-separated (XOR --role)");
+  const grant = access2.command("grant").description("Bind a principal to a context via a role or inline actions.").requiredOption("--principal <p>", "principal: 'usr_<userId>', 'key_<keyId>', or 'me' (your own user)").requiredOption("--context <c>", "app context").option("--role <roleId>", "reference a Role (XOR --actions)").option("--actions <csv>", "inline single-clause actions, comma-separated (XOR --role)");
   addCommonAuthOptions(grant).action(
     async (flags) => {
       process.exit(
@@ -14096,15 +14229,15 @@ function registerAccessCommands(program, deps) {
       );
     }
   );
-  const revoke = access2.command("revoke").description("Remove a principal\u2019s binding in a context.").requiredOption("--principal <p>", "principal: 'usr_<userId>' or 'key_<keyId>'").requiredOption("--context <c>", "app context");
+  const revoke = access2.command("revoke").description("Remove a principal\u2019s binding in a context.").requiredOption("--principal <p>", "principal: 'usr_<userId>', 'key_<keyId>', or 'me' (your own user)").requiredOption("--context <c>", "app context");
   addAuthOptions(revoke).action(async (flags) => {
     process.exit(await runAccessRevoke({ ...toCommonOptions(flags), principal: flags.principal, context: flags.context }, deps));
   });
-  const list = access2.command("list").description("List a context\u2019s members (--context) or a principal\u2019s contexts (--principal).").option("--context <c>", "list members of this context").option("--principal <p>", "list contexts this principal is bound to");
+  const list = access2.command("list").description("List a context\u2019s members (--context) or a principal\u2019s contexts (--principal).").option("--context <c>", "list members of this context").option("--principal <p>", "list contexts this principal is bound to ('me' = your own user)");
   addCommonAuthOptions(list).action(async (flags) => {
     process.exit(await runAccessList({ ...toCommonOptions(flags), context: flags.context, principal: flags.principal }, deps));
   });
-  const get = access2.command("get").description("Show one principal\u2019s binding in a context.").requiredOption("--principal <p>", "principal: 'usr_<userId>' or 'key_<keyId>'").requiredOption("--context <c>", "app context");
+  const get = access2.command("get").description("Show one principal\u2019s binding in a context.").requiredOption("--principal <p>", "principal: 'usr_<userId>', 'key_<keyId>', or 'me' (your own user)").requiredOption("--context <c>", "app context");
   addCommonAuthOptions(get).action(async (flags) => {
     process.exit(await runAccessGet({ ...toCommonOptions(flags), principal: flags.principal, context: flags.context }, deps));
   });