@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/files-browse.js

@@ -31,7 +31,7 @@
  * `toCompanyAnchored`.
  *
  * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
- * methods and `grantPathToPrefix` from hq-cloud.
+ * methods from hq-cloud.
  */
 import { isAccessDeniedError, accessDeniedKeyOf, reportAccessDenied, accessDeniedCompanyOf, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
@@ -40,10 +40,14 @@ import * as path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
-import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
+import { VaultClient, } from "@indigoai-us/hq-cloud";
+import { isPrivateFolderPattern } from "./_patterns.js";
+import { displayAclSource, } from "../utils/files-browse-acl.js";
+export { ACL_SOURCE_DISPLAY_LABELS, displayAclSource } from "../utils/files-browse-acl.js";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, buildVaultConfig, } from "../utils/cognito-session.js";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
-import { getCompanyUid, looksLikeCompanyUid, vaultApiFetch, } from "../utils/vault-api.js";
+import { maxLength } from "../utils/table-width.js";
+import { getCompanyUid, looksLikeCompanyUid, looksLikePersonVaultUid, vaultApiFetch, } from "../utils/vault-api.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
 // ── Pure helpers ────────────────────────────────────────────────────────────
 /**
@@ -59,6 +63,11 @@ export function parseCompanySlugFromPath(prefix) {
     }
     return parts[1];
 }
+// Normalize personal paths before using them as S3 list prefixes.
+function normalizePersonalBrowsePrefix(pathPrefix) {
+    const normalized = pathPrefix.replace(/^\/+/, "");
+    return /^[/.]+$/.test(normalized) ? "" : normalized;
+}
 /**
  * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
  * the vault bucket actually stores. Company vault buckets are already
@@ -70,9 +79,15 @@ export function parseCompanySlugFromPath(prefix) {
  */
 export function toBucketRelative(pathOrPrefix, slug) {
     const anchor = `companies/${slug}/`;
+    const slugAnchor = `${slug}/`;
     const normalized = pathOrPrefix.replace(/^\/+/, "");
-    return normalized.startsWith(anchor)
-        ? normalized.slice(anchor.length)
+    if (normalized.startsWith(anchor))
+        return normalized.slice(anchor.length);
+    // Explicit-grant responses can use either the full company anchor or the
+    // historical bare-slug anchor. Strip both before classification, while
+    // preserving the caller's trailing `/` versus `/*` semantics.
+    return normalized.startsWith(slugAnchor)
+        ? normalized.slice(slugAnchor.length)
         : normalized;
 }
 /**
@@ -85,22 +100,55 @@ export function toCompanyAnchored(bucketRelKey, slug) {
 }
 /**
  * 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.
+ * raw explicit-grant patterns. `foo/*` covers all keys below `foo/`, while
+ * `foo/` is the private folder itself and never covers a child key. 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 `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.
+ * The caller translates only the redundant company anchor before calling this;
+ * it must not coalesce a trailing slash into a glob, which would imply child
+ * access that the server did not grant.
  */
-export function classifyAclSource(bucketRelKey, grantPrefixes) {
-    for (const p of grantPrefixes) {
-        if (p === "" || bucketRelKey.startsWith(p))
+export function classifyAclSource(bucketRelKey, grantPatterns) {
+    const normalized = grantPatterns.map((entry) => typeof entry === "string"
+        ? { pattern: entry, source: undefined }
+        : entry);
+    for (const entry of normalized) {
+        const pattern = entry.pattern;
+        if (pattern === "" || pattern === "*")
             return "shared-with-you";
+        if (pattern.endsWith("/*")) {
+            if (bucketRelKey.startsWith(pattern.slice(0, -1))) {
+                return entry.source === "creator" ? "creator" : "shared-with-you";
+            }
+            continue;
+        }
+        if (isPrivateFolderPattern(pattern)) {
+            if (bucketRelKey === pattern)
+                return "private-folder";
+            continue;
+        }
+        if (bucketRelKey === pattern) {
+            return entry.source === "creator" ? "creator" : "shared-with-you";
+        }
+    }
+    // The server can expose a creator-owned child row without returning the
+    // creator's original `foo/` row. Keep the zero-byte `foo/` marker visible
+    // and label it as creator access when a creator grant is underneath it.
+    if (bucketRelKey.endsWith("/")) {
+        const creatorOwnsMarker = normalized.some((entry) => entry.source === "creator" &&
+            entry.pattern.startsWith(bucketRelKey));
+        if (creatorOwnsMarker)
+            return "creator";
     }
     return "role-bypass";
 }
+/** Remove only the redundant company anchor; retain the ACL pattern itself. */
+export function toBrowseGrantPattern(grantPath, slug) {
+    const companyRelative = toBucketRelative(grantPath, slug);
+    return companyRelative === "*" ? "" : companyRelative;
+}
 /**
  * Bright-line guard for `--out`: refuse to write any byte beneath
  * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
@@ -132,17 +180,30 @@ export function formatBrowseTable(rows) {
         r.key,
         String(r.size),
         r.lastModified ? r.lastModified.toISOString() : "—",
-        r.aclSource,
+        displayAclSource(r.aclSource),
     ]);
-    const widths = cols.map((c, i) => Math.max(c.length, ...data.map((row) => row[i].length)));
+    const widths = cols.map((c, i) => maxLength(data, (row) => row[i].length, c.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),
     ];
+    for (const row of data)
+        lines.push(renderRow(row));
     return lines.join("\n");
 }
+function formatSearchResults(rows, query) {
+    if (rows.length === 0) {
+        return `No files found for search ${JSON.stringify(query)}.`;
+    }
+    return formatBrowseTable(rows);
+}
+function normalizeCompanySearchPath(value) {
+    return value
+        .split("/")
+        .map((segment) => (segment === "company" ? "companies" : segment))
+        .join("/");
+}
 /** Guard: the personal path needs an S3 factory. */
 function requirePersonalS3Factory(f) {
     if (!f) {
@@ -221,18 +282,28 @@ export async function runBrowse(input) {
     }
     // 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. 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
+    // listing. Personal-mode paths are normalized in bucket-relative form.
+    const bucketPrefix = personalMode
+        ? normalizePersonalBrowsePrefix(pathPrefix)
+        : slug === undefined
+            ? pathPrefix
+            : toBucketRelative(pathPrefix, slug);
+    // Company callers can spell the bucket root as `/` or `.`. S3's empty
+    // Prefix is the root; passing either literal would list under that key.
+    const listPrefix = !personalMode && (bucketPrefix === "/" || bucketPrefix === ".")
+        ? ""
+        : bucketPrefix;
+    // Pull the caller's explicit-grant graph once so per-key classification is
+    // O(grants) without N round-trips. Retain the raw pattern after stripping
+    // only the redundant company anchor: `foo/` and `foo/*` have different
+    // server semantics. Skipped in personal mode — the grants graph is a company
+    // concept; a person bucket marks every row `"personal-vault"`.
+    const grantPatterns = personalMode || slug === undefined
         ? []
-        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => grantPathToPrefix(g.path, slug));
+        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => ({
+            pattern: toBrowseGrantPattern(g.path, slug),
+            source: g.source,
+        }));
     const rows = [];
     let continuationToken;
     do {
@@ -244,8 +315,14 @@ export async function runBrowse(input) {
         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)
+            const aclSource = personalMode
+                ? "personal-vault"
+                : classifyAclSource(obj.Key, grantPatterns);
+            // Keep a private-folder marker visible so its ACL meaning can be shown.
+            // Other zero-byte directory markers remain list implementation details.
+            if (obj.Key.endsWith("/") &&
+                (obj.Size ?? 0) === 0 &&
+                aclSource !== "private-folder")
                 continue;
             // `obj.Key` is company-relative. Classify in that space, then re-anchor
             // for display so the CLI keeps speaking `companies/<slug>/...`.
@@ -255,9 +332,7 @@ export async function runBrowse(input) {
                     : toCompanyAnchored(obj.Key, slug),
                 size: obj.Size ?? 0,
                 lastModified: obj.LastModified,
-                aclSource: personalMode
-                    ? "personal-vault"
-                    : classifyAclSource(obj.Key, grantPrefixes),
+                aclSource,
             });
         }
         continuationToken = resp.NextContinuationToken ?? undefined;
@@ -306,18 +381,37 @@ export async function runCat(input) {
     }
     else {
         const slug = input.companySlug ?? parseCompanySlugFromPath(key);
-        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 (looksLikePersonVaultUid(slug)) {
+            // A `prs_` scope names a PERSON'S vault, which is where a DM attachment
+            // lives (`chat/attachments/dm/<uidA>--<uidB>/…`). There is no company
+            // entity to look up — `findInMyNamespace("company", …)` can only ever
+            // find a company, so it refuses the one scope the server accepts
+            // (hq-pro #3571 authorizes either member of the pair; hq-cli #644 made
+            // the presign path carry the ref). Go straight to the presign path and
+            // let the vault API's per-key gate decide.
+            //
+            // The key is already bucket-relative: a person vault has no
+            // `companies/<slug>/` anchor to strip. `Bucket` is inert on this path —
+            // the browse-vend company client presigns by companyUid + key and never
+            // reads it — so the scope ref is carried through for error messages.
+            bucket = slug;
+            s3Key = key;
+            s3 = requireCompanyClient(input.companyClient)({ companyUid: slug });
         }
-        if (!entity.bucketName) {
-            throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+        else {
+            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.`);
+            }
+            bucket = entity.bucketName;
+            // Translate the anchored CLI key into the company-relative bucket key.
+            s3Key = toBucketRelative(key, slug);
+            // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
+            s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
         }
-        bucket = entity.bucketName;
-        // Translate the anchored CLI key into the company-relative bucket key.
-        s3Key = toBucketRelative(key, slug);
-        // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
-        s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
     }
     // HQ-CLI-5: when writing to --out, create the parent directory BEFORE issuing
     // the presigned GET, so no synchronous filesystem call sits between receiving
@@ -415,14 +509,24 @@ export function formatSharedWithMeTable(rows) {
         return "Nothing is explicitly shared with you. (Owner/admin role-bypass access is not listed here — only explicit grants.)";
     }
     const cols = ["COMPANY", "PATH", "PERMISSION", "SOURCE"];
-    const data = rows.map((r) => [r.companySlug, r.path, r.permission, r.source]);
-    const widths = cols.map((c, i) => Math.max(c.length, ...data.map((row) => row[i].length)));
+    const data = rows.map((r) => [
+        r.companySlug,
+        isPrivateFolderPattern(r.path) ? `${r.path} (private folder)` : r.path,
+        r.permission,
+        r.source,
+    ]);
+    const widths = cols.map((c, i) => maxLength(data, (row) => row[i].length, c.length));
     const renderRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
-    return [
+    const lines = [
         chalk.bold(renderRow(cols)),
         chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
-        ...data.map(renderRow),
-    ].join("\n");
+    ];
+    for (const row of data)
+        lines.push(renderRow(row));
+    if (rows.some((row) => isPrivateFolderPattern(row.path))) {
+        lines.push("Private folders expose the folder only; children are creator-only.");
+    }
+    return lines.join("\n");
 }
 /**
  * `hq files search <query>` orchestrator. Lists the company (or personal)
@@ -445,7 +549,17 @@ export async function runSearch(input) {
         region: input.region,
     });
     const q = input.query.toLowerCase();
-    return rows.filter((r) => r.key.toLowerCase().includes(q));
+    // Only a leading `company/<slug>...` path form is an alias for the
+    // `companies/` anchor. A bare `company` stays a plain substring, since every
+    // company-mode key starts with `companies/<slug>/`.
+    const normalizedQuery = /^company\/[^/]+/.test(q)
+        ? normalizeCompanySearchPath(q)
+        : q;
+    return rows.filter((r) => {
+        const key = r.key.toLowerCase();
+        return (key.includes(q) ||
+            normalizeCompanySearchPath(key).includes(normalizedQuery));
+    });
 }
 /** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
 export function pinFilePath(hqRoot) {
@@ -596,7 +710,7 @@ export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
  * `send(...)` as if it held an S3 client.
  */
 export function createCompanyPresignClient(input) {
-    const { token, companyUid, companySlug } = input;
+    const { token, companyUid, companySlug, baseUrl } = input;
     const denied = (message, key, extra) => Object.assign(new Error(message), {
         status: 403,
         key,
@@ -610,7 +724,7 @@ export function createCompanyPresignClient(input) {
             query.prefix = prefix;
         if (cmd.input.ContinuationToken)
             query.cursor = cmd.input.ContinuationToken;
-        const res = await vaultApiFetch({ token, path: "/v1/files/list", query });
+        const res = await vaultApiFetch({ token, baseUrl, path: "/v1/files/list", query });
         if (!res.ok) {
             const body = (await res.json().catch(() => ({})));
             const message = body.message ?? body.error ?? `files list failed (${res.status})`;
@@ -641,6 +755,7 @@ export function createCompanyPresignClient(input) {
         const key = cmd.input.Key;
         const res = await vaultApiFetch({
             token,
+            baseUrl,
             path: "/v1/files/presign",
             method: "POST",
             body: { company: companyUid, key, op: "get" },
@@ -841,10 +956,11 @@ export async function resolveBrowseSession() {
  * 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) {
+export function registerFilesBrowseCommands(filesCmd, deps = {}) {
+    const personalS3Factory = deps.personalS3Factory ?? defaultS3Factory;
     filesCmd
         .command("browse [path]")
-        .description("List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.")
+        .description("List vault objects under [path] without syncing them locally. Private-folder rows (foo/) are labelled and do not imply child access; their children are creator-only. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.")
         .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>)")
         .option("--personal", "Browse the caller's canonical personal vault. [path] is treated as " +
         "bucket-relative (omit it to list the vault root). Mutually exclusive " +
@@ -875,7 +991,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                     personalMode: true,
                     personalUid,
                     vaultClient: cognito,
-                    s3Factory: defaultS3Factory,
+                    s3Factory: personalS3Factory,
                     region: DEFAULT_COGNITO.region,
                 });
                 console.log(formatBrowseTable(result.rows));
@@ -967,7 +1083,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                     personalMode: true,
                     personalUid,
                     vaultClient: cognito,
-                    s3Factory: defaultS3Factory,
+                    s3Factory: personalS3Factory,
                     region: DEFAULT_COGNITO.region,
                 });
                 if (result.destination.kind === "file") {
@@ -1016,7 +1132,7 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
     filesCmd
         .command("shared-with-me")
-        .description("List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
+        .description("List the files/prefixes explicitly shared with you. Private folders (foo/) expose only the folder; children are creator-only. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
         .option("--company <slug>", "Scope to a single company (defaults to a cross-company roll-up).")
         .action(async (options, command) => {
         try {
@@ -1084,10 +1200,10 @@ export function registerFilesBrowseCommands(filesCmd) {
                     personalMode: true,
                     personalUid,
                     vaultClient: cognito,
-                    s3Factory: defaultS3Factory,
+                    s3Factory: personalS3Factory,
                     region: DEFAULT_COGNITO.region,
                 });
-                console.log(formatBrowseTable(rows));
+                console.log(formatSearchResults(rows, query));
                 return;
             }
             if (!company) {
@@ -1101,7 +1217,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 companyClient: makeCompanyPresignFactory(accessToken, company),
                 region: DEFAULT_COGNITO.region,
             });
-            console.log(formatBrowseTable(rows));
+            console.log(formatSearchResults(rows, query));
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/commands/files.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+export declare const FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG = "files.share-empty-prefix-warning";
 /**
  * Parse a human-friendly duration string ("15m", "1h", "24h", "2d") into
  * milliseconds. Returns null on parse failure. Mirrors the parser used in
@@ -62,6 +63,22 @@ export declare class FilesDeleteHttpError extends Error {
 export declare function formatFilesDeleteError(err: FilesDeleteHttpError, prefix: string): string;
 /** Injectable yes/no confirmation seam (stubbed in tests). */
 export type ConfirmFn = (message: string) => Promise<boolean>;
+/**
+ * POST /v1/files/delete. Throws FilesDeleteHttpError on any non-2xx so the one
+ * caller renders a single consistent error path.
+ *
+ * Scope is EITHER a company vault (`companyUid` set) OR the caller's personal
+ * vault (`personal: true`). For the personal case the server resolves the target
+ * person + bucket from the authenticated caller — we send NO uid, just the
+ * `personal` flag — so there is nothing for the client to get wrong or spoof.
+ */
+export declare function callDeleteEndpoint(params: {
+    token: string;
+    companyUid?: string;
+    personal?: boolean;
+    prefix: string;
+    dryRun: boolean;
+}): Promise<FilesDeleteResponse>;
 interface RunFilesDeleteParams {
     prefix: string;
     dryRun: boolean;