@indigoai-us/hq-cli 5.108.26 → 5.109.1

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [5.109.1] — 2026-09-08
+
+### Added
+
+- `hq access` records each outcome (outcome, company, timestamp only) to
+  `.hq/access-outcomes.jsonl` so the cause mix can be reviewed later.
+
+## [5.109.0] — 2026-09-08
+
+### Added
+
+- `hq access <path-or-query>` — one command for "I can't find or open this
+  file". Resolves an exact key or a fuzzy name (never auto-picks between
+  several hits), then reports exactly one of `never-existed`, `local`,
+  `not-synced`, or `no-access` (exit 0/2/3, 4 for ambiguous). When the file
+  exists and you can read it but it is not on disk, it fetches and pins it the
+  same way `hq files get` does, and if that fails it runs `hq sync status`,
+  `hq sync doctor`, and retries once. When you lack access it names the
+  grantor (ACL creator, then company owner/admin), shows their email, asks one
+  yes/no question, and sends them a DM whose Copy-prompt is the exact
+  `hq files share … --permission read` command. Repeat requests for the same
+  prefix are deduped for 24h via `.hq/access-requests.json`. `--json` without
+  `--yes` never sends; `--no-fix` diagnoses only.
+- Every access-denied (403) error from `hq files …` and `hq sync …` now ends
+  with `Run: hq access <path>`; in a TTY it offers to run it for you.
+  Existing messages and exit codes are unchanged.
+
 ## [5.108.26] — 2026-09-08
 
 ### Added

package/dist/commands/__fixtures__/access-vault.d.ts

@@ -0,0 +1,93 @@
+/**
+ * In-memory vault / ACL / DM harness for the `hq access` command.
+ * No network I/O — listings, GetObject, STS vend, and DMs stay in process
+ * (or under a tmp hqRoot the caller supplies).
+ */
+import { vi } from "vitest";
+import type { CompanyBrowseClientFactory, FilesBrowseVaultClient } from "../files-browse.js";
+export type AccessVaultState = "missing" | "present-local" | "present-not-local" | "present-denied";
+export interface FakeDmMessage {
+    recipient: string;
+    message: string;
+    prompt?: string;
+    details?: string;
+}
+export interface FakeDmTransport {
+    sent: FakeDmMessage[];
+    send(msg: FakeDmMessage): Promise<{
+        eventId: string;
+    }>;
+}
+export declare function makeFakeDmTransport(): FakeDmTransport;
+export interface AclEntry {
+    granteeType: string;
+    granteeId: string;
+    permission: string;
+    grantedBy: string;
+    grantedAt: string;
+}
+export interface AccessAclTree {
+    prefix: string;
+    direct: AclEntry[];
+    inherited: Array<AclEntry & {
+        sourcePrefix: string;
+    }>;
+    children: Array<AclEntry & {
+        sourcePrefix: string;
+    }>;
+    directRow: {
+        creatorUid: string;
+        open: boolean;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+    effectivePermission: string | null;
+}
+export interface AccessMember {
+    personUid: string;
+    personEmail: string;
+    personName?: string;
+    role: "owner" | "admin" | "member" | "guest";
+}
+export interface AccessVaultFixture {
+    state: AccessVaultState;
+    hqRoot: string;
+    companySlug: string;
+    companyUid: string;
+    /** Company-anchored e.g. companies/acme/knowledge/report.md */
+    key: string;
+    /** Company-relative e.g. knowledge/report.md */
+    bucketKey: string;
+    vaultClient: FilesBrowseVaultClient;
+    companyClient: CompanyBrowseClientFactory;
+    vend: ReturnType<typeof vi.fn>;
+    acl: AccessAclTree | null;
+    members: AccessMember[];
+    dm: FakeDmTransport;
+    listedKeys: string[];
+    region: string;
+}
+export interface MakeAccessFixtureOptions {
+    state: AccessVaultState;
+    hqRoot: string;
+    companySlug?: string;
+    key?: string;
+    extraKeys?: string[];
+    acl?: AccessAclTree | null;
+    members?: AccessMember[];
+    content?: string;
+    /**
+     * `present-denied` only: make the LIST call itself fail with 403 (the
+     * `/v1/files/list` shape) instead of returning the key. Models a caller
+     * without read on the prefix — the server refuses to enumerate.
+     */
+    listDenied?: boolean;
+    /** Deny only the ROOT (prefix "") list — the caller can read the prefix but not enumerate the bucket. */
+    rootListDenied?: boolean;
+}
+export declare function vendStatusForState(state: AccessVaultState): {
+    status: number;
+    message?: string;
+};
+export declare function makeAccessFixture(opts: MakeAccessFixtureOptions): AccessVaultFixture;
+//# sourceMappingURL=access-vault.d.ts.map

package/dist/commands/__fixtures__/access-vault.js

@@ -0,0 +1,166 @@
+/**
+ * In-memory vault / ACL / DM harness for the `hq access` command.
+ * No network I/O — listings, GetObject, STS vend, and DMs stay in process
+ * (or under a tmp hqRoot the caller supplies).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+import { vi } from "vitest";
+import { ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
+export function makeFakeDmTransport() {
+    const sent = [];
+    let n = 0;
+    return {
+        sent,
+        async send(msg) {
+            sent.push(msg);
+            n += 1;
+            return { eventId: `evt_${n}` };
+        },
+    };
+}
+const FAKE_VEND = {
+    credentials: {
+        accessKeyId: "ASIA-test",
+        secretAccessKey: "secret-test",
+        sessionToken: "session-test",
+    },
+};
+const DEFAULT_MEMBERS = [
+    {
+        personUid: "prs_owner",
+        personEmail: "owner@example.com",
+        personName: "Olive Owner",
+        role: "owner",
+    },
+    {
+        personUid: "prs_admin",
+        personEmail: "admin@example.com",
+        personName: "Adam Admin",
+        role: "admin",
+    },
+    {
+        personUid: "prs_me",
+        personEmail: "me@example.com",
+        personName: "Mia Member",
+        role: "member",
+    },
+];
+export function vendStatusForState(state) {
+    if (state === "missing")
+        return { status: 404 };
+    if (state === "present-denied") {
+        return { status: 403, message: "caller lacks read on this prefix" };
+    }
+    return { status: 200 };
+}
+function attachStatus(err, status) {
+    const tagged = err;
+    tagged.status = status;
+    return tagged;
+}
+function attachHttpStatus(err, httpStatusCode) {
+    const tagged = err;
+    tagged.$metadata = { httpStatusCode };
+    return tagged;
+}
+function toBucketKey(key, slug) {
+    const prefix = `companies/${slug}/`;
+    const trimmed = key.replace(/^\/+/, "");
+    if (trimmed.startsWith(prefix))
+        return trimmed.slice(prefix.length);
+    return trimmed;
+}
+export function makeAccessFixture(opts) {
+    const companySlug = opts.companySlug ?? "acme";
+    const key = opts.key ?? `companies/${companySlug}/knowledge/report.md`;
+    const bucketKey = toBucketKey(key, companySlug);
+    const companyUid = `cmp_${companySlug}`;
+    const content = opts.content ?? "hello";
+    const extraKeys = opts.extraKeys ?? [];
+    const listedKeys = opts.state === "missing" ? [...extraKeys] : [...extraKeys, bucketKey];
+    const members = opts.members ?? DEFAULT_MEMBERS;
+    const acl = opts.acl === undefined ? null : opts.acl;
+    const region = "us-east-1";
+    const dm = makeFakeDmTransport();
+    if (opts.state === "present-local") {
+        const dest = path.join(opts.hqRoot, key);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, content, "utf-8");
+    }
+    const vend = vi.fn(async () => {
+        if (opts.state === "missing") {
+            throw attachStatus(new Error("not found (404)"), 404);
+        }
+        if (opts.state === "present-denied") {
+            throw attachStatus(new Error("caller lacks read on this prefix (403)"), 403);
+        }
+        return FAKE_VEND;
+    });
+    const vendSelf = vi.fn(async () => FAKE_VEND);
+    const listMyExplicitGrants = vi.fn(async () => []);
+    const entityShape = {
+        uid: companyUid,
+        slug: companySlug,
+        name: companySlug,
+        bucketName: `hq-vault-cmp-${companySlug}`,
+    };
+    const findInMyNamespace = vi.fn(async () => entityShape);
+    const get = vi.fn(async () => entityShape);
+    const vaultClient = {
+        sts: { vend, vendSelf },
+        listMyExplicitGrants,
+        entity: { get, findInMyNamespace },
+    };
+    const listDenied = opts.state === "present-denied" && opts.listDenied === true;
+    const send = vi.fn(async (cmd) => {
+        if (cmd instanceof ListObjectsV2Command) {
+            const prefix = cmd.input.Prefix ?? "";
+            if (listDenied || (opts.rootListDenied === true && prefix === "")) {
+                throw Object.assign(new Error("files list failed (403)"), {
+                    status: 403,
+                    key: prefix,
+                    company: companySlug,
+                });
+            }
+            const Contents = listedKeys
+                .filter((k) => (prefix === "" ? true : k.startsWith(prefix)))
+                .map((Key) => ({
+                Key,
+                Size: content.length,
+                LastModified: new Date(),
+            }));
+            return { Contents };
+        }
+        if (cmd instanceof GetObjectCommand) {
+            const requested = cmd.input.Key ?? "";
+            if (opts.state === "missing" || requested !== bucketKey) {
+                throw attachHttpStatus(new Error("Not found (404)"), 404);
+            }
+            if (opts.state === "present-denied") {
+                throw attachHttpStatus(new Error("caller lacks read on this prefix"), 403);
+            }
+            return { Body: Readable.from([content]) };
+        }
+        throw new Error(`unexpected command: ${cmd}`);
+    });
+    const companyClient = vi.fn(() => ({ send }));
+    return {
+        state: opts.state,
+        hqRoot: opts.hqRoot,
+        companySlug,
+        companyUid,
+        key,
+        bucketKey,
+        vaultClient,
+        companyClient,
+        vend,
+        acl,
+        members,
+        dm,
+        listedKeys,
+        region,
+    };
+}
+//# sourceMappingURL=access-vault.js.map

package/dist/commands/access.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `hq access <path-or-query>` — existence + ACL probe with a self-healing
+ * ladder: resolve, list, probe ACL, then (with --fix) download / pin / repair
+ * sync or request access from the grantor.
+ *
+ * Tells a teammate whether a vault file exists and whether they can read it,
+ * so they never see a bare not-found.
+ *
+ * Vending uses the multi-tenant STS route `vaultClient.sts.vend({ companyUid })`
+ * (`/sts/vend`). The legacy `POST /vend` is never used — it assumes a single
+ * static BUCKET_ARN that is unset in multi-tenant prod.
+ *
+ * Company vault keys are company-relative; the CLI speaks the anchored form
+ * `companies/<slug>/...` for display.
+ */
+import { Command } from "commander";
+import { type CompanyBrowseClientFactory, type FilesBrowseVaultClient, type RunGetResult } from "./files-browse.js";
+export type AccessOutcome = "never-existed" | "local" | "not-synced" | "no-access" | "ambiguous" | "pending-confirmation";
+export interface AccessAclTree {
+    prefix: string;
+    direct: Array<{
+        granteeType: string;
+        granteeId: string;
+        permission: string;
+        grantedBy: string;
+        grantedAt: string;
+    }>;
+    inherited: Array<{
+        granteeType: string;
+        granteeId: string;
+        permission: string;
+        grantedBy: string;
+        grantedAt: string;
+        sourcePrefix: string;
+    }>;
+    children: Array<{
+        granteeType: string;
+        granteeId: string;
+        permission: string;
+        grantedBy: string;
+        grantedAt: string;
+        sourcePrefix: string;
+    }>;
+    directRow: {
+        creatorUid: string;
+        open: boolean;
+        createdAt: string;
+        updatedAt: string;
+    } | null;
+    effectivePermission: string | null;
+}
+export interface AccessMember {
+    personUid: string;
+    personEmail: string;
+    personName?: string;
+    role: "owner" | "admin" | "member" | "guest";
+}
+export interface AccessGrantor {
+    personUid: string;
+    email: string;
+    name?: string;
+    source: "acl-creator" | "owner" | "admin";
+}
+export interface AccessDeps {
+    hqRoot: string;
+    companySlug: string;
+    companyUid: string;
+    vaultClient: FilesBrowseVaultClient;
+    companyClient: CompanyBrowseClientFactory;
+    region: string;
+    /** GET acl/tree for the exact company-relative prefix; null = no ACL record. */
+    fetchAclTree: (prefix: string) => Promise<AccessAclTree | null>;
+    /** Active members (owner/admin/member/guest) — used for grantor resolution. */
+    listMembers: () => Promise<AccessMember[]>;
+    requester: {
+        email: string;
+        name?: string;
+    };
+    dm?: {
+        send(msg: {
+            recipient: string;
+            message: string;
+            prompt?: string;
+            details?: string;
+        }): Promise<{
+            eventId: string;
+        }>;
+    };
+    confirm?: (question: string) => Promise<boolean>;
+    now?: () => number;
+    /** Multi-hit chooser. Absent or returning null ⇒ outcome "ambiguous". Never auto-pick. */
+    pick?: (candidates: string[]) => Promise<string | null>;
+    /** Plain-text sink (default console.log). Tests capture it. */
+    log?: (line: string) => void;
+    /**
+     * Diagnostic sink (default console.error). Carries the recipient line before
+     * a DM is sent so it is visible even under --json, whose stdout must stay
+     * a single JSON object.
+     */
+    stderr?: (line: string) => void;
+    /** Materialize + pin one path. Default: runGet from ./files-browse.js. */
+    get?: (anchoredPath: string) => Promise<RunGetResult>;
+    /** Summarise local sync journal state for the company. */
+    syncStatus?: () => Promise<string>;
+    /** Sync doctor. Default wraps hq-cloud syncDoctor(reconcileConflicts). */
+    syncDoctor?: (apply: boolean) => Promise<SyncDoctorOutcome>;
+}
+export interface SyncDoctorOutcome {
+    twins: number;
+    summary: string;
+    bulkRefused?: boolean;
+    breakerMessage?: string;
+}
+export interface RunAccessInput {
+    target: string;
+    fix: boolean;
+    json: boolean;
+    yes?: boolean;
+    deps: AccessDeps;
+}
+export interface RunAccessResult {
+    outcome: AccessOutcome;
+    path: string;
+    company: string;
+    exists: boolean;
+    grantor?: AccessGrantor;
+    candidates?: string[];
+    steps: string[];
+    exitCode: 0 | 2 | 3 | 4;
+    /** True when the self-heal get rung materialized the file. Omitted when not fixed. */
+    fixed?: boolean;
+    localPath?: string;
+    requestSentAt?: string;
+    alreadyAskedAt?: string;
+    requestNote?: string;
+}
+export declare function outcomeExitCode(outcome: AccessOutcome): 0 | 2 | 3 | 4;
+export declare function formatAccessOutcome(result: RunAccessResult): string;
+export declare function resolveGrantor(tree: AccessAclTree | null, members: AccessMember[]): AccessGrantor | null;
+export declare function runAccess(input: RunAccessInput): Promise<RunAccessResult>;
+export declare function registerAccessCommand(program: Command): void;
+/**
+ * Resolve the company `hq access` runs against: explicit `company` (the
+ * ladder forwards the slug stamped on a 403), else the slug anchored in the
+ * target path, else the active company in `<hqRoot>/.hq/config.json`.
+ */
+export declare function resolveAccessCompany(target: string, opts?: {
+    company?: string;
+    hqRoot?: string;
+}): string | undefined;
+export declare function runAccessForPath(path: string, opts?: {
+    company?: string;
+    hqRoot?: string;
+    json?: boolean;
+    yes?: boolean;
+    fix?: boolean;
+}): Promise<RunAccessResult>;
+//# sourceMappingURL=access.d.ts.map