@indigoai-us/hq-cli 5.108.0 → 5.108.2

package/dist/lib/work-context/outbox.js

@@ -0,0 +1,357 @@
+/**
+ * Metadata-only durable outbox under ~/.hq/work-context/outbox/<operationId>.json.
+ * Written before any network I/O. FIFO per session; bounded-parallel across sessions.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+import { atomicWriteJson, ensureOwnerDir } from "./atomic.js";
+import { NotTrackingError } from "./errors.js";
+import { isSafeWorkContextSegment, workContextOutboxDir, workContextOutboxPath, } from "./paths.js";
+/** Fields allowed on a durable outbox operation (privacy allowlist). */
+export const OUTBOX_ALLOWLIST = [
+    "contractVersion",
+    "operationId",
+    "clientOperationId",
+    "sessionId",
+    "companyUid",
+    "companySlug",
+    "projectId",
+    "taskId",
+    "kind",
+    "digest",
+    "delivery",
+    "createdAt",
+    "updatedAt",
+    "attemptCount",
+    "lastErrorCode",
+    "receiptId",
+    "destinationCompanyUid",
+    "destinationCompanySlug",
+];
+const DEFAULT_PARALLEL = 4;
+export function stableOperationId(clientOperationId, sessionId) {
+    const h = crypto
+        .createHash("sha256")
+        .update(`v1:${sessionId}:${clientOperationId}`)
+        .digest("hex")
+        .slice(0, 32);
+    return `op_${h}`;
+}
+export function digestOperation(parts) {
+    const canonical = JSON.stringify({
+        v: 1,
+        sessionId: parts.sessionId,
+        clientOperationId: parts.clientOperationId,
+        companyUid: parts.companyUid ?? null,
+        companySlug: parts.companySlug ?? null,
+        projectId: parts.projectId ?? null,
+        taskId: parts.taskId ?? null,
+        kind: parts.kind,
+        destinationCompanyUid: parts.destinationCompanyUid ?? null,
+        destinationCompanySlug: parts.destinationCompanySlug ?? null,
+    });
+    return crypto.createHash("sha256").update(canonical).digest("hex");
+}
+function projectOutbox(op) {
+    const out = {
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        operationId: op.operationId,
+        clientOperationId: op.clientOperationId,
+        sessionId: op.sessionId,
+        kind: op.kind,
+        digest: op.digest,
+        delivery: op.delivery,
+        createdAt: op.createdAt,
+        updatedAt: op.updatedAt,
+        attemptCount: op.attemptCount,
+    };
+    if (op.companyUid)
+        out.companyUid = op.companyUid;
+    if (op.companySlug)
+        out.companySlug = op.companySlug;
+    if (op.projectId)
+        out.projectId = op.projectId;
+    if (op.taskId)
+        out.taskId = op.taskId;
+    if (op.lastErrorCode)
+        out.lastErrorCode = op.lastErrorCode;
+    if (op.receiptId)
+        out.receiptId = op.receiptId;
+    if (op.destinationCompanyUid) {
+        out.destinationCompanyUid = op.destinationCompanyUid;
+    }
+    if (op.destinationCompanySlug) {
+        out.destinationCompanySlug = op.destinationCompanySlug;
+    }
+    return out;
+}
+/**
+ * Atomically enqueue (or idempotently return) an outbox operation.
+ * Disk/permission/lock failure → NotTrackingError (no network-only send).
+ */
+export function enqueueOutbox(input, root) {
+    if (!isSafeWorkContextSegment(input.sessionId)) {
+        throw new NotTrackingError(`Unsafe session id: ${input.sessionId}`);
+    }
+    if (!isSafeWorkContextSegment(input.clientOperationId) &&
+        !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(input.clientOperationId)) {
+        throw new NotTrackingError(`Unsafe clientOperationId: ${input.clientOperationId}`);
+    }
+    const kind = input.kind ?? "register";
+    const operationId = stableOperationId(input.clientOperationId, input.sessionId);
+    if (!isSafeWorkContextSegment(operationId)) {
+        throw new NotTrackingError(`Unsafe operationId: ${operationId}`);
+    }
+    const digest = digestOperation({
+        sessionId: input.sessionId,
+        clientOperationId: input.clientOperationId,
+        companyUid: input.companyUid,
+        companySlug: input.companySlug,
+        projectId: input.projectId,
+        taskId: input.taskId,
+        kind,
+        destinationCompanyUid: input.destinationCompanyUid,
+        destinationCompanySlug: input.destinationCompanySlug,
+    });
+    const now = (input.now ?? (() => new Date()))().toISOString();
+    const existing = readOutboxOperation(operationId, root);
+    if (existing) {
+        if (existing.digest !== digest) {
+            throw new NotTrackingError(`Idempotency conflict for ${operationId}`, "IdempotencyConflictError");
+        }
+        return existing;
+    }
+    const op = projectOutbox({
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        operationId,
+        clientOperationId: input.clientOperationId,
+        sessionId: input.sessionId,
+        companyUid: input.companyUid,
+        companySlug: input.companySlug,
+        projectId: input.projectId,
+        taskId: input.taskId,
+        kind,
+        digest,
+        delivery: "queued",
+        createdAt: now,
+        updatedAt: now,
+        attemptCount: 0,
+        destinationCompanyUid: input.destinationCompanyUid,
+        destinationCompanySlug: input.destinationCompanySlug,
+    });
+    try {
+        ensureOwnerDir(workContextOutboxDir(root));
+        // Exclusive publish: linkSync fails with EEXIST if dest appeared (rename
+        // would clobber a conflicting digest from a concurrent writer).
+        const dest = workContextOutboxPath(operationId, root);
+        const tmp = `${dest}.tmp.${process.pid}.${Date.now()}`;
+        fs.writeFileSync(tmp, `${JSON.stringify(op, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        try {
+            fs.linkSync(tmp, dest);
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        catch (linkErr) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* ignore */
+            }
+            const code = linkErr?.code;
+            if (code === "EEXIST") {
+                const raced = readOutboxOperation(operationId, root);
+                if (raced) {
+                    if (raced.digest !== digest) {
+                        throw new NotTrackingError(`Idempotency conflict for ${operationId}`, "IdempotencyConflictError");
+                    }
+                    return raced;
+                }
+            }
+            throw linkErr;
+        }
+        try {
+            fs.chmodSync(dest, 0o600);
+        }
+        catch {
+            /* ignore */
+        }
+        return op;
+    }
+    catch (err) {
+        if (err instanceof NotTrackingError)
+            throw err;
+        throw new NotTrackingError(`Outbox persistence failed: ${err instanceof Error ? err.message : String(err)}`, "OutboxPersistenceError");
+    }
+}
+export function readOutboxOperation(operationId, root) {
+    if (!isSafeWorkContextSegment(operationId))
+        return null;
+    const filePath = workContextOutboxPath(operationId, root);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function updateOutboxOperation(op, root) {
+    atomicWriteJson(workContextOutboxPath(op.operationId, root), projectOutbox(op));
+}
+export function markOutboxAcked(operationId, root, receiptId, now = () => new Date()) {
+    const op = readOutboxOperation(operationId, root);
+    if (!op)
+        return null;
+    op.delivery = "acked";
+    op.receiptId = receiptId;
+    op.updatedAt = now().toISOString();
+    updateOutboxOperation(op, root);
+    return op;
+}
+export function markOutboxQueued(operationId, root, errorCode, now = () => new Date()) {
+    const op = readOutboxOperation(operationId, root);
+    if (!op)
+        return null;
+    op.delivery = "queued";
+    op.lastErrorCode = errorCode;
+    op.attemptCount += 1;
+    op.updatedAt = now().toISOString();
+    updateOutboxOperation(op, root);
+    return op;
+}
+export function markOutboxQuarantined(operationId, root, errorCode, now = () => new Date()) {
+    const op = readOutboxOperation(operationId, root);
+    if (!op)
+        return null;
+    op.delivery = "quarantined";
+    op.lastErrorCode = errorCode;
+    op.attemptCount += 1;
+    op.updatedAt = now().toISOString();
+    updateOutboxOperation(op, root);
+    return op;
+}
+export function listOutboxOperations(root) {
+    const dir = workContextOutboxDir(root);
+    if (!fs.existsSync(dir))
+        return [];
+    const ops = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json") || name.startsWith("."))
+            continue;
+        const op = readOutboxOperation(name.replace(/\.json$/, ""), root);
+        if (op)
+            ops.push(op);
+    }
+    return ops.sort((a, b) => {
+        const byTime = a.createdAt.localeCompare(b.createdAt);
+        if (byTime !== 0)
+            return byTime;
+        return a.clientOperationId.localeCompare(b.clientOperationId);
+    });
+}
+export function outboxStats(root) {
+    const ops = listOutboxOperations(root);
+    return {
+        depth: ops.filter((o) => o.delivery === "queued").length,
+        quarantined: ops.filter((o) => o.delivery === "quarantined").length,
+        queued: ops.filter((o) => o.delivery === "queued").length,
+        acked: ops.filter((o) => o.delivery === "acked").length,
+    };
+}
+/**
+ * Replay queued (and recover lost-receipt) operations.
+ * FIFO per sessionId; bounded parallelism across sessions.
+ */
+export async function replayOutbox(root, deliver, opts = {}) {
+    const parallel = opts.parallel ?? DEFAULT_PARALLEL;
+    const now = opts.now ?? (() => new Date());
+    const pending = listOutboxOperations(root).filter((o) => o.delivery === "queued" || (o.delivery === "acked" && !o.receiptId));
+    // Group by session, preserve FIFO within each.
+    const bySession = new Map();
+    for (const op of pending) {
+        const list = bySession.get(op.sessionId) ?? [];
+        list.push(op);
+        bySession.set(op.sessionId, list);
+    }
+    let delivered = 0;
+    let queued = 0;
+    let quarantined = 0;
+    const sessions = [...bySession.keys()];
+    let cursor = 0;
+    async function runSession(sessionId) {
+        const ops = bySession.get(sessionId) ?? [];
+        for (const op of ops) {
+            // Lost-receipt recovery: if already acked with receipt, skip; if acked
+            // without receiptId, re-deliver via same operationId (idempotent server).
+            const result = await deliver(op);
+            if (result.ok) {
+                markOutboxAcked(op.operationId, root, result.receiptId, now);
+                delivered += 1;
+            }
+            else if (result.retryable) {
+                markOutboxQueued(op.operationId, root, result.code, now);
+                queued += 1;
+                // Stop this session's FIFO on transient failure.
+                break;
+            }
+            else {
+                markOutboxQuarantined(op.operationId, root, result.code, now);
+                quarantined += 1;
+                break;
+            }
+        }
+    }
+    async function worker() {
+        while (cursor < sessions.length) {
+            const idx = cursor;
+            cursor += 1;
+            const sid = sessions[idx];
+            if (sid)
+                await runSession(sid);
+        }
+    }
+    const workers = Array.from({ length: Math.min(parallel, sessions.length) }, () => worker());
+    await Promise.all(workers);
+    return { delivered, queued, quarantined };
+}
+/** Remove acked ops older than retention (optional GC; not required by AC). */
+export function removeAckedOutbox(root, olderThanMs, now = Date.now()) {
+    let removed = 0;
+    for (const op of listOutboxOperations(root)) {
+        if (op.delivery !== "acked" || !op.receiptId)
+            continue;
+        const age = now - Date.parse(op.updatedAt);
+        if (Number.isFinite(age) && age > olderThanMs) {
+            try {
+                fs.unlinkSync(workContextOutboxPath(op.operationId, root));
+                removed += 1;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return removed;
+}
+export function outboxFileExists(operationId, root) {
+    return fs.existsSync(workContextOutboxPath(operationId, root));
+}
+export function quarantineCorruptOutboxFile(filePath, root) {
+    const base = path.basename(filePath);
+    const dest = path.join(workContextOutboxDir(root), `.quarantine.${base}`);
+    try {
+        fs.renameSync(filePath, dest);
+    }
+    catch {
+        /* ignore */
+    }
+}
+//# sourceMappingURL=outbox.js.map

package/dist/lib/work-context/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Local Work Context paths under ~/.hq/work-context/.
+ * All roots are injectable for tests (never touch the real HOME in unit tests).
+ */
+export declare const WORK_CONTEXT_DIRNAME = "work-context";
+export declare function workContextRoot(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function workContextConfigPath(root?: string): string;
+export declare function workContextSessionsDir(root?: string): string;
+export declare function workContextSessionPath(sessionId: string, root?: string): string;
+export declare function workContextOutboxDir(root?: string): string;
+export declare function workContextOutboxPath(operationId: string, root?: string): string;
+/** Safe path segment for session/operation ids (no traversal). */
+export declare function isSafeWorkContextSegment(value: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/work-context/paths.js

@@ -0,0 +1,39 @@
+/**
+ * Local Work Context paths under ~/.hq/work-context/.
+ * All roots are injectable for tests (never touch the real HOME in unit tests).
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+export const WORK_CONTEXT_DIRNAME = "work-context";
+export function workContextRoot(home = os.homedir(), env = process.env) {
+    const override = env.HQ_WORK_CONTEXT_ROOT?.trim();
+    if (override)
+        return override;
+    return path.join(home, ".hq", WORK_CONTEXT_DIRNAME);
+}
+export function workContextConfigPath(root) {
+    return path.join(root ?? workContextRoot(), "config.json");
+}
+export function workContextSessionsDir(root) {
+    return path.join(root ?? workContextRoot(), "sessions");
+}
+export function workContextSessionPath(sessionId, root) {
+    return path.join(workContextSessionsDir(root), `${sessionId}.json`);
+}
+export function workContextOutboxDir(root) {
+    return path.join(root ?? workContextRoot(), "outbox");
+}
+export function workContextOutboxPath(operationId, root) {
+    return path.join(workContextOutboxDir(root), `${operationId}.json`);
+}
+/** Safe path segment for session/operation ids (no traversal). */
+export function isSafeWorkContextSegment(value) {
+    const trimmed = value.trim();
+    return Boolean(trimmed &&
+        trimmed.length <= 128 &&
+        !trimmed.includes("..") &&
+        !trimmed.includes("/") &&
+        !trimmed.includes("\\") &&
+        /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed));
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/work-context/project.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Project/task resolution for work-context (US-007B).
+ *
+ * Order:
+ *   1. existing active binding (state bound / needs_task with projectId)
+ *   2. trusted explicit (HQ_SPAWN_PROJECT/HQ_SPAWN_TASK, observation, meta.yaml)
+ *   3. exactly one deterministic mapping (cwd under companies/{slug}/projects/{project}/
+ *      or a registry resource that names exactly one project for the repo)
+ * Soft evidence never auto-binds — candidates are server-owned (GET .../candidates).
+ */
+import { type TrustedExplicitContext } from "./contract.js";
+import type { SessionStateFile } from "./state.js";
+export type ProjectResolutionSource = "existing_binding" | "trusted_explicit" | "deterministic_cwd" | "deterministic_registry";
+export interface ResolvedProjectTask {
+    projectId?: string;
+    taskId?: string;
+    source: ProjectResolutionSource;
+    /** True when project+task are both present (trusted or existing bound). */
+    complete: boolean;
+}
+export interface ProjectResolveInput {
+    sessionId: string;
+    env?: NodeJS.ProcessEnv;
+    trusted?: TrustedExplicitContext & {
+        companySlug?: string;
+        projectId?: string;
+        taskId?: string;
+        storyId?: string;
+    };
+    cwd?: string;
+    hqRoot?: string;
+    existingState?: SessionStateFile | null;
+    /** Injectable meta project/task (tests). */
+    metaProjectId?: string | null;
+    metaTaskId?: string | null;
+    /** Injectable registry project id (tests). */
+    registryProjectId?: string | null;
+}
+/**
+ * Read project / task from workspace/sessions/<sid>/meta.yaml (best-effort).
+ * Keys written by startwork, execute-task, run-project, plan, brainstorm:
+ *   project | project_id | projectId
+ *   task | task_id | taskId | story_id | storyId
+ */
+export declare function readMetaProjectTask(sessionId: string, hqRoot: string | undefined): {
+    projectId?: string;
+    taskId?: string;
+};
+/**
+ * Look up a company registry resource that names exactly one project for the
+ * enclosing git remote. Scans companies/{slug}/registry/resources/*.yaml for
+ * type: repo entries whose repo_url matches and that carry a `project:` field.
+ * Zero or multiple distinct projects → null (never guess).
+ */
+export declare function projectIdFromRepoRegistry(input: {
+    cwd?: string;
+    hqRoot?: string;
+    companySlug?: string;
+}): string | null;
+/**
+ * Resolve project and task. Never invents an adhoc target. Soft evidence is
+ * out of scope here (server candidates only).
+ */
+export declare function resolveProjectTask(input: ProjectResolveInput): ResolvedProjectTask | null;
+/** Work-signal thresholds for one-time clarification (US-007B). */
+export declare const TOOL_WRITES_ASK_THRESHOLD = 3;
+export declare const SESSION_AGE_ASK_MS: number;
+/**
+ * Whether the session has crossed the work-signal threshold that unlocks a
+ * one-time clarification. Soft — never auto-binds.
+ */
+export declare function shouldAskAfter(input: {
+    toolWrites?: number;
+    startedAt?: string;
+    hasTurn?: boolean;
+    now?: Date;
+}): boolean;
+//# sourceMappingURL=project.d.ts.map