@indigoai-us/hq-cli 5.17.0 → 5.18.1

package/dist/commands/files-browse.js

@@ -0,0 +1,348 @@
+/**
+ * `hq files browse <path>` + `hq files cat <path> [--out <file>]` (US-008).
+ *
+ * Peek at a company's vault files **without** ever materialising them under
+ * `companies/{co}/` in the local HQ tree. Distinct from the sync path:
+ *
+ *   - `browse`  — `ListObjectsV2` under the given prefix, prints
+ *                 `{key, size, lastModified, aclSource}` rows. The
+ *                 `aclSource` hint distinguishes prefixes the caller can
+ *                 see via an EXPLICIT grant (`shared-with-you`) from
+ *                 prefixes they can see only because owner/admin
+ *                 role-bypass widened the vended policy (`role-bypass`).
+ *   - `cat`     — `GetObject`, stream the body to stdout. With `--out
+ *                 <file>` write the body to a path the user picked, but
+ *                 only after a bright-line guard refuses any destination
+ *                 inside `<hqRoot>/companies/` — that's the exact tree
+ *                 `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.
+ *
+ * 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.
+ */
+
+!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]="7a4467c5-bef0-5f15-99f9-9db157497caa")}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 { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+// ── Pure helpers ────────────────────────────────────────────────────────────
+/**
+ * Parse the company slug from a vault prefix. Vault paths are anchored at
+ * `companies/<slug>/...`; anything else is rejected so we never try to
+ * browse a non-company tree (e.g. `personal/`) with a company-vend.
+ */
+export function parseCompanySlugFromPath(prefix) {
+    const normalized = prefix.replace(/^\/+/, "");
+    const parts = normalized.split("/");
+    if (parts.length < 2 || parts[0] !== "companies" || !parts[1]) {
+        throw new Error(`Invalid browse path '${prefix}'. Expected a path starting with 'companies/<slug>/'.`);
+    }
+    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.
+ *
+ * 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.
+ */
+export function classifyAclSource(key, grants) {
+    for (const g of grants) {
+        if (g.path && key.startsWith(g.path))
+            return "shared-with-you";
+    }
+    return "role-bypass";
+}
+/**
+ * Bright-line guard for `--out`: refuse to write any byte beneath
+ * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
+ * slug-by-slug — `companies/` is the entire surface hq-sync owns, so a
+ * containment check on that parent suffices and avoids drift with the
+ * manifest file. Returns the resolved absolute output path on success;
+ * throws when the destination would land inside the protected tree.
+ */
+export function assertOutPathOutsideCompanies(outPath, hqRoot) {
+    const absOut = path.resolve(outPath);
+    const protectedRoot = path.resolve(hqRoot, "companies") + path.sep;
+    if (absOut === path.resolve(hqRoot, "companies") || absOut.startsWith(protectedRoot)) {
+        throw new Error(`Refusing to write '${absOut}': bytes peeked via 'hq files cat' must not land under ` +
+            `'${path.resolve(hqRoot, "companies")}'. Pick an --out path outside the HQ companies tree.`);
+    }
+    return absOut;
+}
+/**
+ * Render a browse listing as a padded table. Mirrors the chalk + padEnd
+ * pattern used by `hq sync mode --show` so the CLI surface stays
+ * stylistically consistent.
+ */
+export function formatBrowseTable(rows) {
+    if (rows.length === 0) {
+        return "No objects under that prefix.";
+    }
+    const cols = ["KEY", "SIZE", "MODIFIED", "ACL"];
+    const data = rows.map((r) => [
+        r.key,
+        String(r.size),
+        r.lastModified ? r.lastModified.toISOString() : "—",
+        r.aclSource,
+    ]);
+    const widths = cols.map((c, i) => Math.max(c.length, ...data.map((row) => row[i].length)));
+    const renderRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+    const lines = [
+        chalk.bold(renderRow(cols)),
+        chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
+        ...data.map(renderRow),
+    ];
+    return lines.join("\n");
+}
+/**
+ * `hq files browse <path>` orchestrator.
+ *
+ *   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.
+ *   5. Fetch explicit grants once, classify each key.
+ *
+ * Pure-ish: no console output, no process.exit — caller renders + exits.
+ */
+export async function runBrowse(input) {
+    const { pathPrefix, vaultClient, s3Factory, region } = input;
+    const 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.`);
+    }
+    if (!entity.bucketName) {
+        throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+    }
+    const companyUid = entity.uid;
+    const bucket = entity.bucketName;
+    // Distinct vend call from sync — `purpose: 'browse'` opts the request
+    // into the role-bypass-allowed code path on the server (US-009).
+    const vend = await vaultClient.vend({
+        paths: [pathPrefix],
+        operations: "read-only",
+        purpose: "browse",
+    });
+    const s3 = s3Factory({
+        region,
+        credentials: {
+            accessKeyId: vend.credentials.accessKeyId,
+            secretAccessKey: vend.credentials.secretAccessKey,
+            sessionToken: vend.credentials.sessionToken,
+        },
+    });
+    // Pull the caller's explicit-grant graph once so per-key classification
+    // is O(grants) without N round-trips.
+    const grants = await vaultClient.listMyExplicitGrants(companyUid);
+    const rows = [];
+    let continuationToken;
+    do {
+        const resp = (await s3.send(new ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: pathPrefix,
+            ContinuationToken: continuationToken,
+        })));
+        for (const obj of resp.Contents ?? []) {
+            if (!obj.Key)
+                continue;
+            // Skip S3 "directory marker" objects (0-byte, trailing slash).
+            if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
+                continue;
+            rows.push({
+                key: obj.Key,
+                size: obj.Size ?? 0,
+                lastModified: obj.LastModified,
+                aclSource: classifyAclSource(obj.Key, grants),
+            });
+        }
+        continuationToken = resp.NextContinuationToken ?? undefined;
+    } while (continuationToken);
+    return { rows, vend };
+}
+/**
+ * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then
+ * streams the object body either to stdout or to `--out` (after the
+ * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
+ */
+export async function runCat(input) {
+    const { key, vaultClient, s3Factory, region, hqRoot } = input;
+    const slug = input.companySlug ?? parseCompanySlugFromPath(key);
+    // Acceptance 5: refuse BEFORE vending — no point pulling credentials
+    // for a request we're already going to abort.
+    let absOut;
+    if (input.out !== undefined) {
+        absOut = assertOutPathOutsideCompanies(input.out, hqRoot);
+    }
+    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 vend = await vaultClient.vend({
+        paths: [key],
+        operations: "read-only",
+        purpose: "browse",
+    });
+    const s3 = s3Factory({
+        region,
+        credentials: {
+            accessKeyId: vend.credentials.accessKeyId,
+            secretAccessKey: vend.credentials.secretAccessKey,
+            sessionToken: vend.credentials.sessionToken,
+        },
+    });
+    const resp = (await s3.send(new GetObjectCommand({ Bucket: entity.bucketName, Key: key })));
+    if (!resp.Body) {
+        throw new Error(`GetObject for '${key}' returned no body.`);
+    }
+    // The SDK Body type in node is a Readable (it can also be a
+    // ReadableStream/Blob in other runtimes but those don't apply to the
+    // CLI). Cast through unknown so the type checker accepts the narrowing.
+    const body = resp.Body;
+    let bytesWritten = 0;
+    body.on("data", (chunk) => {
+        bytesWritten += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
+    });
+    if (absOut !== undefined) {
+        // Ensure the parent directory exists — but ONLY if it's also outside
+        // the protected tree (the guard already validated absOut itself; the
+        // parent of an outside-tree path is by definition outside too).
+        fs.mkdirSync(path.dirname(absOut), { recursive: true });
+        await pipeline(body, fs.createWriteStream(absOut));
+        return {
+            bytesWritten,
+            destination: { kind: "file", absPath: absOut },
+            vend,
+        };
+    }
+    await pipeline(body, input.stdout ?? process.stdout);
+    return { bytesWritten, destination: { kind: "stdout" }, vend };
+}
+// ── CLI registration ────────────────────────────────────────────────────────
+const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, credentials });
+/**
+ * Wire `hq files browse` + `hq files cat` onto an existing `files`
+ * Commander group. `registerFilesCommand` in files.ts builds the group
+ * and registers `share`/`unshare`/`acl`; this function appends the two
+ * new browse-vs-sync subcommands so they share the `--company` switch.
+ */
+export function registerFilesBrowseCommands(filesCmd) {
+    filesCmd
+        .command("browse <path>")
+        .description("List vault objects under <path> without syncing them locally. Uses the browse-vend path (role-bypass allowed).")
+        .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 vaultConfig = buildVaultConfig(accessToken);
+            const client = new VaultClient(vaultConfig);
+            // Resolve slug — CLI flag wins, otherwise parse from path arg.
+            const slug = options.company ?? parseCompanySlugFromPath(pathArg);
+            // If the user passed `--company` AND the path doesn't begin with
+            // companies/<that-slug>/, refuse — we'd otherwise vend creds for
+            // one company and list keys from another tree, which never makes
+            // sense (defense in depth against operator typos).
+            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}'.`);
+                }
+            }
+            // Confirm the slug resolves to a known membership — same pattern
+            // sync-mode/sync-narrow use to surface "you're not a member" early.
+            await getCompanyUid(accessToken, slug);
+            const result = await runBrowse({
+                pathPrefix: pathArg,
+                companySlug: slug,
+                vaultClient: client,
+                s3Factory: defaultS3Factory,
+                region: DEFAULT_COGNITO.region,
+            });
+            console.log(formatBrowseTable(result.rows));
+            if (result.rows.length > 0) {
+                const bypassCount = result.rows.filter((r) => r.aclSource === "role-bypass").length;
+                if (bypassCount > 0) {
+                    console.log("");
+                    console.log(chalk.yellow(`Heads-up: ${bypassCount} object(s) visible only via role-bypass (no explicit grant covers them).`));
+                }
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    filesCmd
+        .command("cat <path>")
+        .description("Stream a single vault object to stdout (or --out <file>) without syncing it. Uses the browse-vend path.")
+        .option("--out <file>", "Write the object body to <file> instead of stdout. Refused under <hqRoot>/companies/.")
+        .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 (keyArg, options) => {
+        try {
+            const accessToken = await ensureCognitoToken();
+            const vaultConfig = buildVaultConfig(accessToken);
+            const client = new VaultClient(vaultConfig);
+            const slug = options.company ?? parseCompanySlugFromPath(keyArg);
+            if (options.company !== undefined) {
+                const fromPath = (() => {
+                    try {
+                        return parseCompanySlugFromPath(keyArg);
+                    }
+                    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 runCat({
+                key: keyArg,
+                out: options.out,
+                hqRoot: options.hqRoot,
+                companySlug: slug,
+                vaultClient: client,
+                s3Factory: defaultS3Factory,
+                region: DEFAULT_COGNITO.region,
+            });
+            if (result.destination.kind === "file") {
+                console.error(chalk.green("✓"), `Wrote ${result.bytesWritten} bytes to ${result.destination.absPath}`);
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=files-browse.js.map
+//# debugId=7a4467c5-bef0-5f15-99f9-9db157497caa

package/dist/commands/files.d.ts

@@ -40,5 +40,5 @@ export declare class ShareSessionHttpError extends Error {
  * stay in sync.
  */
 export declare function formatShareSessionError(err: ShareSessionHttpError): string;
-export declare function registerFilesCommand(program: Command): void;
+export declare function registerFilesCommand(program: Command): Command;
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -1,5 +1,5 @@
 
-!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]="7a4bfaa9-c578-5cd8-8955-ec965faada13")}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]="c72d8e20-42a6-5818-b5d3-985e53954430")}catch(e){}}();
 import chalk from "chalk";
 import open from "open";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -315,6 +315,10 @@ export function registerFilesCommand(program) {
             process.exit(1);
         }
     });
+    // Return the `files` Commander group so callers (src/index.ts) can attach
+    // additional subcommands (e.g. `hq files browse`/`hq files cat` from
+    // files-browse.ts) onto the same group without re-creating it.
+    return files;
 }
 async function runDirectGrant(params) {
     const canonicalPrefix = normalizeFilePrefix(params.prefix);
@@ -456,4 +460,4 @@ async function runShareSession(params) {
     }
 }
 //# sourceMappingURL=files.js.map
-//# debugId=7a4bfaa9-c578-5cd8-8955-ec965faada13
+//# debugId=c72d8e20-42a6-5818-b5d3-985e53954430

package/dist/commands/sync-mode.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `hq sync mode <mode>` (US-006) — flip a membership's syncMode for a company.
+ *
+ * Subcommand of the `hq sync` group. Three call shapes:
+ *
+ *   hq sync mode shared|all|custom [--company <slug>]
+ *       Resolves the target membership for the given company (or the cwd's
+ *       active company from `.hq/config.json` if `--company` is omitted) and
+ *       calls `VaultClient.setMembershipSyncConfig`. Prints membershipId +
+ *       previous mode → new mode as a chat audit trail.
+ *
+ *   hq sync mode --show
+ *       No positional. Prints a table of every membership the caller has
+ *       with its company slug, current sync-mode, and last-updated stamp.
+ *
+ *   hq sync mode custom --paths a/,b/  (planned follow-up)
+ *       For the `custom` mode the server requires `customPaths`. This command
+ *       accepts `--paths` as a comma-separated list to forward to the API; if
+ *       omitted on `custom` the server validation will reject.
+ *
+ * Auto-detect of `--company` from cwd: best-effort via the active-company
+ * slug in `<hq-root>/.hq/config.json`. If absent, the caller must pass
+ * `--company` explicitly — there's no cwd-walk to a `companies/<slug>/`
+ * folder in this initial implementation (follow-up US could add it).
+ *
+ * Cross-package note: this command depends on `VaultClient`
+ * (`getMembershipSyncConfig` / `setMembershipSyncConfig`) added in
+ * hq-cloud US-004 (commit 41e5ee1). While that hq-cloud release is
+ * unpublished, hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud`
+ * in package.json — revert that line to `^5.20.0` (or whatever the
+ * published cut is) once US-004 ships to npm.
+ */
+import { Command } from "commander";
+import { type MembershipSyncConfig, type Membership, type SyncMode } from "@indigoai-us/hq-cloud";
+export declare const LEGAL_SYNC_MODES: readonly SyncMode[];
+/** Subset of VaultClient surface this command exercises (test seam). */
+export interface SyncModeVaultClient {
+    listMyMemberships(): Promise<Membership[]>;
+    getMembershipSyncConfig(membershipId: string): Promise<MembershipSyncConfig>;
+    setMembershipSyncConfig(membershipId: string, partial: {
+        syncMode: SyncMode;
+        customPaths?: string[];
+    }): Promise<MembershipSyncConfig>;
+    entity: {
+        get(uid: string): Promise<{
+            uid: string;
+            slug: string;
+            name?: string;
+        }>;
+    };
+}
+export interface SetSyncModeOptions {
+    /** Validated mode — already known to be a legal SyncMode. */
+    mode: SyncMode;
+    /** Company slug (caller-provided or resolved from cwd). Required. */
+    companySlug: string;
+    /** Required when `mode === "custom"`. Server rejects otherwise. */
+    customPaths?: string[];
+    /** Injected vault client (real impl built from access token by default). */
+    vaultClient: SyncModeVaultClient;
+}
+export interface SetSyncModeResult {
+    membershipId: string;
+    companySlug: string;
+    previousMode: SyncMode;
+    newMode: SyncMode;
+    previousWasDefault: boolean;
+    newConfig: MembershipSyncConfig;
+}
+export interface ShowSyncModesOptions {
+    vaultClient: SyncModeVaultClient;
+}
+export interface ShowSyncModesRow {
+    companySlug: string;
+    companyName?: string;
+    membershipId: string;
+    syncMode: SyncMode;
+    isDefault: boolean;
+    updatedAt?: string;
+}
+/** Throws a helpful Error if `mode` is not a legal SyncMode. */
+export declare function validateMode(mode: string): SyncMode;
+/**
+ * Read the active company slug from `<hq-root>/.hq/config.json`. Returns
+ * undefined when the file is missing or `activeCompany` isn't set. Never
+ * throws — auto-detect is best-effort.
+ */
+export declare function readActiveCompanySlug(hqRoot: string): string | undefined;
+/** Parse `--paths a/,b/c/` into trimmed non-empty entries. */
+export declare function parseCustomPaths(raw: string | undefined): string[] | undefined;
+/**
+ * Resolve a membership by company slug, then PUT the new sync-mode. Returns
+ * the membershipId, the previous mode (read via GET first), and the server's
+ * fresh config (which sets `isDefault: false` once a row exists).
+ */
+export declare function setSyncMode(options: SetSyncModeOptions): Promise<SetSyncModeResult>;
+/**
+ * Fetch every membership the caller has, resolve company slugs, and look up
+ * each effective sync-config in parallel. Returns rows sorted by slug for
+ * stable table output.
+ */
+export declare function showSyncModes(options: ShowSyncModesOptions): Promise<ShowSyncModesRow[]>;
+/**
+ * Render the `--show` table as plain text. No external dep — hq-cli doesn't
+ * use cli-table3, so we hand-format columns to match the existing chalk +
+ * padEnd pattern used by `hq members list`.
+ */
+export declare function formatShowTable(rows: ShowSyncModesRow[]): string;
+/**
+ * Wire `hq sync mode` onto an existing `sync` Commander group. The caller
+ * (`src/index.ts`) constructs the `sync` group and calls this after
+ * `registerCloudCommands` so push/pull/status/mode all coexist.
+ */
+export declare function registerSyncModeCommand(syncCmd: Command): void;
+//# sourceMappingURL=sync-mode.d.ts.map