@indigoai-us/hq-cli 5.17.0 → 5.18.0

package/src/commands/files-browse.ts

@@ -0,0 +1,561 @@
+/**
+ * `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.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+import {
+  S3Client,
+  ListObjectsV2Command,
+  GetObjectCommand,
+  type ListObjectsV2CommandOutput,
+  type GetObjectCommandOutput,
+} from "@aws-sdk/client-s3";
+
+import {
+  VaultClient,
+  type VendResult,
+  type ExplicitGrant,
+} 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";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/**
+ * Subset of `VaultClient` this command actually uses — exposed so tests
+ * can stub vend + grants without standing up a real `VaultClient`.
+ */
+export interface FilesBrowseVaultClient {
+  vend(input: {
+    paths: string[];
+    operations: "read-only" | "read-write" | "staged-write";
+    purpose: "sync" | "browse";
+    duration?: number;
+  }): Promise<VendResult>;
+  listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
+  entity: {
+    get(uid: string): Promise<{ uid: string; slug: string; name?: string; bucketName?: string }>;
+    findInMyNamespace(
+      type: string,
+      slug: string,
+    ): Promise<{ uid: string; slug: string; name?: string; bucketName?: string } | null>;
+  };
+}
+
+/** Subset of `S3Client` this command actually uses — for test stubs. */
+export interface FilesBrowseS3Client {
+  send(
+    cmd: ListObjectsV2Command,
+  ): Promise<ListObjectsV2CommandOutput>;
+  send(cmd: GetObjectCommand): Promise<GetObjectCommandOutput>;
+}
+
+/** Factory for an S3 client given vended credentials. Injectable for tests. */
+export type S3ClientFactory = (input: {
+  region: string;
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+  };
+}) => FilesBrowseS3Client;
+
+/** ACL provenance for a single listed key. */
+export type AclSource = "shared-with-you" | "role-bypass";
+
+export interface BrowseRow {
+  key: string;
+  size: number;
+  lastModified: Date | undefined;
+  aclSource: AclSource;
+}
+
+// ── 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: string): string {
+  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: string,
+  grants: ExplicitGrant[],
+): AclSource {
+  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: string,
+  hqRoot: string,
+): string {
+  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: BrowseRow[]): string {
+  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: string[]): string =>
+    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");
+}
+
+// ── Orchestrators ───────────────────────────────────────────────────────────
+
+export interface RunBrowseInput {
+  /** Vault path prefix, e.g. `companies/indigo/scratch/`. */
+  pathPrefix: string;
+  /** Caller-overridden company slug (defaults to slug parsed from path). */
+  companySlug?: string;
+  vaultClient: FilesBrowseVaultClient;
+  s3Factory: S3ClientFactory;
+  region: string;
+}
+
+export interface RunBrowseResult {
+  rows: BrowseRow[];
+  vend: VendResult;
+}
+
+/**
+ * `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: RunBrowseInput): Promise<RunBrowseResult> {
+  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: BrowseRow[] = [];
+  let continuationToken: string | undefined;
+  do {
+    const resp = (await s3.send(
+      new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: pathPrefix,
+        ContinuationToken: continuationToken,
+      }),
+    )) as ListObjectsV2CommandOutput;
+
+    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 };
+}
+
+export interface RunCatInput {
+  /** Single vault key, e.g. `companies/indigo/scratch/foo.txt`. */
+  key: string;
+  /**
+   * Where to write the body. `undefined` ⇒ stdout. Bright-line-guarded
+   * against `<hqRoot>/companies/` by `assertOutPathOutsideCompanies`.
+   */
+  out?: string;
+  hqRoot: string;
+  companySlug?: string;
+  vaultClient: FilesBrowseVaultClient;
+  s3Factory: S3ClientFactory;
+  region: string;
+  /** Destination stream for the stdout path. Injectable for tests. */
+  stdout?: NodeJS.WritableStream;
+}
+
+export interface RunCatResult {
+  bytesWritten: number;
+  destination: { kind: "stdout" } | { kind: "file"; absPath: string };
+  vend: VendResult;
+}
+
+/**
+ * `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: RunCatInput): Promise<RunCatResult> {
+  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: string | undefined;
+  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 }),
+  )) as GetObjectCommandOutput;
+
+  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 as unknown as Readable;
+  let bytesWritten = 0;
+  body.on("data", (chunk: Buffer | string) => {
+    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: S3ClientFactory = ({ region, credentials }) =>
+  new S3Client({ region, credentials });
+
+interface FilesBrowseCliOptions {
+  company?: string;
+  hqRoot: string;
+}
+
+interface FilesCatCliOptions extends FilesBrowseCliOptions {
+  out?: string;
+}
+
+/**
+ * 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: Command): void {
+  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: string, options: FilesBrowseCliOptions) => {
+      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: string, options: FilesCatCliOptions) => {
+      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);
+      }
+    });
+}

package/src/commands/files.ts

@@ -118,7 +118,7 @@ export function formatShareSessionError(err: ShareSessionHttpError): string {
 // Command registration
 // ---------------------------------------------------------------------------
 
-export function registerFilesCommand(program: Command): void {
+export function registerFilesCommand(program: Command): Command {
   const files = program
     .command("files")
     .description("Manage file access controls in HQ vault")
@@ -407,6 +407,11 @@ export function registerFilesCommand(program: Command): void {
         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;
 }
 
 // ---------------------------------------------------------------------------