@indigoai-us/hq-cli 5.17.0 → 5.18.0

package/dist/lib/local-tree-diff.js

@@ -0,0 +1,244 @@
+/**
+ * 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).
+ */
+
+!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]="77563dec-63f2-52df-9138-c88bfd1600b9")}catch(e){}}();
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { hashFile, isCoveredByAny, } from "@indigoai-us/hq-cloud";
+// ── Pure entry point ────────────────────────────────────────────────────────
+/**
+ * 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 function buildNarrowPlan(input) {
+    const { hqRoot, companySlug, prospectivePrefixSet, journal } = input;
+    const walkRoot = path.join(hqRoot, "companies", companySlug);
+    const staying = [];
+    const clean = [];
+    const dirty = [];
+    if (!fs.existsSync(walkRoot)) {
+        return emptyPlan();
+    }
+    walkLocal(walkRoot, hqRoot, (file) => {
+        if (isCoveredByAny(file.relPath, prospectivePrefixSet)) {
+            staying.push(file);
+            return;
+        }
+        const verdict = classifyAgainstJournal(file, journal);
+        if (verdict.clean) {
+            clean.push(file);
+        }
+        else {
+            dirty.push({ ...file, reason: verdict.reason });
+        }
+    });
+    return {
+        staying,
+        clean,
+        dirty,
+        totalStayingCount: staying.length,
+        totalCleanCount: clean.length,
+        totalCleanBytes: clean.reduce((sum, f) => sum + f.bytes, 0),
+        totalDirtyCount: dirty.length,
+        totalDirtyBytes: dirty.reduce((sum, f) => sum + f.bytes, 0),
+    };
+}
+// ── Internal: walk + classify ───────────────────────────────────────────────
+function emptyPlan() {
+    return {
+        staying: [],
+        clean: [],
+        dirty: [],
+        totalStayingCount: 0,
+        totalCleanCount: 0,
+        totalCleanBytes: 0,
+        totalDirtyCount: 0,
+        totalDirtyBytes: 0,
+    };
+}
+/**
+ * Recursive readdir walk yielding regular files (and dangling-target
+ * symlinks — those are recorded as files for narrow-plan purposes; the
+ * delete path uses `fs.unlinkSync` which handles symlinks correctly).
+ *
+ * Uses `lstat` rather than `stat` so a symlink's size doesn't follow the
+ * target chain (matches the share-engine convention).
+ */
+function walkLocal(dir, hqRoot, emit) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        // Permission-denied or ENOENT mid-walk — skip silently; the CLI
+        // surfaces the higher-level "company folder missing" message earlier.
+        const code = err.code;
+        if (code === "ENOENT" || code === "EACCES")
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        const absPath = path.join(dir, entry.name);
+        const relPath = path.relative(hqRoot, absPath);
+        if (entry.isSymbolicLink()) {
+            // Record the link as a file-like entry. Don't descend — narrow is
+            // about pruning files that the LOCAL tree has materialized here; a
+            // symlink to a knowledge repo is one such "file" from the
+            // walk's POV.
+            let bytes = 0;
+            try {
+                bytes = fs.lstatSync(absPath).size;
+            }
+            catch {
+                // pass — dangling link still gets emitted with size 0
+            }
+            emit({ relPath, absPath, bytes });
+            continue;
+        }
+        if (entry.isDirectory()) {
+            walkLocal(absPath, hqRoot, emit);
+            continue;
+        }
+        if (entry.isFile()) {
+            let bytes = 0;
+            try {
+                bytes = fs.lstatSync(absPath).size;
+            }
+            catch {
+                // pass
+            }
+            emit({ relPath, absPath, bytes });
+        }
+    }
+}
+/**
+ * Mirror of `scope-shrink.ts::classifyOrphan`:
+ *
+ *   clean = (entry exists AND hash(local) === entry.hash AND mtime <= syncedAt + 1s)
+ *           OR (local file missing)
+ *
+ * Differences from the implicit path:
+ *   - If there is NO journal entry at all, classify as **dirty**
+ *     (`not-in-journal`). The implicit path never sees those files (it
+ *     iterates the journal); here we walk the local tree so an
+ *     un-journaled file is a real risk — it could be an unsynced local
+ *     draft.
+ *   - We don't honor `direction: "up"` differently. For an explicit
+ *     narrow migration the user is asking "wipe everything outside the
+ *     shared scope" — push-only authorship deserves the same dirty-file
+ *     protection as pulled content (otherwise `--apply` could nuke local
+ *     drafts).
+ */
+function classifyAgainstJournal(file, journal) {
+    const entry = journal.files[file.relPath];
+    if (!entry) {
+        return { clean: false, reason: "not-in-journal" };
+    }
+    // Tombstoned entries — the file shouldn't be here at all; treat as
+    // not-in-journal for safety so `--apply` doesn't silently delete it.
+    if (entry.removedAt) {
+        return { clean: false, reason: "not-in-journal" };
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(file.absPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            // Already gone — clean (the apply path will skip ENOENT on unlink).
+            return { clean: true, reason: "stat-error" };
+        }
+        return { clean: false, reason: "stat-error" };
+    }
+    // mtime guard with 1s grace for filesystem clock jitter, matching
+    // hq-cloud `scope-shrink.ts`.
+    const syncedAtMs = Date.parse(entry.syncedAt);
+    if (!Number.isNaN(syncedAtMs) && stat.mtimeMs > syncedAtMs + 1000) {
+        return { clean: false, reason: "modified-after-sync" };
+    }
+    // Hash check — final word. Symlinks: hashFile reads contents which is
+    // wrong for symlinks (it would follow the target), so on a symlink we
+    // skip the hash check and trust mtime alone. This matches the
+    // engine's behavior in the symlink-orphan case.
+    if (stat.isSymbolicLink()) {
+        return { clean: true, reason: "stat-error" };
+    }
+    let actualHash;
+    try {
+        actualHash = hashFile(file.absPath);
+    }
+    catch {
+        return { clean: false, reason: "stat-error" };
+    }
+    if (actualHash !== entry.hash) {
+        return { clean: false, reason: "hash-mismatch" };
+    }
+    return { clean: true, reason: "stat-error" };
+}
+// ── Formatting helper (separable for tests) ────────────────────────────────
+/**
+ * Render the dry-run summary as plain text (no chalk — keep it pure). The
+ * CLI wrapper can colorize lines afterwards if desired.
+ */
+export function formatNarrowPlanSummary(plan) {
+    const lines = [];
+    lines.push("Narrow plan summary:");
+    lines.push(`  files staying:  ${plan.totalStayingCount}`);
+    lines.push(`  clean orphans:  ${plan.totalCleanCount} (${formatBytes(plan.totalCleanBytes)})`);
+    lines.push(`  dirty orphans:  ${plan.totalDirtyCount} (${formatBytes(plan.totalDirtyBytes)})`);
+    return lines.join("\n");
+}
+/** Human-readable byte counts with a fixed unit ladder. */
+export function formatBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "0 B";
+    if (n < 1024)
+        return `${n} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(2)} ${units[i]}`;
+}
+//# sourceMappingURL=local-tree-diff.js.map
+//# debugId=77563dec-63f2-52df-9138-c88bfd1600b9

package/dist/lib/narrow-hint-banner.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `narrow-hint-banner` (US-011) — one-time-per-session hint nudging
+ * existing all-mode owners to switch to shared-mode sync.
+ *
+ * Emitted from `hq sync pull --all` and `hq sync now` after the per-target
+ * fanout resolves each membership's sync config. Suppressed when:
+ *
+ *   - the membership is NOT on `syncMode: 'all'` (shared / custom users
+ *     have already opted in to narrowing, so there is nothing to nudge),
+ *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
+ *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
+ *     `syncNarrowHint: 'off'`,
+ *   - or the same `{companyUid, level}` pair has already been shown this
+ *     process (module-singleton dedupe; the runner imports the same module
+ *     once per `hq` invocation so a single invocation prints at most one
+ *     banner per company per level).
+ *
+ * Three escalating levels — `'hint' | 'warning' | 'strict'`. Today's
+ * default level is `'hint'`; this release ships the plumbing so a future
+ * hq-core-staging release can flip the default to `'warning'` and then
+ * `'strict'` without re-touching the call sites.
+ *
+ * - hint    → dim suggestion to stderr, never blocks.
+ * - warning → yellow note to stderr, never blocks.
+ * - strict  → red error to stderr; callers are expected to refuse to
+ *             proceed unless the operator passes `--mode-all`. The
+ *             helper itself never throws or exits — the decision lives at
+ *             the call site so tests don't have to stub `process.exit`.
+ *
+ * The level is selected by the caller (typically from the
+ * `HQ_SYNC_NARROW_HINT_LEVEL` env var). See `resolveBannerLevel` for the
+ * default-and-override ladder.
+ *
+ * TODO(hq-core-staging release N+2): bump default level to 'warning'.
+ * TODO(hq-core-staging release N+3): bump default level to 'strict' and
+ *   wire `--mode-all` as the only opt-out.
+ */
+export type BannerLevel = "hint" | "warning" | "strict";
+export interface BannerInput {
+    /** Company UID — used to dedupe per-process so each company emits once. */
+    companyUid: string;
+    /** Effective sync mode resolved from `getMembershipSyncConfig`. */
+    syncMode: "shared" | "all" | "custom";
+    /** Escalation level — see file header. */
+    level: BannerLevel;
+}
+export interface ShouldShowBannerOpts {
+    /**
+     * Optional hqRoot — when provided, the helper checks
+     * `<hqRoot>/.hq/config.json` for a `syncNarrowHint: 'off'` key in
+     * addition to the env override. Falsy paths skip the file check.
+     */
+    hqRoot?: string;
+    /**
+     * Test seam: override `process.env` lookup. Defaults to
+     * `process.env.HQ_SYNC_NARROW_HINT`.
+     */
+    envValue?: string | undefined;
+    /**
+     * Test seam: override `fs.readFileSync`. Defaults to `node:fs`.
+     */
+    readFile?: (p: string) => string;
+    /** Test seam: override `fs.existsSync`. */
+    existsFile?: (p: string) => boolean;
+}
+/**
+ * Decides whether a banner should be printed AT ALL — independent of
+ * dedupe and `syncMode` gating. Exposed for tests and for the strict-mode
+ * call site (which needs to know whether to refuse-to-proceed even if the
+ * banner itself is suppressed).
+ */
+export declare function shouldShowBanner(opts?: ShouldShowBannerOpts): boolean;
+/**
+ * Resolve the banner level from environment overrides. Defaults to
+ * `'hint'`. Recognized values for `HQ_SYNC_NARROW_HINT_LEVEL`:
+ * `hint`, `warning`, `strict` (case-insensitive). Unknown values fall
+ * back to the default rather than throwing — the env var is operator-
+ * facing and a typo shouldn't break a sync.
+ */
+export declare function resolveBannerLevel(envValue?: string | undefined): BannerLevel;
+/**
+ * Returns `true` when the strict-mode rollout has been opted into AND
+ * the membership in question is still on `'all'`. Call sites should
+ * refuse to proceed (exit non-zero) when this returns true and the
+ * operator hasn't passed `--mode-all`.
+ */
+export declare function isStrictRefusal(syncMode: BannerInput["syncMode"], level: BannerLevel): boolean;
+/**
+ * Emit a one-time-per-{company,level} banner. Writes to `stderr` by
+ * default; tests inject a sink. Idempotent — repeated calls with the
+ * same `{companyUid, level}` are no-ops for the lifetime of the
+ * process.
+ */
+export declare function emitNarrowHint(input: BannerInput, opts?: {
+    hqRoot?: string;
+    write?: (s: string) => void;
+    /** Test seam — overrides `shouldShowBanner` env/config lookups. */
+    showOverride?: boolean;
+}): void;
+/** Test-only helper — clears the per-process dedupe set. */
+export declare function _resetShownForTests(): void;
+//# sourceMappingURL=narrow-hint-banner.d.ts.map

package/dist/lib/narrow-hint-banner.js

@@ -0,0 +1,144 @@
+/**
+ * `narrow-hint-banner` (US-011) — one-time-per-session hint nudging
+ * existing all-mode owners to switch to shared-mode sync.
+ *
+ * Emitted from `hq sync pull --all` and `hq sync now` after the per-target
+ * fanout resolves each membership's sync config. Suppressed when:
+ *
+ *   - the membership is NOT on `syncMode: 'all'` (shared / custom users
+ *     have already opted in to narrowing, so there is nothing to nudge),
+ *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
+ *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
+ *     `syncNarrowHint: 'off'`,
+ *   - or the same `{companyUid, level}` pair has already been shown this
+ *     process (module-singleton dedupe; the runner imports the same module
+ *     once per `hq` invocation so a single invocation prints at most one
+ *     banner per company per level).
+ *
+ * Three escalating levels — `'hint' | 'warning' | 'strict'`. Today's
+ * default level is `'hint'`; this release ships the plumbing so a future
+ * hq-core-staging release can flip the default to `'warning'` and then
+ * `'strict'` without re-touching the call sites.
+ *
+ * - hint    → dim suggestion to stderr, never blocks.
+ * - warning → yellow note to stderr, never blocks.
+ * - strict  → red error to stderr; callers are expected to refuse to
+ *             proceed unless the operator passes `--mode-all`. The
+ *             helper itself never throws or exits — the decision lives at
+ *             the call site so tests don't have to stub `process.exit`.
+ *
+ * The level is selected by the caller (typically from the
+ * `HQ_SYNC_NARROW_HINT_LEVEL` env var). See `resolveBannerLevel` for the
+ * default-and-override ladder.
+ *
+ * TODO(hq-core-staging release N+2): bump default level to 'warning'.
+ * TODO(hq-core-staging release N+3): bump default level to 'strict' and
+ *   wire `--mode-all` as the only opt-out.
+ */
+
+!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]="b62d5114-da5b-5a77-bf3f-8362a2197665")}catch(e){}}();
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const SHOWN = new Set();
+/**
+ * Decides whether a banner should be printed AT ALL — independent of
+ * dedupe and `syncMode` gating. Exposed for tests and for the strict-mode
+ * call site (which needs to know whether to refuse-to-proceed even if the
+ * banner itself is suppressed).
+ */
+export function shouldShowBanner(opts = {}) {
+    const envValue = opts.envValue !== undefined
+        ? opts.envValue
+        : process.env.HQ_SYNC_NARROW_HINT;
+    if (typeof envValue === "string" && envValue.toLowerCase() === "off") {
+        return false;
+    }
+    if (opts.hqRoot) {
+        const configPath = path.join(opts.hqRoot, ".hq", "config.json");
+        const exists = opts.existsFile ?? fs.existsSync;
+        const read = opts.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+        if (exists(configPath)) {
+            try {
+                const cfg = JSON.parse(read(configPath));
+                if (typeof cfg.syncNarrowHint === "string" &&
+                    cfg.syncNarrowHint.toLowerCase() === "off") {
+                    return false;
+                }
+            }
+            catch {
+                // Malformed config is best-effort — fall through and assume "on".
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Resolve the banner level from environment overrides. Defaults to
+ * `'hint'`. Recognized values for `HQ_SYNC_NARROW_HINT_LEVEL`:
+ * `hint`, `warning`, `strict` (case-insensitive). Unknown values fall
+ * back to the default rather than throwing — the env var is operator-
+ * facing and a typo shouldn't break a sync.
+ */
+export function resolveBannerLevel(envValue = process.env.HQ_SYNC_NARROW_HINT_LEVEL) {
+    if (typeof envValue !== "string")
+        return "hint";
+    const v = envValue.toLowerCase();
+    if (v === "warning" || v === "strict" || v === "hint")
+        return v;
+    return "hint";
+}
+/**
+ * Returns `true` when the strict-mode rollout has been opted into AND
+ * the membership in question is still on `'all'`. Call sites should
+ * refuse to proceed (exit non-zero) when this returns true and the
+ * operator hasn't passed `--mode-all`.
+ */
+export function isStrictRefusal(syncMode, level) {
+    return level === "strict" && syncMode === "all";
+}
+/**
+ * Emit a one-time-per-{company,level} banner. Writes to `stderr` by
+ * default; tests inject a sink. Idempotent — repeated calls with the
+ * same `{companyUid, level}` are no-ops for the lifetime of the
+ * process.
+ */
+export function emitNarrowHint(input, opts = {}) {
+    // Only nudge 'all'-mode memberships — shared/custom callers already
+    // opted in to narrowing, so the hint would just be noise.
+    if (input.syncMode !== "all")
+        return;
+    const show = opts.showOverride !== undefined
+        ? opts.showOverride
+        : shouldShowBanner({ ...(opts.hqRoot ? { hqRoot: opts.hqRoot } : {}) });
+    if (!show)
+        return;
+    const key = `${input.companyUid}:${input.level}`;
+    if (SHOWN.has(key))
+        return;
+    SHOWN.add(key);
+    const write = opts.write ?? ((s) => process.stderr.write(s + "\n"));
+    if (input.level === "hint") {
+        write(chalk.dim("Tip: switch to shared-mode sync — fewer files, same visibility. " +
+            "Run `hq sync narrow --dry-run` to preview."));
+        return;
+    }
+    if (input.level === "warning") {
+        write(chalk.yellow("Warning: shared-mode sync is the new default; this membership " +
+            "still pulls everything. Run `hq sync narrow --dry-run` to " +
+            "preview the migration before the next release flips the " +
+            "default to strict."));
+        return;
+    }
+    // strict — caller is responsible for refusing to proceed unless
+    // --mode-all was passed. We only emit the message here.
+    write(chalk.red("Error: shared-mode sync is now strict; pass --mode-all to keep " +
+        "all-mode behavior for this run, or run `hq sync narrow --apply` " +
+        "to migrate this membership."));
+}
+/** Test-only helper — clears the per-process dedupe set. */
+export function _resetShownForTests() {
+    SHOWN.clear();
+}
+//# sourceMappingURL=narrow-hint-banner.js.map
+//# debugId=b62d5114-da5b-5a77-bf3f-8362a2197665

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.17.0",
+  "version": "5.18.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^5.22.0",
+    "@indigoai-us/hq-cloud": "^5.23.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",