@indigoai-us/hq-cli 5.28.0 → 5.30.0

package/dist/commands/files-browse.js

@@ -17,25 +17,30 @@
  *                 `hq sync` owns, and writing a peeked object there would
  *                 silently re-import it into the sync envelope.
  *
- * Both subcommands vend via the new `purpose: 'browse'` path
- * (`VaultClient.vend`) shipped in hq-cloud US-009. The server treats that
- * purpose as the role-bypass-allowed surface — sync vends NEVER widen, so
- * keeping browse on its own vend call is the acceptance-criteria-1
- * separation we need.
+ * Both subcommands vend through the multi-tenant STS routes —
+ * `VaultClient.sts.vend` (`/sts/vend`, company) and `.sts.vendSelf`
+ * (`/sts/vend-self`, personal). These resolve the caller's per-entity bucket
+ * and apply role/ACL scoping server-side (owner/admin → full access; member/
+ * guest → per-prefix). The legacy `POST /vend` is deliberately NOT used: it
+ * assumes a single static `BUCKET_ARN` that is unset in multi-tenant prod, so
+ * it builds an invalid policy and STS rejects it (`MalformedPolicyDocument`).
  *
- * Cross-package note: depends on `VendInput`/`VendResult` + the
- * `VaultClient.vend` method from hq-cloud US-009 (commit 2f790c5).
- * hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud` via
- * `pnpm.overrides` until that release ships to npm.
+ * Namespace note: company vault keys are company-relative (no
+ * `companies/<slug>/` prefix). The CLI speaks the anchored form for user
+ * familiarity and translates at the S3 boundary via `toBucketRelative` /
+ * `toCompanyAnchored`.
+ *
+ * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
+ * methods and `grantPathToPrefix` from hq-cloud.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="102456e4-666a-5484-b432-7f0b73275818")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="73529786-7369-5356-a6a8-4d55bd553147")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
-import { VaultClient, } from "@indigoai-us/hq-cloud";
+import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
@@ -54,17 +59,43 @@ export function parseCompanySlugFromPath(prefix) {
     return parts[1];
 }
 /**
- * Classify a single S3 key against the caller's explicit-grant list. Any
- * grant whose `path` is a prefix of the key contributes `shared-with-you`;
- * otherwise the key is only visible via role-bypass on the vend call.
+ * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
+ * the vault bucket actually stores. Company vault buckets are already
+ * company-scoped, so their keys carry NO `companies/<slug>/` prefix (e.g.
+ * `knowledge/foo.md`, not `companies/indigo/knowledge/foo.md`). The CLI speaks
+ * the anchored form for user familiarity; we strip the anchor at the S3
+ * boundary. A path without the anchor (or personal-mode, bucket-relative
+ * paths) passes through unchanged.
+ */
+export function toBucketRelative(pathOrPrefix, slug) {
+    const anchor = `companies/${slug}/`;
+    const normalized = pathOrPrefix.replace(/^\/+/, "");
+    return normalized.startsWith(anchor)
+        ? normalized.slice(anchor.length)
+        : normalized;
+}
+/**
+ * Re-attach the `companies/<slug>/` anchor to a company-relative bucket key
+ * for display + `hq files cat` round-trip, so the CLI surface keeps speaking
+ * the anchored form the user passed in.
+ */
+export function toCompanyAnchored(bucketRelKey, slug) {
+    return `companies/${slug}/${bucketRelKey}`;
+}
+/**
+ * Classify a single company-relative S3 key against the caller's
+ * (already-normalized) explicit-grant prefixes. Any prefix that covers the
+ * key contributes `shared-with-you`; otherwise the key is visible only via
+ * the owner/admin role-bypass the `/sts/vend` policy applied. An empty-string
+ * prefix is a company-wide grant and matches everything.
  *
- * Grant paths and S3 keys live in the same canonical form ("companies/<slug>/…");
- * `coalescePrefixes` would shrink the list further but isn't required for
- * correctness — `startsWith` already short-circuits on the first match.
+ * Grant `path`s arrive in inconsistent/glob form; the caller normalizes them
+ * to company-relative `startsWith` prefixes via `grantPathToPrefix` before
+ * calling this — keeping this helper pure and trivially testable.
  */
-export function classifyAclSource(key, grants) {
-    for (const g of grants) {
-        if (g.path && key.startsWith(g.path))
+export function classifyAclSource(bucketRelKey, grantPrefixes) {
+    for (const p of grantPrefixes) {
+        if (p === "" || bucketRelKey.startsWith(p))
             return "shared-with-you";
     }
     return "role-bypass";
@@ -116,8 +147,10 @@ export function formatBrowseTable(rows) {
  *
  *   1. Parse slug from prefix (or use override).
  *   2. Resolve companyUid + bucketName via VaultClient.entity.
- *   3. Vend with `purpose: 'browse'`, `operations: 'read-only'`, paths: [prefix].
- *   4. Construct S3Client from vended creds, paginate ListObjectsV2.
+ *   3. Vend read creds via the multi-tenant STS route (`/sts/vend` company,
+ *      `/sts/vend-self` personal) — resolves the per-entity bucket + role/ACL.
+ *   4. Construct S3Client from vended creds, paginate ListObjectsV2 over the
+ *      company-relative key space.
  *   5. Fetch explicit grants once, classify each key.
  *
  * Pure-ish: no console output, no process.exit — caller renders + exits.
@@ -127,10 +160,11 @@ export async function runBrowse(input) {
     // Branch by mode. Company mode parses slug from path and looks up by
     // namespace; personal mode resolves the entity directly by the supplied
     // person UID and skips the slug + grants machinery (a person bucket has
-    // no grants graph — the owner is the only principal). The vend call is
-    // identical for both modes once we have the entity in hand.
+    // no grants graph — the owner is the only principal).
     let bucket;
     let entityUid;
+    let slug;
+    let vend;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runBrowse: personalMode requires personalUid. Resolve via " +
@@ -142,9 +176,10 @@ export async function runBrowse(input) {
         }
         entityUid = entity.uid;
         bucket = entity.bucketName;
+        vend = await vaultClient.sts.vendSelf({ personUid: entityUid });
     }
     else {
-        const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
+        slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
         const entity = await vaultClient.entity.findInMyNamespace("company", slug);
         if (!entity) {
             throw new Error(`No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`);
@@ -154,17 +189,11 @@ export async function runBrowse(input) {
         }
         entityUid = entity.uid;
         bucket = entity.bucketName;
+        // Multi-tenant vend: the server resolves this company's bucket + applies
+        // owner/admin role-bypass (full access) or member/guest ACL scoping. The
+        // legacy `POST /vend` is unused here — see FilesBrowseVaultClient docs.
+        vend = await vaultClient.sts.vend({ companyUid: entityUid });
     }
-    // Distinct vend call from sync — `purpose: 'browse'` opts the request
-    // into the role-bypass-allowed code path on the server (US-009). The
-    // personal mode vends against the person entity which is owner-only by
-    // construction; the vend response shape is identical so downstream
-    // S3Client construction doesn't branch.
-    const vend = await vaultClient.vend({
-        paths: [pathPrefix],
-        operations: "read-only",
-        purpose: "browse",
-    });
     const s3 = s3Factory({
         region,
         credentials: {
@@ -173,19 +202,26 @@ export async function runBrowse(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
+    // Company vault keys are company-relative (no `companies/<slug>/` prefix), so
+    // translate the CLI's anchored prefix into the bucket-relative form before
+    // listing. Personal-mode paths are already bucket-relative.
+    const listPrefix = personalMode || slug === undefined
+        ? pathPrefix
+        : toBucketRelative(pathPrefix, slug);
     // Pull the caller's explicit-grant graph once so per-key classification
-    // is O(grants) without N round-trips. Skipped in personal mode — the
-    // grants graph is a company concept; a person bucket marks every row
-    // as `"personal-vault"` directly.
-    const grants = personalMode
+    // is O(grants) without N round-trips. Grant `path`s are normalized to
+    // company-relative `startsWith` prefixes (matching the bucket key space)
+    // via `grantPathToPrefix`. Skipped in personal mode — the grants graph is a
+    // company concept; a person bucket marks every row `"personal-vault"`.
+    const grantPrefixes = personalMode || slug === undefined
         ? []
-        : await vaultClient.listMyExplicitGrants(entityUid);
+        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => grantPathToPrefix(g.path, slug));
     const rows = [];
     let continuationToken;
     do {
         const resp = (await s3.send(new ListObjectsV2Command({
             Bucket: bucket,
-            Prefix: pathPrefix,
+            Prefix: listPrefix,
             ContinuationToken: continuationToken,
         })));
         for (const obj of resp.Contents ?? []) {
@@ -194,11 +230,17 @@ export async function runBrowse(input) {
             // Skip S3 "directory marker" objects (0-byte, trailing slash).
             if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
                 continue;
+            // `obj.Key` is company-relative. Classify in that space, then re-anchor
+            // for display so the CLI keeps speaking `companies/<slug>/...`.
             rows.push({
-                key: obj.Key,
+                key: personalMode || slug === undefined
+                    ? obj.Key
+                    : toCompanyAnchored(obj.Key, slug),
                 size: obj.Size ?? 0,
                 lastModified: obj.LastModified,
-                aclSource: personalMode ? "personal-vault" : classifyAclSource(obj.Key, grants),
+                aclSource: personalMode
+                    ? "personal-vault"
+                    : classifyAclSource(obj.Key, grantPrefixes),
             });
         }
         continuationToken = resp.NextContinuationToken ?? undefined;
@@ -221,6 +263,8 @@ export async function runCat(input) {
     // Same branch logic as runBrowse — see that function's doc-block for
     // the personal-vs-company rationale.
     let bucket;
+    let s3Key;
+    let vend;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runCat: personalMode requires personalUid. Resolve via " +
@@ -231,6 +275,8 @@ export async function runCat(input) {
             throw new Error(`Personal entity '${input.personalUid}' has no provisioned bucket.`);
         }
         bucket = entity.bucketName;
+        s3Key = key; // personal-mode keys are already bucket-relative
+        vend = await vaultClient.sts.vendSelf({ personUid: entity.uid });
     }
     else {
         const slug = input.companySlug ?? parseCompanySlugFromPath(key);
@@ -242,12 +288,10 @@ export async function runCat(input) {
             throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
         }
         bucket = entity.bucketName;
+        // Translate the anchored CLI key into the company-relative bucket key.
+        s3Key = toBucketRelative(key, slug);
+        vend = await vaultClient.sts.vend({ companyUid: entity.uid });
     }
-    const vend = await vaultClient.vend({
-        paths: [key],
-        operations: "read-only",
-        purpose: "browse",
-    });
     const s3 = s3Factory({
         region,
         credentials: {
@@ -256,7 +300,7 @@ export async function runCat(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
-    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: s3Key })));
     if (!resp.Body) {
         throw new Error(`GetObject for '${key}' returned no body.`);
     }
@@ -356,6 +400,148 @@ export function formatSharedWithMeTable(rows) {
         ...data.map(renderRow),
     ].join("\n");
 }
+/**
+ * `hq files search <query>` orchestrator. Lists the company (or personal)
+ * vault under its root via `runBrowse`, then filters to keys containing the
+ * query (case-insensitive). v1 is a name/path search over the listing — no
+ * content search. Rows carry the same ACL-source classification as browse.
+ *
+ * Pure-ish: no console output. The caller renders with `formatBrowseTable`.
+ */
+export async function runSearch(input) {
+    const prefix = input.personalMode ? "" : `companies/${input.companySlug}/`;
+    const { rows } = await runBrowse({
+        pathPrefix: prefix,
+        companySlug: input.companySlug,
+        personalMode: input.personalMode,
+        personalUid: input.personalUid,
+        vaultClient: input.vaultClient,
+        s3Factory: input.s3Factory,
+        region: input.region,
+    });
+    const q = input.query.toLowerCase();
+    return rows.filter((r) => r.key.toLowerCase().includes(q));
+}
+/** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
+export function pinFilePath(hqRoot) {
+    return path.join(hqRoot, ".hq", "pins.json");
+}
+/** Read the pin set, tolerating a missing or corrupt file (→ fresh). */
+export function readPins(hqRoot) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(pinFilePath(hqRoot), "utf-8"));
+        if (parsed && typeof parsed === "object" && parsed.pins) {
+            return { version: parsed.version ?? 1, pins: parsed.pins };
+        }
+    }
+    catch {
+        /* missing / unreadable / malformed → start fresh */
+    }
+    return { version: 1, pins: {} };
+}
+/**
+ * Register a company-relative prefix in the per-machine pin set. Pins are what
+ * keep an on-demand `hq files get` from being pruned by the next *scoped*
+ * sync (`syncMode: shared|custom`): the sync runner unions the company's pins
+ * into its pull scope. Idempotent + sorted for stable diffs.
+ */
+export function addPin(hqRoot, companySlug, prefix) {
+    const pf = readPins(hqRoot);
+    const list = pf.pins[companySlug] ?? [];
+    if (!list.includes(prefix))
+        list.push(prefix);
+    list.sort();
+    pf.pins[companySlug] = list;
+    const f = pinFilePath(hqRoot);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(pf, null, 2) + "\n");
+}
+/**
+ * `hq files get <path>` orchestrator. Materializes a vault file or prefix into
+ * the local HQ tree on demand. Unlike `cat` (which refuses to write under
+ * `companies/`), `get` deliberately writes INTO `companies/<slug>/...` by
+ * default — that's the point: pull a path you have access to but don't sync.
+ * It then registers a pin so the next scoped sync keeps it.
+ *
+ * Company mode only in v1 — materializing a personal vault would target the
+ * HQ root itself, which is too broad to do implicitly.
+ */
+export async function runGet(input) {
+    const { path: vaultPath, vaultClient, s3Factory, region, hqRoot } = input;
+    const slug = input.companySlug ?? parseCompanySlugFromPath(vaultPath);
+    const entity = await vaultClient.entity.findInMyNamespace("company", slug);
+    if (!entity) {
+        throw new Error(`No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`);
+    }
+    if (!entity.bucketName) {
+        throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+    }
+    const bucket = entity.bucketName;
+    const vend = await vaultClient.sts.vend({ companyUid: entity.uid });
+    const s3 = s3Factory({
+        region,
+        credentials: {
+            accessKeyId: vend.credentials.accessKeyId,
+            secretAccessKey: vend.credentials.secretAccessKey,
+            sessionToken: vend.credentials.sessionToken,
+        },
+    });
+    // Company-relative prefix to list/fetch (bucket keys carry no anchor).
+    const bucketPrefix = toBucketRelative(vaultPath, slug);
+    const keys = [];
+    let continuationToken;
+    do {
+        const resp = (await s3.send(new ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: bucketPrefix,
+            ContinuationToken: continuationToken,
+        })));
+        for (const obj of resp.Contents ?? []) {
+            if (!obj.Key)
+                continue;
+            if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
+                continue;
+            keys.push(obj.Key);
+        }
+        continuationToken = resp.NextContinuationToken ?? undefined;
+    } while (continuationToken);
+    if (keys.length === 0) {
+        throw new Error(`No objects under '${vaultPath}'.`);
+    }
+    const destinations = [];
+    let bytesWritten = 0;
+    for (const key of keys) {
+        // Default: in-place under companies/<slug>/<company-relative key>.
+        // --into: write the path relative to the requested prefix under <into>.
+        let destAbs;
+        if (input.into !== undefined) {
+            const rel = key.startsWith(bucketPrefix)
+                ? key.slice(bucketPrefix.length)
+                : key;
+            destAbs = path.resolve(input.into, rel || path.basename(key));
+        }
+        else {
+            destAbs = path.join(hqRoot, "companies", slug, key);
+        }
+        const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+        if (!resp.Body) {
+            throw new Error(`GetObject for '${key}' returned no body.`);
+        }
+        const body = resp.Body;
+        fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+        await pipeline(body, fs.createWriteStream(destAbs));
+        bytesWritten += fs.statSync(destAbs).size;
+        destinations.push(destAbs);
+    }
+    // Pin only the in-place case — `--into` writes outside the sync envelope, so
+    // there's nothing for a scoped sync to prune.
+    let pinned;
+    if (input.into === undefined) {
+        addPin(hqRoot, slug, bucketPrefix);
+        pinned = { companySlug: slug, prefix: bucketPrefix };
+    }
+    return { filesWritten: keys.length, bytesWritten, destinations, pinned };
+}
 // ── CLI registration ────────────────────────────────────────────────────────
 const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, credentials });
 /**
@@ -547,6 +733,98 @@ export function registerFilesBrowseCommands(filesCmd) {
             process.exit(1);
         }
     });
+    filesCmd
+        .command("search <query>")
+        .description("Search vault object keys (case-insensitive path/name match) under a company without downloading. Requires --company (or --personal). Content search is not supported in v1.")
+        .option("--company <slug>", "Company slug to search.")
+        .option("--personal", "Search the caller's canonical personal vault. Mutually exclusive with --company.")
+        .action(async (query, options) => {
+        try {
+            if (options.personal && options.company) {
+                throw new Error("--personal and --company are mutually exclusive. Pick one.");
+            }
+            const accessToken = await ensureCognitoToken();
+            const client = new VaultClient(buildVaultConfig(accessToken));
+            if (options.personal) {
+                const personalUid = await resolveCanonicalPersonUid({
+                    listMyMemberships: () => client.listMyMemberships(),
+                    listPersonEntities: () => client.entity.listByType("person"),
+                    getEntity: async () => null,
+                });
+                const rows = await runSearch({
+                    query,
+                    companySlug: "personal",
+                    personalMode: true,
+                    personalUid,
+                    vaultClient: client,
+                    s3Factory: defaultS3Factory,
+                    region: DEFAULT_COGNITO.region,
+                });
+                console.log(formatBrowseTable(rows));
+                return;
+            }
+            if (!options.company) {
+                throw new Error("search: --company <slug> is required (or --personal to search your personal vault).");
+            }
+            await getCompanyUid(accessToken, options.company);
+            const rows = await runSearch({
+                query,
+                companySlug: options.company,
+                vaultClient: client,
+                s3Factory: defaultS3Factory,
+                region: DEFAULT_COGNITO.region,
+            });
+            console.log(formatBrowseTable(rows));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    filesCmd
+        .command("get <path>")
+        .description("Download (materialize) a vault file or prefix into local HQ on demand. Default writes in place under <hqRoot>/companies/<slug>/<path> and registers a pin so a scoped sync (mode shared|custom) won't prune it. Use --into to write elsewhere (no pin). Company mode only.")
+        .option("--into <dir>", "Write into this directory instead of the in-place companies/<slug>/ location. No pin is registered.")
+        .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>).")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(async (pathArg, options) => {
+        try {
+            const accessToken = await ensureCognitoToken();
+            const client = new VaultClient(buildVaultConfig(accessToken));
+            const slug = options.company ?? parseCompanySlugFromPath(pathArg);
+            if (options.company !== undefined) {
+                const fromPath = (() => {
+                    try {
+                        return parseCompanySlugFromPath(pathArg);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })();
+                if (fromPath && fromPath !== options.company) {
+                    throw new Error(`--company '${options.company}' disagrees with path slug '${fromPath}'.`);
+                }
+            }
+            await getCompanyUid(accessToken, slug);
+            const result = await runGet({
+                path: pathArg,
+                into: options.into,
+                hqRoot: options.hqRoot,
+                companySlug: slug,
+                vaultClient: client,
+                s3Factory: defaultS3Factory,
+                region: DEFAULT_COGNITO.region,
+            });
+            console.error(chalk.green("✓"), `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`);
+            if (result.pinned) {
+                console.error(chalk.dim(`Pinned ${result.pinned.companySlug}:${result.pinned.prefix} — survives scoped sync.`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=102456e4-666a-5484-b432-7f0b73275818
+//# debugId=73529786-7369-5356-a6a8-4d55bd553147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.28.0",
+  "version": "5.30.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "~5.42.0",
+    "@indigoai-us/hq-cloud": "~5.44.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",