@indigoai-us/hq-cli 5.345.54 → 5.345.55

package/dist/commands/import-scan.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `hq import` command group.
+ *
+ *   hq import scan                  human-readable scan summary
+ *   hq import scan --json           only the final `done` event (one JSON line)
+ *   hq import scan --json --stream  every scan event as JSON Lines
+ *
+ * Runs the HQ tree's import-context scanner with `--progress-json` (local
+ * only, read-only apart from report.json). The HQ tree is `--hq-root`, else
+ * the one the HQ installer recorded in ~/.hq/menubar.json; this command does
+ * not guess from the current folder or $HQ_ROOT. Event contract and types:
+ * src/lib/import-scan/events.ts and docs/import-scan-stream.md.
+ */
+import { Command, type CommanderError } from "commander";
+/** Exit code for every usage error of `hq import scan` (contract). */
+export declare const IMPORT_SCAN_USAGE_EXIT_CODE = 2;
+/** Exit code for a Commander error raised while parsing `hq import scan`. */
+export declare function importScanExitCode(err: CommanderError): number;
+export interface RegisterImportCommandDeps {
+    /** Ends the process (default process.exit). Tests pass one that throws. */
+    exit?: (code: number, err: CommanderError) => never;
+}
+export declare function registerImportCommand(program: Command, deps?: RegisterImportCommandDeps): Command;
+//# sourceMappingURL=import-scan.d.ts.map

package/dist/commands/import-scan.js

@@ -0,0 +1,75 @@
+/**
+ * `hq import` command group.
+ *
+ *   hq import scan                  human-readable scan summary
+ *   hq import scan --json           only the final `done` event (one JSON line)
+ *   hq import scan --json --stream  every scan event as JSON Lines
+ *
+ * Runs the HQ tree's import-context scanner with `--progress-json` (local
+ * only, read-only apart from report.json). The HQ tree is `--hq-root`, else
+ * the one the HQ installer recorded in ~/.hq/menubar.json; this command does
+ * not guess from the current folder or $HQ_ROOT. Event contract and types:
+ * src/lib/import-scan/events.ts and docs/import-scan-stream.md.
+ */
+import { runImportScan } from "../lib/import-scan/run.js";
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+/** Exit code for every usage error of `hq import scan` (contract). */
+export const IMPORT_SCAN_USAGE_EXIT_CODE = 2;
+/** Commander error codes that mean "the command line was wrong". */
+const COMMANDER_USAGE_ERROR_CODES = new Set([
+    "commander.unknownOption",
+    "commander.unknownCommand",
+    "commander.missingArgument",
+    "commander.optionMissingArgument",
+    "commander.missingMandatoryOptionValue",
+    "commander.conflictingOption",
+    "commander.excessArguments",
+    "commander.invalidArgument",
+]);
+/** Exit code for a Commander error raised while parsing `hq import scan`. */
+export function importScanExitCode(err) {
+    if (err.exitCode !== 0 && COMMANDER_USAGE_ERROR_CODES.has(err.code))
+        return IMPORT_SCAN_USAGE_EXIT_CODE;
+    return err.exitCode;
+}
+export function registerImportCommand(program, deps = {}) {
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const importCmd = program
+        .command("import")
+        .description("Import existing AI context (Claude Code, Codex, repos) into HQ");
+    importCmd
+        .command("scan")
+        .description("Scan this machine for AI context (sessions, repos, companies, projects); local only")
+        .option("--json", "Print only the final done event as JSON")
+        .option("--stream", "With --json, print every scan event as JSON Lines while scanning")
+        .option("--hq-root <path>", "HQ folder (default: the folder the HQ installer recorded)")
+        .option("--output <path>", "Where to write report.json (default: <hq>/workspace/imports/<scan id>/report.json)")
+        .option("--scope <dir>", "Also scan this folder (repeatable)", collect, [])
+        .option("--claude-export <path>", "Include a claude.ai data export (unzipped folder or conversations.json)")
+        .option("--no-default-scopes", "Scan only --scope folders, not the default code folders")
+        .addHelpText("after", "\nThe desktop app runs: hq import scan --json --stream\n" +
+        "Events (v1): start, source, count, company, project, error, done. See docs/import-scan-stream.md.")
+        // Usage errors (unknown option, missing value, --stream without --json)
+        // exit 2 per the scan contract. Scoped to this command only; Commander
+        // would otherwise exit 1 for most of them.
+        .exitOverride((err) => exit(importScanExitCode(err), err))
+        .action(async (opts, cmd) => {
+        if (opts.stream && !opts.json) {
+            cmd.error("error: --stream requires --json", { exitCode: 2 });
+        }
+        const mode = opts.json ? (opts.stream ? "stream" : "final") : "human";
+        const code = await runImportScan({
+            mode,
+            hqRoot: opts.hqRoot,
+            output: opts.output,
+            scopes: opts.scope,
+            claudeExport: opts.claudeExport,
+            noDefaultScopes: opts.defaultScopes === false,
+        }, { stdout: process.stdout, stderr: process.stderr });
+        process.exitCode = code;
+    });
+    return importCmd;
+}
+//# sourceMappingURL=import-scan.js.map

package/dist/commands/lanes-session-start.d.ts

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+import type { Command } from "commander";
+export interface SessionStartOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: Pick<NodeJS.WriteStream, "write">;
+    stderr?: Pick<NodeJS.WriteStream, "write">;
+    resolveRoot?: (env: NodeJS.ProcessEnv, cwd?: string) => string;
+    startSweep?: (root: string, env: NodeJS.ProcessEnv, context: SessionStartContext) => void;
+}
+interface SessionStartContext {
+    sessionId?: string;
+    companySlug?: string;
+}
+/** Starts the CL-4 read-only orphan report once per host, without holding SessionStart open. */
+export declare function startSessionStartOrphanSweep(root: string, env?: NodeJS.ProcessEnv, spawnDetached?: typeof spawn, context?: SessionStartContext): void;
+/** SessionStart-compatible, fail-open conduct bootstrap. */
+export declare function runLaneSessionStart(options?: SessionStartOptions): Promise<void>;
+export declare function registerLaneSessionStartCommand(lanes: Command): void;
+export {};
+//# sourceMappingURL=lanes-session-start.d.ts.map

package/dist/commands/lanes-session-start.js

@@ -0,0 +1,215 @@
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+import { readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
+import { LANE_CONDUCT_SESSION_START_FLAG } from "../lib/lanes/flag-keys.js";
+function enabledFromSettings(root) {
+    const personal = path.join(root, "personal", "settings", "orchestrator.yaml");
+    const settings = fs.existsSync(personal) ? personal : path.join(root, "core", "settings", "orchestrator.yaml");
+    if (!fs.existsSync(settings))
+        return false;
+    const text = fs.readFileSync(settings, "utf8");
+    const block = /^conduct:\s*(?:#.*)?\r?\n((?:[ \t]+.*\r?\n?)*)/m.exec(text)?.[1] ?? "";
+    const value = /^\s+default_enabled:\s*["']?(true|false|yes|no|on|off|1|0)["']?\s*(?:#.*)?$/mi.exec(block)?.[1]?.toLowerCase();
+    return value === "true" || value === "yes" || value === "on" || value === "1";
+}
+function sessionWasDisabled(root, env, payloadSessionId) {
+    const sessionId = payloadSessionId || env.HQ_SESSION_ID;
+    if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId))
+        return false;
+    const meta = path.join(root, "workspace", "sessions", sessionId, "meta.yaml");
+    if (!fs.existsSync(meta))
+        return false;
+    const text = fs.readFileSync(meta, "utf8");
+    return /^\s*(?:conduct_mode|conduct_enabled|conduct_default):\s*(?:off|false|no|0)\s*(?:#.*)?$/mi.test(text) ||
+        /^\s*conduct_engine:\s*(?:""|''|#.*)?\s*$/mi.test(text);
+}
+function sessionStartContext(root, env, payloadSessionId) {
+    const sessionId = payloadSessionId || env.HQ_SESSION_ID;
+    let companySlug = "";
+    if (sessionId && /^[A-Za-z0-9_-]+$/.test(sessionId)) {
+        const meta = path.join(root, "workspace", "sessions", sessionId, "meta.yaml");
+        if (fs.existsSync(meta)) {
+            const text = fs.readFileSync(meta, "utf8");
+            companySlug = /^\s*company_slug:\s*["']?([A-Za-z0-9][A-Za-z0-9-]*)["']?\s*(?:#.*)?$/mi.exec(text)?.[1] ?? "";
+        }
+    }
+    if (!companySlug)
+        companySlug = env.HQ_COMPANY_SLUG?.trim() ?? "";
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(companySlug))
+        companySlug = "";
+    return { ...(sessionId ? { sessionId } : {}), ...(companySlug ? { companySlug } : {}) };
+}
+function extractConductorBlock(core) {
+    const start = core.indexOf("<!-- inject:start -->");
+    const end = core.indexOf("<!-- inject:end -->");
+    if (start < 0 || end < 0 || end <= start)
+        return null;
+    return core.slice(start + "<!-- inject:start -->".length, end).replace(/^\r?\n/, "").replace(/\r?\n$/, "");
+}
+const ORPHAN_SWEEP_LOCK_TTL_MS = 15 * 60_000;
+/** Starts the CL-4 read-only orphan report once per host, without holding SessionStart open. */
+export function startSessionStartOrphanSweep(root, env = process.env, spawnDetached = spawn, context = {}) {
+    // The orphan command resolves company membership when --company is absent;
+    // skip here if this session has no tenant context rather than risk ambiguity.
+    if (!context.companySlug)
+        return;
+    const stateRoot = env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
+    const stateDir = path.join(stateRoot, "hq-cli");
+    const lockPath = path.join(stateDir, "lanes-session-start-orphan-sweep.json");
+    const reportDir = path.join(stateDir, "lanes-orphan-reports", context.companySlug);
+    const ownerToken = randomUUID();
+    try {
+        fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        fs.mkdirSync(reportDir, { recursive: true, mode: 0o700 });
+        let fd;
+        try {
+            fd = fs.openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return;
+            let previous = {};
+            try {
+                previous = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+            }
+            catch { /* malformed lease can be reclaimed */ }
+            const age = Date.now() - Number(previous.started_at || 0);
+            let running = false;
+            if (Number.isInteger(previous.pid) && Number(previous.pid) > 0) {
+                try {
+                    process.kill(Number(previous.pid), 0);
+                    running = true;
+                }
+                catch {
+                    running = false;
+                }
+            }
+            if (age < ORPHAN_SWEEP_LOCK_TTL_MS && running)
+                return;
+            fs.rmSync(lockPath, { force: true });
+            try {
+                fd = fs.openSync(lockPath, "wx", 0o600);
+            }
+            catch {
+                return;
+            }
+        }
+        const startedAt = Date.now();
+        fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, started_at: startedAt, owner_token: ownerToken }));
+        fs.closeSync(fd);
+        const cli = process.argv[1];
+        if (!cli) {
+            fs.rmSync(lockPath, { force: true });
+            return;
+        }
+        const wrapper = [
+            "const cp=require('node:child_process'),fs=require('node:fs'),path=require('node:path');",
+            "const [cli,lock,root,token,report,company]=process.argv.slice(1);",
+            "const cleanup=()=>{try{const lease=JSON.parse(fs.readFileSync(lock,'utf8'));if(lease.owner_token===token)fs.rmSync(lock,{force:true})}catch{}};",
+            "const start=()=>{let lease;try{lease=JSON.parse(fs.readFileSync(lock,'utf8'))}catch{}if(lease?.owner_token!==token){if(Date.now()<Number(lease?.started_at||0)+1000)return setTimeout(start,10);process.exit(0)}",
+            "try{fs.writeFileSync(lock,JSON.stringify({...lease,pid:process.pid}))}catch{}",
+            "const tmp=report+'.tmp';let output;try{output=fs.createWriteStream(tmp,{flags:'wx',mode:0o600})}catch{cleanup();process.exit(0)}",
+            "const child=cp.spawn(process.execPath,[cli,'lanes','orphans','--company',company,'--json'],{stdio:['ignore','pipe','ignore'],env:{...process.env,HQ_ROOT:root,HQ_NO_UPDATE_CHECK:'1'}});",
+            "child.stdout.pipe(output);child.on('error',()=>{output.destroy();try{fs.rmSync(tmp,{force:true})}catch{}cleanup()});",
+            "child.on('exit',(code)=>output.end(()=>{try{if(code===0)fs.renameSync(tmp,report);else fs.rmSync(tmp,{force:true})}catch{}cleanup()}));};start();",
+        ].join("");
+        const reportPath = path.join(reportDir, `orphans-${startedAt}-${ownerToken}.json`);
+        const launcher = spawnDetached(process.execPath, ["-e", wrapper, cli, lockPath, root, ownerToken, reportPath, context.companySlug], {
+            detached: true,
+            stdio: "ignore",
+            env: { ...env, HQ_ROOT: root, HQ_NO_UPDATE_CHECK: "1" },
+        });
+        if (launcher.pid) {
+            try {
+                fs.writeFileSync(lockPath, JSON.stringify({ pid: launcher.pid, started_at: startedAt, owner_token: ownerToken }));
+            }
+            catch { /* TTL lease still bounds an orphaned lock */ }
+        }
+        launcher.on("error", () => {
+            try {
+                const lease = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+                if (lease.owner_token === ownerToken)
+                    fs.rmSync(lockPath, { force: true });
+            }
+            catch { /* The lease may already have been reclaimed. */ }
+        });
+        launcher.unref();
+    }
+    catch {
+        // SessionStart's orphan report is advisory and must never block startup.
+    }
+}
+/** SessionStart-compatible, fail-open conduct bootstrap. */
+export async function runLaneSessionStart(options = {}) {
+    const env = options.env ?? process.env;
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    let debugLineWritten = false;
+    const debug = (message) => {
+        if (env.HQ_LANES_DEBUG === "1" && !debugLineWritten) {
+            debugLineWritten = true;
+            stderr.write(`${message}\n`);
+        }
+    };
+    try {
+        const chunks = [];
+        for await (const chunk of stdin)
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        const input = Buffer.concat(chunks).toString("utf8");
+        let source = "startup";
+        let payloadSessionId;
+        try {
+            const payload = JSON.parse(input);
+            source = payload.source || "startup";
+            payloadSessionId = payload.session_id;
+        }
+        catch { /* malformed hook input uses startup default */ }
+        if (source !== "startup")
+            return;
+        const disabledHooks = `,${env.HQ_DISABLED_HOOKS ?? ""},`.replace(/\s/g, "");
+        if (/(^|,)auto-conduct(,|$)/.test(disabledHooks))
+            return;
+        const root = (options.resolveRoot ?? ((e, cwd) => resolveLanesHqRoot({ env: e, cwd })))(env, options.cwd);
+        const flagEnabled = await readLanesRegistryFlagFailOpen(LANE_CONDUCT_SESSION_START_FLAG, {
+            env,
+            defaultValue: true,
+            reportFailure: (error) => {
+                const kind = error instanceof Error ? error.name : "Error";
+                debug(`hq lanes session-start: flag read failed (${kind})`);
+            },
+        });
+        if (!flagEnabled)
+            return;
+        const context = sessionStartContext(root, env, payloadSessionId);
+        (options.startSweep ?? ((r, e, c) => startSessionStartOrphanSweep(r, e, spawn, c)))(root, env, context);
+        if (sessionWasDisabled(root, env, payloadSessionId))
+            return;
+        let enabled = enabledFromSettings(root);
+        if (/^(1|true|on|yes)$/i.test(env.HQ_AUTO_CONDUCT ?? ""))
+            enabled = true;
+        else if (/^(0|false|off|no)$/i.test(env.HQ_AUTO_CONDUCT ?? ""))
+            enabled = false;
+        if (!enabled)
+            return;
+        const core = path.join(root, ".claude", "skills", "conduct", "conductor-core.md");
+        if (!fs.existsSync(core))
+            return;
+        const block = extractConductorBlock(fs.readFileSync(core, "utf8"));
+        if (block)
+            stdout.write(`${block}\n`);
+    }
+    catch {
+        debug("hq lanes session-start: bootstrap failed");
+    }
+}
+export function registerLaneSessionStartCommand(lanes) {
+    lanes.command("session-start", { hidden: true })
+        .description("Internal SessionStart bootstrap")
+        .action(async () => runLaneSessionStart());
+}
+//# sourceMappingURL=lanes-session-start.js.map

package/dist/commands/lanes-watch.d.ts

@@ -1,4 +1,6 @@
+import { type MonitorEngine } from "../lib/lanes/index.js";
 import type { Ctx, MonitorCheckOptions, LaneWaitCommandOptions, LaneWatchHandlerDeps, LaneWatchOptions } from "./lanes-shared.js";
+export declare function resolveMonitorEngine(requested: string | undefined, env: NodeJS.ProcessEnv): MonitorEngine;
 export declare function createLaneWatchHandlers(deps: LaneWatchHandlerDeps): {
     runWatch: (ctx: Ctx, laneIds: string[], opts: LaneWatchOptions) => Promise<number>;
     runMonitorCheck: (ctx: Ctx, opts: MonitorCheckOptions) => Promise<number>;

package/dist/commands/lanes-watch.js

@@ -10,8 +10,9 @@ const MONITOR_ACTIVE_LANE_STATES = new Set([
     "awaiting_input",
     "blocked",
 ]);
-function resolveMonitorEngine(requested, env) {
+export function resolveMonitorEngine(requested, env) {
     const value = requested?.trim().toLowerCase() ||
+        env.HQ_LANE_ENGINE?.trim().toLowerCase() ||
         env.HQ_CONDUCT_ENGINE?.trim().toLowerCase() ||
         "claude";
     if (!MONITOR_ENGINES.includes(value)) {

package/dist/commands/lanes.js

@@ -33,6 +33,7 @@ import { registerLaneReviewCommand } from "./lanes-review.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+import { registerLaneSessionStartCommand } from "./lanes-session-start.js";
 import { laneDepthCap } from "../lib/lanes/depth-cap.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { runResidentCommandWithPackageLease } from "../utils/resident-package-preload.js";
@@ -9234,8 +9235,9 @@ export function registerLanesCommand(parent, deps = {}) {
         timeoutPath,
     });
     const lanes = parent
-        .command("lanes", { hidden: true })
+        .command("lanes")
         .description("Create, supervise, and steer worker lanes; routed decision queue");
+    registerLaneSessionStartCommand(lanes);
     registerLaneChecksCommand(lanes, {
         hqRoot: ctx.hqRoot,
         resolveCompany: ctx.resolveCompany,
@@ -9506,7 +9508,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .command("monitor-check")
         .description("Check that active Claude senior lanes have live Monitor watch tasks")
         .option("--session <id>", "Senior session id")
-        .option("--engine <engine>", "claude | codex | grok; defaults to HQ_CONDUCT_ENGINE or claude")
+        .option("--engine <engine>", "claude | codex | grok; defaults to HQ_LANE_ENGINE (HQ_CONDUCT_ENGINE is deprecated) or claude")
         .option("--reminder", "Print the senior Monitor reminder text")
         .option("--json", "JSON on stdout")
         .action(wrapText(async (opts) => watchHandlers.runMonitorCheck(ctx, opts)));

package/dist/lib/daemon/conflict-notices.d.ts

@@ -0,0 +1,4 @@
+export declare function conflictNoticeStateDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/** Acknowledge by appending a tombstone; runner-owned notice data is read-only here. */
+export declare function acknowledgeConflictNotice(id: string, stateDir?: string, acknowledgedAt?: string): void;
+//# sourceMappingURL=conflict-notices.d.ts.map

package/dist/lib/daemon/conflict-notices.js

@@ -0,0 +1,80 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+function writeAllSync(fd, text) {
+    const bytes = Buffer.from(text);
+    let offset = 0;
+    while (offset < bytes.length) {
+        const written = fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        if (written <= 0)
+            throw new Error("Conflict acknowledgement append made no progress.");
+        offset += written;
+    }
+}
+export function conflictNoticeStateDir(env = process.env, home = os.homedir()) {
+    return env.HQ_STATE_DIR || path.join(home, ".hq");
+}
+/** Acknowledge by appending a tombstone; runner-owned notice data is read-only here. */
+export function acknowledgeConflictNotice(id, stateDir = conflictNoticeStateDir(), acknowledgedAt = new Date().toISOString()) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new Error("Invalid conflict notice id.");
+    const noticesPath = path.join(stateDir, "conflict-notices.json");
+    let notices = [];
+    try {
+        const file = JSON.parse(fs.readFileSync(noticesPath, "utf8"));
+        if (file?.schema === 1 && Array.isArray(file.notices))
+            notices = file.notices;
+        else
+            process.stderr.write("Conflict notice schema is unsupported; treating notices as empty.\n");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            process.stderr.write(`Conflict notice file could not be read; treating notices as empty (${error instanceof Error ? error.name : "UnknownError"}).\n`);
+        }
+    }
+    if (!notices.some((notice) => notice.id === id)) {
+        throw new Error("Unknown conflict notice.");
+    }
+    const ackPath = path.join(stateDir, "conflict-notice-acks.jsonl");
+    let existing = "";
+    try {
+        existing = fs.readFileSync(ackPath, "utf8");
+        let malformedLineCount = 0;
+        let alreadyAcknowledged = false;
+        for (const line of existing.split("\n")) {
+            if (!line)
+                continue;
+            try {
+                const record = JSON.parse(line);
+                if (!/^[a-f0-9]{64}$/.test(record.id) || typeof record.acknowledgedAt !== "string") {
+                    throw new Error("Invalid acknowledgement record");
+                }
+                if (record.id === id)
+                    alreadyAcknowledged = true;
+            }
+            catch {
+                malformedLineCount += 1;
+            }
+        }
+        if (malformedLineCount > 0) {
+            process.stderr.write(`Skipped ${malformedLineCount} malformed conflict acknowledgement line(s).\n`);
+        }
+        if (alreadyAcknowledged)
+            return;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const fd = fs.openSync(ackPath, "a", 0o600);
+    try {
+        const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        writeAllSync(fd, `${separator}${JSON.stringify({ id, acknowledgedAt })}\n`);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=conflict-notices.js.map

package/dist/lib/import-scan/events.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Streaming context-scan events (contract v1).
+ *
+ * `hq import scan --json --stream` relays these as JSON Lines, one object per
+ * line. They are produced by the HQ import-context scanner
+ * (`.claude/skills/import-context/scan.sh --progress-json` in an HQ tree) and
+ * validated here before they reach stdout. The HQ desktop first-run setup
+ * renders them as a knowledge tree that grows while the scan runs.
+ *
+ * The canonical contract lives next to the scanner
+ * (`.claude/skills/import-context/progress-json.md` in hq-core) and in
+ * `docs/import-scan-stream.md` in this repo. The JSON Schema is
+ * `scan-event.schema.json` in this directory (shipped next to the compiled
+ * module as `dist/lib/import-scan/scan-event.schema.json`).
+ *
+ * Desktop consumers can import these types from
+ * `@indigoai-us/hq-cli/dist/lib/import-scan/events.js` or mirror them.
+ *
+ * Versioning: within v1, fields, source ids, count keys and messages may be
+ * added. Consumers ignore unknown fields and must not parse message text.
+ * Removing or retyping a field, or adding a new `type`, `status` or `basis`
+ * value, bumps `v`.
+ */
+export declare const SCAN_EVENT_VERSION: 1;
+/** Event types, in the order a stream introduces them. */
+export declare const SCAN_EVENT_TYPES: readonly ["start", "source", "count", "company", "project", "error", "done"];
+export type ScanEventType = (typeof SCAN_EVENT_TYPES)[number];
+export declare const SCAN_SOURCE_STATUSES: readonly ["scanning", "done", "skipped", "error"];
+export type ScanSourceStatus = (typeof SCAN_SOURCE_STATUSES)[number];
+export declare const SCAN_COMPANY_BASES: readonly ["hq-company", "repo-org", "folder"];
+export type ScanCompanyBasis = (typeof SCAN_COMPANY_BASES)[number];
+export declare const SCAN_PROJECT_BASES: readonly ["repo", "claude-code-cwd", "codex-cwd"];
+export type ScanProjectBasis = (typeof SCAN_PROJECT_BASES)[number];
+/**
+ * Source ids the v1 scanner emits, in scan order. Other ids may appear in
+ * later v1 scanners; show them by their `label`.
+ */
+export declare const KNOWN_SCAN_SOURCE_IDS: readonly ["hq", "repos", "claude-code", "codex", "grok", "claude-ai", "artifacts"];
+export type KnownScanSourceId = (typeof KNOWN_SCAN_SOURCE_IDS)[number];
+/**
+ * Source id used on `error` events that hq-cli itself emits (HQ not found,
+ * scanner missing or too old, scanner crashed). Never listed in `start`.
+ */
+export declare const SCAN_CLI_ERROR_SOURCE: "scanner";
+/**
+ * Stable machine-readable codes on `error` events. hq-cli sets one on every
+ * error it emits itself (source "scanner"); scanner-emitted errors may omit it.
+ *
+ *   scanner_outdated  the HQ tree's scanner is missing or predates
+ *                     --progress-json; updating HQ fixes it
+ *   scan_failed       any other reason the scan could not run or finish
+ *                     (HQ not found, scanner crashed, cancelled, non-zero exit)
+ *
+ * Consumers branch on `code`, never on `message`. Treat an error without a
+ * code as non-fatal unless the stream ends with `report: null`.
+ */
+export declare const SCAN_ERROR_CODES: readonly ["scanner_outdated", "scan_failed"];
+export type ScanErrorCode = (typeof SCAN_ERROR_CODES)[number];
+/** Project ids: "p_" + 12 lowercase hex (pid() in scan-progress.sh). */
+export declare const SCAN_PROJECT_ID_PATTERN: RegExp;
+export interface ScanSourceInfo {
+    id: string;
+    label: string;
+}
+interface ScanEventBase {
+    v: typeof SCAN_EVENT_VERSION;
+}
+/** First line: the sources present on this machine, in scan order. */
+export interface ScanStartEvent extends ScanEventBase {
+    type: "start";
+    sources: ScanSourceInfo[];
+}
+/** Source lifecycle: `scanning` once, then one of done/skipped/error. */
+export interface ScanSourceEvent extends ScanEventBase {
+    type: "source";
+    id: string;
+    status: ScanSourceStatus;
+    /** Final counts, on `done`. Each value repeats the last `count` event for that key. */
+    counts?: Record<string, number>;
+    /** Plain-words reason, on `skipped` and `error`. */
+    message?: string;
+}
+/** Running count; fires at 1-2-5 milestones and once with the final value. */
+export interface ScanCountEvent extends ScanEventBase {
+    type: "count";
+    source: string;
+    key: string;
+    value: number;
+}
+/** A company from the deterministic rule pass. Emitted once per id. */
+export interface ScanCompanyEvent extends ScanEventBase {
+    type: "company";
+    id: string;
+    name: string;
+    basis: ScanCompanyBasis;
+}
+/**
+ * A project. Upsert by `id`: an id repeats only when a later rule pass
+ * attaches a company to a project that had `company: null`.
+ */
+export interface ScanProjectEvent extends ScanEventBase {
+    type: "project";
+    /** "p_" + 12 lowercase hex, the same for the same project on any machine. */
+    id: string;
+    /** Folder or repository basename; never contains "/". */
+    name: string;
+    company: string | null;
+    basis: ScanProjectBasis;
+}
+/** Non-fatal problem, in plain words. */
+export interface ScanErrorEvent extends ScanEventBase {
+    type: "error";
+    source: string;
+    message: string;
+    /** Stable code (SCAN_ERROR_CODES). Always set on hq-cli's own errors. */
+    code?: ScanErrorCode;
+}
+export interface ScanSummary {
+    companies: number;
+    projects: number;
+    sessions: number;
+}
+/**
+ * Last line. `report` is the absolute path of report.json, or `null` when
+ * hq-cli could not run the scan (then `summary` is all zeros and the command
+ * exits non-zero).
+ */
+export interface ScanDoneEvent extends ScanEventBase {
+    type: "done";
+    report: string | null;
+    summary: ScanSummary;
+}
+export type ScanEvent = ScanStartEvent | ScanSourceEvent | ScanCountEvent | ScanCompanyEvent | ScanProjectEvent | ScanErrorEvent | ScanDoneEvent;
+export {};
+//# sourceMappingURL=events.d.ts.map