@indigoai-us/hq-cli 5.108.1 → 5.108.3

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

@@ -0,0 +1,247 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import { projectIdFromCwd } from "./company.js";
+import { normalizeTaskId } from "./contract.js";
+import { findEnclosingGitDir, normalizeRemoteOwnerName, readOriginRemoteUrl, } from "./repo-remote.js";
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function normalizeSlug(value) {
+    if (!value)
+        return undefined;
+    const s = value.trim();
+    if (!s || !SLUG_RE.test(s))
+        return undefined;
+    return s;
+}
+/**
+ * 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 function readMetaProjectTask(sessionId, hqRoot) {
+    if (!hqRoot || !sessionId)
+        return {};
+    const metaPath = path.join(hqRoot, "workspace", "sessions", sessionId, "meta.yaml");
+    if (!fs.existsSync(metaPath))
+        return {};
+    try {
+        const text = fs.readFileSync(metaPath, "utf8");
+        let projectId;
+        let taskId;
+        for (const line of text.split(/\r?\n/)) {
+            const proj = /^\s*(?:project|project_id|projectId)\s*:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/.exec(line);
+            if (proj?.[1] && !projectId)
+                projectId = normalizeSlug(proj[1]);
+            const task = /^\s*(?:task|task_id|taskId|story_id|storyId)\s*:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/.exec(line);
+            if (task?.[1] && !taskId)
+                taskId = normalizeSlug(task[1]);
+        }
+        return {
+            ...(projectId ? { projectId } : {}),
+            ...(taskId ? { taskId } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 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 function projectIdFromRepoRegistry(input) {
+    const hqRoot = input.hqRoot?.trim()
+        ? path.resolve(input.hqRoot)
+        : undefined;
+    const companySlug = normalizeSlug(input.companySlug);
+    if (!hqRoot || !companySlug || !input.cwd)
+        return null;
+    const gitDir = findEnclosingGitDir(path.resolve(input.cwd));
+    if (!gitDir)
+        return null;
+    const origin = readOriginRemoteUrl(gitDir);
+    if (!origin)
+        return null;
+    const ownerName = normalizeRemoteOwnerName(origin);
+    if (!ownerName)
+        return null;
+    const target = ownerName.toLowerCase();
+    const resourcesDir = path.join(hqRoot, "companies", companySlug, "registry", "resources");
+    if (!fs.existsSync(resourcesDir))
+        return null;
+    const matches = new Set();
+    let entries;
+    try {
+        entries = fs.readdirSync(resourcesDir);
+    }
+    catch {
+        return null;
+    }
+    for (const name of entries) {
+        if (!name.endsWith(".yaml") && !name.endsWith(".yml"))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(resourcesDir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        // Must be a repo resource.
+        if (!/^\s*type:\s*repo\s*$/m.test(text))
+            continue;
+        // Extract repo_url / url and compare.
+        const urlMatch = /^\s*(?:repo_url|url)\s*:\s*["']?([^"'\s]+)["']?\s*$/m.exec(text);
+        if (!urlMatch?.[1])
+            continue;
+        const candidate = normalizeRemoteOwnerName(urlMatch[1]);
+        if (!candidate || candidate.toLowerCase() !== target)
+            continue;
+        const projMatch = /^\s*project\s*:\s*["']?([A-Za-z0-9._-]+)["']?\s*$/m.exec(text);
+        if (projMatch?.[1]) {
+            const p = normalizeSlug(projMatch[1]);
+            if (p)
+                matches.add(p);
+        }
+    }
+    if (matches.size === 1)
+        return [...matches][0];
+    return null;
+}
+/**
+ * Resolve project and task. Never invents an adhoc target. Soft evidence is
+ * out of scope here (server candidates only).
+ */
+export function resolveProjectTask(input) {
+    const env = input.env ?? process.env;
+    const state = input.existingState ?? null;
+    // 1. Existing active binding.
+    if (state) {
+        const boundStatuses = new Set(["bound", "needs_task", "needs_project"]);
+        if (boundStatuses.has(state.contextStatus) &&
+            state.projectId &&
+            state.contextStatus === "bound") {
+            return {
+                projectId: state.projectId,
+                taskId: state.taskId,
+                source: "existing_binding",
+                complete: Boolean(state.projectId && state.taskId),
+            };
+        }
+        // needs_task with project already accepted — keep project, fill task from
+        // higher-precedence sources below only when absent.
+        if ((state.contextStatus === "needs_task" ||
+            state.contextStatus === "bound") &&
+            state.projectId &&
+            state.taskId) {
+            return {
+                projectId: state.projectId,
+                taskId: state.taskId,
+                source: "existing_binding",
+                complete: true,
+            };
+        }
+    }
+    // 2. Trusted explicit: env + observation + meta.yaml.
+    const spawnProject = normalizeSlug(env.HQ_SPAWN_PROJECT);
+    const spawnTask = normalizeSlug(env.HQ_SPAWN_TASK);
+    const trustedProject = normalizeSlug(input.trusted?.projectId ?? spawnProject);
+    let trustedTask = spawnTask;
+    if (input.trusted?.taskId || input.trusted?.storyId) {
+        const norm = normalizeTaskId({
+            taskId: input.trusted.taskId,
+            storyId: input.trusted.storyId,
+        });
+        if (norm.ok)
+            trustedTask = norm.taskId;
+    }
+    else if (spawnTask) {
+        trustedTask = spawnTask;
+    }
+    const meta = input.metaProjectId !== undefined || input.metaTaskId !== undefined
+        ? {
+            projectId: normalizeSlug(input.metaProjectId) ?? undefined,
+            taskId: normalizeSlug(input.metaTaskId) ?? undefined,
+        }
+        : readMetaProjectTask(input.sessionId, input.hqRoot);
+    const explicitProject = trustedProject ?? meta.projectId;
+    const explicitTask = trustedTask ?? meta.taskId;
+    if (explicitProject || explicitTask) {
+        // Prefer spawn/trusted over meta; already merged above.
+        if (explicitProject) {
+            return {
+                projectId: explicitProject,
+                taskId: explicitTask,
+                source: "trusted_explicit",
+                complete: Boolean(explicitProject && explicitTask),
+            };
+        }
+    }
+    // Preserve existing project from needs_task without task (not a full bind).
+    if (state?.projectId && state.contextStatus === "needs_task") {
+        return {
+            projectId: state.projectId,
+            taskId: state.taskId,
+            source: "existing_binding",
+            complete: Boolean(state.taskId),
+        };
+    }
+    // 3. Exactly one deterministic mapping.
+    const fromCwd = projectIdFromCwd(input.cwd, input.hqRoot);
+    if (fromCwd) {
+        return {
+            projectId: fromCwd,
+            source: "deterministic_cwd",
+            complete: false,
+        };
+    }
+    const fromRegistry = input.registryProjectId !== undefined
+        ? normalizeSlug(input.registryProjectId) ?? null
+        : projectIdFromRepoRegistry({
+            cwd: input.cwd,
+            hqRoot: input.hqRoot,
+            companySlug: state?.companySlug ??
+                input.trusted?.companySlug ??
+                normalizeSlug(env.HQ_SPAWN_COMPANY),
+        });
+    if (fromRegistry) {
+        return {
+            projectId: fromRegistry,
+            source: "deterministic_registry",
+            complete: false,
+        };
+    }
+    return null;
+}
+/** Work-signal thresholds for one-time clarification (US-007B). */
+export const TOOL_WRITES_ASK_THRESHOLD = 3;
+export const SESSION_AGE_ASK_MS = 10 * 60 * 1000;
+/**
+ * Whether the session has crossed the work-signal threshold that unlocks a
+ * one-time clarification. Soft — never auto-binds.
+ */
+export function shouldAskAfter(input) {
+    const writes = input.toolWrites ?? 0;
+    if (writes >= TOOL_WRITES_ASK_THRESHOLD)
+        return true;
+    if (!input.hasTurn || !input.startedAt)
+        return false;
+    const startMs = Date.parse(input.startedAt);
+    if (!Number.isFinite(startMs))
+        return false;
+    const now = input.now ?? new Date();
+    return now.getTime() - startMs >= SESSION_AGE_ASK_MS;
+}
+//# sourceMappingURL=project.js.map

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

@@ -0,0 +1,85 @@
+/**
+ * hq mesh context reconcile — sole runtime-to-control-plane entrypoint
+ * (US-007A company gate + US-007B project/task organization).
+ */
+import type { MembershipValidationResult } from "./config.js";
+import { type ContextResult, type TrustedExplicitContext } from "./contract.js";
+import { type FetchCandidatesFn } from "./organize.js";
+import { replayOutbox, type DeliverFn } from "./outbox.js";
+export interface ReconcileObservation {
+    contractVersion: number;
+    identity: {
+        sessionId?: string;
+        providerSessionId?: string;
+        harness?: string;
+        adapterVersion?: string;
+        runtimeVersion?: string;
+    };
+    clientOperationId: string;
+    explicit?: TrustedExplicitContext & {
+        companySlug?: string;
+    };
+    /** Alias for explicit (dispatch envelope). */
+    trustedContext?: TrustedExplicitContext & {
+        companySlug?: string;
+    };
+    untrackedOrigin?: "user";
+    /** Structured untracked choice; only origin "user" is accepted. */
+    untracked?: {
+        origin: string;
+    };
+    /** Local-only evidence — never written to outbox/state beyond structured ids. */
+    cwd?: string;
+    hqRoot?: string;
+    remoteOwnerSlug?: string;
+    /**
+     * How the observation was produced. Transcript-watch sets "transcript"
+     * so durable state carries source + transcriptMarker (US-018).
+     */
+    source?: "hooks" | "transcript";
+    /** Optional turn signal for the 10-minute ask threshold (US-007B). */
+    hasTurn?: boolean;
+    toolWrites?: number;
+    /** Prohibited content may appear on the wire-in observation; must be stripped. */
+    prompt?: unknown;
+    transcript?: unknown;
+    message?: unknown;
+    token?: unknown;
+    credentials?: unknown;
+    [key: string]: unknown;
+}
+export interface ReconcileDeps {
+    root: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    /** Network deliverer; only called after outbox write. */
+    deliver?: DeliverFn;
+    /** Skip network even when company is resolved (local unit tests). */
+    offline?: boolean;
+    /** Server candidates fetcher (US-007B); ranking is server-owned. */
+    fetchCandidates?: FetchCandidatesFn;
+    /** Observation may mark that a turn occurred (for 10-minute ask threshold). */
+    markTurn?: boolean;
+    /**
+     * Membership-validated slug→uid (GET /membership/me). Required to attach a
+     * companyUid when local resolution only yielded a slug. Injectable for tests.
+     */
+    validateMembership?: (slug: string) => Promise<MembershipValidationResult> | MembershipValidationResult;
+}
+export interface ReconcileOutcome {
+    result: ContextResult;
+    exitCode: number;
+    /** Diagnostics for stderr (no secrets). */
+    diagnostics: string[];
+    statePath?: string;
+    outboxOperationId?: string;
+}
+export declare function parseObservationJson(raw: string): ReconcileObservation;
+export declare function loadObservationFromFile(filePath: string): ReconcileObservation;
+/**
+ * Mark a session untracked (user origin only). Local receipt; no server write.
+ */
+export declare function markUntracked(sessionId: string, deps: Pick<ReconcileDeps, "root" | "now">, clientOperationId?: string): ReconcileOutcome;
+export declare function reconcileObservation(obs: ReconcileObservation, deps: ReconcileDeps): Promise<ReconcileOutcome>;
+export { replayOutbox };
+//# sourceMappingURL=reconcile.d.ts.map