@indigoai-us/hq-cli 5.17.0 → 5.18.0

package/dist/commands/sync-narrow.js

@@ -0,0 +1,327 @@
+/**
+ * `hq sync narrow` (US-007) — explicit migration ritual to flip a company's
+ * membership from `syncMode: all` to `syncMode: shared`, with a dry-run
+ * preview and a dirty-file safety gate.
+ *
+ * Two call shapes:
+ *
+ *   hq sync narrow --dry-run [--company <slug>]
+ *       Resolves the membership for <slug> (or the active company), fetches
+ *       the caller's explicit grants, coalesces them, walks the local
+ *       `companies/<slug>/` tree, and prints a table:
+ *
+ *           files staying:  N
+ *           clean orphans:  N (size)
+ *           dirty orphans:  N (size)
+ *
+ *       Writes nothing — no journal, no local file, no server call beyond
+ *       the read-only GET on grants + sync-config.
+ *
+ *   hq sync narrow --apply [--yes] [--force] [--company <slug>]
+ *       Same computation, then:
+ *         - if `dirty > 0` and `--force` NOT set → abort with conflict report
+ *           and a recovery message.
+ *         - else delete clean orphans on disk, tombstone their journal
+ *           entries, optionally delete dirty orphans too (with `--force`),
+ *           then PUT sync-config to `shared`. The server's PUT writes the
+ *           authoritative `MEMBERSHIP_SYNC_CONFIG_CHANGED` audit row; the
+ *           CLI prints a local audit line as well.
+ *
+ * Refuses on already-`shared` or `custom` memberships (acceptance 5) —
+ * narrowing makes sense only as `all → shared`.
+ *
+ * Cross-package note: depends on hq-cloud helpers shipped in US-005
+ * (`coalescePrefixes`, `readJournal`/`writeJournal`, `tombstoneEntry`) and
+ * the VaultClient sync-config endpoints from US-003. While that hq-cloud
+ * release is unpublished, hq-cli pins `@indigoai-us/hq-cloud` to
+ * `file:../hq-cloud` via `pnpm.overrides`.
+ */
+
+!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]="a6c1e2b9-5d9a-57b2-a80b-adfdbce88206")}catch(e){}}();
+import chalk from "chalk";
+import * as readline from "node:readline";
+import * as fs from "node:fs";
+import { VaultClient, coalescePrefixes, readJournal, writeJournal, tombstoneEntry, } from "@indigoai-us/hq-cloud";
+import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { readActiveCompanySlug } from "./sync-mode.js";
+import { buildNarrowPlan, formatBytes, formatNarrowPlanSummary, } from "../lib/local-tree-diff.js";
+const realJournalIO = {
+    read: readJournal,
+    write: writeJournal,
+};
+const realFsIO = {
+    unlinkSync: fs.unlinkSync,
+};
+const realConfirm = async (message) => {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+};
+/**
+ * Resolve the caller's membership for `companySlug` and read its current
+ * sync-config. Throws if the slug doesn't match any membership or if the
+ * current mode isn't eligible for narrowing (`all` → `shared` only).
+ */
+export async function resolveNarrowTarget(input) {
+    const { companySlug, vaultClient } = input;
+    const memberships = await vaultClient.listMyMemberships();
+    const enriched = await Promise.all(memberships.map(async (m) => {
+        try {
+            const ent = await vaultClient.entity.get(m.companyUid);
+            return { membership: m, slug: ent.slug, name: ent.name };
+        }
+        catch {
+            return { membership: m, slug: undefined, name: undefined };
+        }
+    }));
+    const match = enriched.find((row) => row.slug === companySlug);
+    if (!match) {
+        const known = enriched
+            .map((r) => r.slug)
+            .filter((s) => !!s)
+            .join(", ");
+        throw new Error(`No membership found for company '${companySlug}'. Memberships visible to you: ${known || "(none)"}.`);
+    }
+    const membership = match.membership;
+    const syncConfig = await vaultClient.getMembershipSyncConfig(membership.membershipKey);
+    if (syncConfig.syncMode !== "all") {
+        throw new Error(`Refusing to narrow: membership for '${companySlug}' is currently ` +
+            `syncMode='${syncConfig.syncMode}'. The narrow ritual only runs on ` +
+            `syncMode='all' memberships (shared → shared is a no-op; ` +
+            `custom requires \`hq sync mode shared\` directly).`);
+    }
+    return {
+        membership,
+        companyUid: membership.companyUid,
+        companySlug,
+        syncConfig,
+    };
+}
+/**
+ * Compute the narrow plan for one company: fetch explicit grants, coalesce,
+ * read the per-company journal, walk the local tree, classify.
+ *
+ * Reads only — never mutates the journal or hits a destructive endpoint.
+ * `apply()` consumes this and performs the destructive steps.
+ */
+export async function computeNarrowPlan(input) {
+    const { hqRoot, companySlug, companyUid, vaultClient } = input;
+    const io = input.journalIO ?? realJournalIO;
+    const grants = await vaultClient.listMyExplicitGrants(companyUid);
+    const prospectivePrefixSet = coalescePrefixes(grants.map((g) => g.path));
+    const journal = io.read(companySlug);
+    const plan = buildNarrowPlan({
+        hqRoot,
+        companySlug,
+        prospectivePrefixSet,
+        journal,
+    });
+    return { plan, prospectivePrefixSet, grants, journal };
+}
+/**
+ * Apply the destructive side of a narrow:
+ *   1. Delete clean orphans (best-effort — ENOENT is ignored).
+ *   2. Tombstone their journal entries.
+ *   3. If `force`, also delete + tombstone dirty orphans.
+ *   4. Persist the journal.
+ *   5. PUT sync-config → `shared` (server writes the audit row).
+ *
+ * Order is fail-safe: if a delete throws partway, the journal write below
+ * won't run, but the in-progress deletions are already on disk — that's the
+ * "don't roll back I/O" contract from the spec. The CLI surfaces a
+ * recovery message when this throws.
+ *
+ * Pure-ish: no prompting (the CLI wrapper handles that), no console
+ * output. Just disk + network.
+ */
+export async function applyNarrow(input) {
+    const { plan, journal, force, companySlug, membershipId, vaultClient } = input;
+    const journalIO = input.journalIO ?? realJournalIO;
+    const fsIO = input.fsIO ?? realFsIO;
+    let cleanDeleted = 0;
+    let dirtyDeleted = 0;
+    let tombstoned = 0;
+    const cleanBytes = plan.clean.reduce((sum, f) => sum + f.bytes, 0);
+    const dirtyBytes = force
+        ? plan.dirty.reduce((sum, f) => sum + f.bytes, 0)
+        : 0;
+    // 1. Delete clean orphans + tombstone.
+    for (const file of plan.clean) {
+        try {
+            fsIO.unlinkSync(file.absPath);
+            cleanDeleted++;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err;
+        }
+        tombstoneEntry(journal, file.relPath, "narrow_apply");
+        tombstoned++;
+    }
+    // 2. With --force, delete dirty orphans too.
+    if (force) {
+        for (const file of plan.dirty) {
+            try {
+                fsIO.unlinkSync(file.absPath);
+                dirtyDeleted++;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "ENOENT")
+                    throw err;
+            }
+            // tombstone only if a journal entry exists — `not-in-journal` files
+            // never had one to tombstone.
+            if (journal.files[file.relPath]) {
+                tombstoneEntry(journal, file.relPath, "narrow_apply");
+                tombstoned++;
+            }
+        }
+    }
+    // 3. Persist journal.
+    journalIO.write(companySlug, journal);
+    // 4. PUT sync-config → shared. Server writes the authoritative
+    //    MEMBERSHIP_SYNC_CONFIG_CHANGED audit row.
+    const newConfig = await vaultClient.setMembershipSyncConfig(membershipId, {
+        syncMode: "shared",
+    });
+    return {
+        cleanDeleted,
+        cleanBytes,
+        dirtyDeleted,
+        dirtyBytes,
+        tombstoned,
+        newConfig,
+    };
+}
+// ── Dirty-file conflict report (operator-facing) ───────────────────────────
+/**
+ * Format the dirty-file conflict report shown on `--apply` when dirty files
+ * are present and `--force` is NOT set. The CLI prints this and exits
+ * non-zero so the operator can resolve before retrying.
+ */
+export function formatDirtyConflictReport(dirty, companySlug) {
+    const lines = [];
+    lines.push(`Aborting narrow for '${companySlug}': ${dirty.length} locally-modified file(s) ` +
+        `would be removed by this narrow.`);
+    lines.push("");
+    lines.push("Dirty files:");
+    const cap = 25;
+    for (const f of dirty.slice(0, cap)) {
+        lines.push(`  ${f.relPath}  (${formatBytes(f.bytes)}, ${f.reason})`);
+    }
+    if (dirty.length > cap) {
+        lines.push(`  ... ${dirty.length - cap} more`);
+    }
+    lines.push("");
+    lines.push("Resolve before retrying:");
+    lines.push("  - commit or push the modifications via the normal sync flow;");
+    lines.push("  - move them outside the company folder; or");
+    lines.push("  - delete them locally if they really should be gone.");
+    lines.push("");
+    lines.push("Alternatively, re-run with --force to remove the dirty files anyway " +
+        "(destructive — there is no undo).");
+    return lines.join("\n");
+}
+/**
+ * Wire `hq sync narrow` onto the existing `sync` Commander group. Called
+ * from `src/index.ts` after `registerSyncModeCommand`.
+ */
+export function registerSyncNarrowCommand(syncCmd) {
+    syncCmd
+        .command("narrow")
+        .description("Migrate a company's membership from syncMode='all' to 'shared' — " +
+        "dry-run previews diff, --apply performs the prune + flip")
+        .option("--dry-run", "Compute + print the narrow plan; write nothing (default if neither --dry-run nor --apply is passed)")
+        .option("--apply", "Execute the narrow — delete clean orphans, flip sync-mode to 'shared'")
+        .option("--yes", "Skip the interactive confirmation prompt on --apply")
+        .option("--force", "On --apply, also remove locally-modified (dirty) files (destructive — no undo)")
+        .option("--company <slug>", "Company slug (defaults to the active company in <hq-root>/.hq/config.json)")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(async (options) => {
+        try {
+            if (options.dryRun && options.apply) {
+                throw new Error("--dry-run and --apply are mutually exclusive.");
+            }
+            // Default to dry-run when nothing is specified — safer.
+            const apply = !!options.apply;
+            const dryRun = !apply;
+            const companySlug = options.company ?? readActiveCompanySlug(options.hqRoot);
+            if (!companySlug) {
+                throw new Error("No company specified. Pass --company <slug> or set activeCompany in <hq-root>/.hq/config.json.");
+            }
+            const accessToken = await ensureCognitoToken();
+            const vaultConfig = buildVaultConfig(accessToken);
+            const client = new VaultClient(vaultConfig);
+            const target = await resolveNarrowTarget({
+                companySlug,
+                vaultClient: client,
+            });
+            const { plan, prospectivePrefixSet, grants } = await computeNarrowPlan({
+                hqRoot: options.hqRoot,
+                companySlug: target.companySlug,
+                companyUid: target.companyUid,
+                vaultClient: client,
+            });
+            // Always print the summary.
+            console.log(chalk.bold(`${dryRun ? "Dry-run" : "Apply"}: narrow '${target.companySlug}' (${grants.length} explicit grant${grants.length === 1 ? "" : "s"}, ${prospectivePrefixSet.length} coalesced prefix${prospectivePrefixSet.length === 1 ? "" : "es"})`));
+            console.log(formatNarrowPlanSummary(plan));
+            if (dryRun) {
+                if (plan.totalDirtyCount > 0) {
+                    console.log("");
+                    console.log(chalk.yellow(`Heads-up: ${plan.totalDirtyCount} dirty file(s) would block --apply unless --force is passed.`));
+                }
+                return;
+            }
+            // --apply path
+            if (plan.totalDirtyCount > 0 && !options.force) {
+                console.error(chalk.red(formatDirtyConflictReport(plan.dirty, target.companySlug)));
+                process.exit(2);
+                return;
+            }
+            if (!options.yes) {
+                const force = !!options.force;
+                const dirtyTail = force
+                    ? ` AND remove ${plan.totalDirtyCount} dirty file(s) (--force)`
+                    : "";
+                const confirmed = await realConfirm(`About to remove ${plan.totalCleanCount} clean file(s)${dirtyTail} and flip '${target.companySlug}' to syncMode='shared'. Proceed?`);
+                if (!confirmed) {
+                    console.log("Cancelled. No changes applied.");
+                    return;
+                }
+            }
+            // Re-read the journal at apply time to avoid races with concurrent syncs.
+            const journal = readJournal(target.companySlug);
+            const result = await applyNarrow({
+                companySlug: target.companySlug,
+                membershipId: target.membership.membershipKey,
+                plan,
+                journal,
+                vaultClient: client,
+                force: !!options.force,
+            });
+            console.log(chalk.green("✓"), `Narrow applied for ${chalk.bold(target.companySlug)}:`);
+            console.log(chalk.dim(`  removed: ${result.cleanDeleted} clean (${formatBytes(result.cleanBytes)})${result.dirtyDeleted > 0
+                ? ` + ${result.dirtyDeleted} dirty (${formatBytes(result.dirtyBytes)})`
+                : ""}`));
+            console.log(chalk.dim(`  tombstoned: ${result.tombstoned} journal entr${result.tombstoned === 1 ? "y" : "ies"}`));
+            console.log(chalk.dim(`  syncMode: all → ${result.newConfig.syncMode}` +
+                (result.newConfig.updatedAt ? ` (updatedAt: ${result.newConfig.updatedAt})` : "")));
+            console.log(chalk.dim(`  audit: server-side MEMBERSHIP_SYNC_CONFIG_CHANGED row written by PUT /v1/memberships/${target.membership.membershipKey}/sync-config`));
+        }
+        catch (err) {
+            console.error(chalk.red("✗ sync narrow failed:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=sync-narrow.js.map
+//# debugId=a6c1e2b9-5d9a-57b2-a80b-adfdbce88206

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="2fc192b3-daa6-5939-a152-1422a7908e87")}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]="a9b69c08-39a6-58c3-a4b6-a309d0ab8254")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -11,6 +11,8 @@ import { registerSyncCommand } from "./commands/sync.js";
 import { registerListCommand } from "./commands/list.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerCloudCommands } from "./commands/cloud.js";
+import { registerSyncModeCommand } from "./commands/sync-mode.js";
+import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
 import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
 import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
 import { registerLoginCommand } from "./commands/login.js";
@@ -27,6 +29,7 @@ import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
 import { registerFilesCommand } from "./commands/files.js";
+import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
@@ -77,6 +80,8 @@ const syncCmd = program
     .command("sync")
     .description("Cloud sync commands — sync HQ to S3 for mobile access");
 registerCloudCommands(syncCmd);
+registerSyncModeCommand(syncCmd);
+registerSyncNarrowCommand(syncCmd);
 // Cloud provisioning subcommand group (entity + bucket + initial sync)
 // Distinct from `hq sync` which assumes provisioning has already happened.
 const cloudCmd = program
@@ -98,7 +103,10 @@ registerRunCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
 registerGroupsCommand(program);
 // Files ACL management (subcommand group — hq files share|unshare|acl)
-registerFilesCommand(program);
+// `registerFilesCommand` returns the `files` group so we can attach the
+// browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
+const filesCmd = registerFilesCommand(program);
+registerFilesBrowseCommands(filesCmd);
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);
 // Onboarding (top-level — Cognito + vault-service provisioning)
@@ -129,4 +137,4 @@ registerSignalsCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=2fc192b3-daa6-5939-a152-1422a7908e87
+//# debugId=a9b69c08-39a6-58c3-a4b6-a309d0ab8254

package/dist/lib/local-tree-diff.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure helper for `hq sync narrow` (US-007).
+ *
+ * Walks a local directory tree under `<hqRoot>/companies/{slug}/`, classifies
+ * each file against a prospective `shared`-mode prefix set, and groups the
+ * results into three buckets:
+ *
+ *   - **staying**  — file is covered by the prospective prefix set; survives.
+ *   - **clean**    — file is NOT covered (orphan) AND is provably unchanged
+ *                    since the last journal sync (safe to delete).
+ *   - **dirty**    — file is NOT covered (orphan) AND has been locally
+ *                    modified since the last sync (sacred — abort without
+ *                    `--force`).
+ *
+ * The clean-vs-dirty rule mirrors hq-cloud's implicit-shrink path
+ * (`scope-shrink.ts::classifyOrphan`) verbatim so the two narrowing paths —
+ * implicit (next pull after sync-mode flip) and explicit (`hq sync narrow
+ * --apply`) — agree on what "dirty" means. See US-000 Task 3 in
+ * `companies/indigo/projects/hq-sync-browse-vs-sync/references.md`.
+ *
+ * Pure: no network. Reads the journal off `SyncJournal` (caller passes it
+ * in), stats + hashes files on disk — no journal mutations and no remote
+ * calls happen here. The CLI orchestrator (`sync-narrow.ts`) is responsible
+ * for the destructive side effects (delete, tombstone, PUT sync-config).
+ */
+import { type SyncJournal } from "@indigoai-us/hq-cloud";
+export type DirtyReason = "modified-after-sync" | "hash-mismatch" | "not-in-journal" | "stat-error";
+export interface NarrowFile {
+    /** Path relative to `hqRoot` (matches journal key + S3 key naming). */
+    relPath: string;
+    /** Absolute path on disk (convenience for the CLI delete loop). */
+    absPath: string;
+    /** Size in bytes from the local stat. 0 for symlinks (lstat size is the link, not target). */
+    bytes: number;
+}
+export interface NarrowDirtyFile extends NarrowFile {
+    reason: DirtyReason;
+}
+export interface NarrowPlan {
+    /** Files covered by `prospectivePrefixSet` — survive the narrow. */
+    staying: NarrowFile[];
+    /** Orphan files that are journal-clean — safe to delete on `--apply`. */
+    clean: NarrowFile[];
+    /** Orphan files that are locally dirty — block `--apply` unless `--force`. */
+    dirty: NarrowDirtyFile[];
+    totalStayingCount: number;
+    totalCleanCount: number;
+    totalCleanBytes: number;
+    totalDirtyCount: number;
+    totalDirtyBytes: number;
+}
+export interface BuildNarrowPlanInput {
+    /** Absolute HQ root path (the dir containing `companies/`). */
+    hqRoot: string;
+    /** Company slug — used to derive the walk root `<hqRoot>/companies/<slug>/`. */
+    companySlug: string;
+    /**
+     * Coalesced prospective `shared`-mode prefix set (the result of running
+     * the caller's explicit grants through `coalescePrefixes`). Prefixes are
+     * hq-root-relative (e.g. `companies/indigo/meetings/`).
+     */
+    prospectivePrefixSet: readonly string[];
+    /**
+     * Active per-company journal. Hash + mtime comparisons key off
+     * `journal.files[relPath]`.
+     */
+    journal: SyncJournal;
+}
+/**
+ * Build a NarrowPlan by walking `<hqRoot>/companies/<slug>/` and classifying
+ * each regular file against `prospectivePrefixSet` + `journal`.
+ *
+ * Walk semantics:
+ *   - Recursive `fs.readdirSync(... withFileTypes)`.
+ *   - Symlinks are RECORDED but never followed (`lstat`, not `stat`), matching
+ *     the `share()`/sync engine's contract.
+ *   - Hidden files + `.DS_Store` + `node_modules` are walked as-is — the
+ *     caller is expected to point this at HQ content, where `.hqignore`
+ *     filtering happens upstream of the journal. The journal already
+ *     reflects what's been pushed/pulled, so `not-in-journal` is the
+ *     classifier signal for "we didn't put this here".
+ *   - If the walk root is missing entirely, returns an empty plan (rather
+ *     than throwing) — a freshly-flipped membership may not have synced any
+ *     files yet.
+ */
+export declare function buildNarrowPlan(input: BuildNarrowPlanInput): NarrowPlan;
+/**
+ * Render the dry-run summary as plain text (no chalk — keep it pure). The
+ * CLI wrapper can colorize lines afterwards if desired.
+ */
+export declare function formatNarrowPlanSummary(plan: NarrowPlan): string;
+/** Human-readable byte counts with a fixed unit ladder. */
+export declare function formatBytes(n: number): string;
+//# sourceMappingURL=local-tree-diff.d.ts.map