xcoder-dna 0.0.0-stage → 1.3.0

package/dist/tools/validate-tool.js

@@ -0,0 +1,201 @@
+// xcoder:version 4 | xcoder:task task-c4a64f | xcoder:updated 2026-10-17T03:03:13.222Z | xcoder:subtask test-st-3a3927
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveInWorkspace } from "./patch-tools.js";
+import { runCommandTool } from "./shell-tool.js";
+import { detectProjectCommands } from "./project-detect.js";
+import { getOrBuildIndex } from "./workspace-index.js";
+const EXT_LANG = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".py": "python",
+    ".json": "json",
+};
+function guessLanguage(relPath) {
+    return EXT_LANG[path.extname(relPath).toLowerCase()] ?? "text";
+}
+/**
+ * Last-resort in-process TypeScript syntax check, used only when no external
+ * checker could be executed. Node's type stripper is the same parser that
+ * runs TS files natively, so it accepts every construct `node --check`
+ * rejects while still catching genuinely broken syntax (`const x = ;`).
+ */
+async function checkTypeScriptSyntax(full) {
+    let stripTypeScriptTypes;
+    try {
+        const mod = (await import("node:module"));
+        stripTypeScriptTypes = mod.stripTypeScriptTypes;
+    }
+    catch {
+        stripTypeScriptTypes = undefined;
+    }
+    // Older Node without the helper is not a validation failure.
+    if (typeof stripTypeScriptTypes !== "function")
+        return { passed: true, errors: [] };
+    try {
+        const src = await fs.readFile(full, "utf8");
+        stripTypeScriptTypes(src);
+        return { passed: true, errors: [] };
+    }
+    catch (e) {
+        const message = e?.message ?? String(e);
+        return { passed: false, errors: [`TypeScript syntax error: ${message.split("\n")[0]}`] };
+    }
+}
+/**
+ * validate_file (AC-17): post-edit syntax/type check on JUST the patched
+ * file. Prefers the workspace's own detected `typecheck`/`lint` commands,
+ * then fast per-language syntax fallbacks (node --check, py_compile, JSON
+ * parse). Returns ONLY error lines — never the file body. Like every tool,
+ * it never throws; uncheckable languages return `no_checker_available` with
+ * a fallback suggestion.
+ */
+export async function validateFileTool(root, relPath, lang) {
+    let full;
+    try {
+        full = resolveInWorkspace(root, relPath);
+    }
+    catch (e) {
+        return { ok: false, code: "workspace_escape", error: e.message };
+    }
+    // Fail fast on a missing file before any checker runs.
+    try {
+        await fs.access(full);
+    }
+    catch {
+        return {
+            ok: false,
+            code: "file_not_found",
+            error: `"${relPath}" doesn't exist. Use write_file to create it before validating.`,
+        };
+    }
+    const language = (lang ?? guessLanguage(relPath)).toLowerCase();
+    const started = Date.now();
+    // 1) Try the project's own typecheck/lint first — it's already computed
+    //    per workspace and is the most accurate signal.
+    try {
+        const index = await getOrBuildIndex(root);
+        const cmds = await detectProjectCommands(root, index);
+        const candidates = [cmds.typecheck, cmds.lint].filter((c) => !!c);
+        for (const candidate of candidates) {
+            const res = await runCommandTool(candidate, root, 120_000);
+            const errors = extractErrorLines(res.stdout + "\n" + res.stderr);
+            return {
+                ok: true,
+                result: {
+                    passed: res.ok && errors.length === 0,
+                    command: candidate,
+                    tool: "project-command",
+                    errors: errors.length > 0 ? errors.slice(0, 40) : undefined,
+                    tookMs: Date.now() - started,
+                },
+            };
+        }
+    }
+    catch {
+        // fall through to language-specific syntax checks
+    }
+    // 2) Fast per-language syntax fallbacks.
+    //
+    // TypeScript MUST NOT go through `node --check`: that parser rejects
+    // TS-only syntax (annotations, interfaces, generics), so every valid .ts
+    // file was reported as failing. Use a TS-aware checker instead, and only
+    // count diagnostics that point at this file so project/include-level noise
+    // can never mark a good edit as broken.
+    if (language === "typescript") {
+        const res = await runCommandTool(`npx tsc --noEmit --skipLibCheck --target esnext --module esnext "${full}"`, root, 120_000);
+        const raw = extractErrorLines(res.stdout + "\n" + res.stderr);
+        const relevant = raw.filter((line) => line.includes(full) || line.includes(relPath));
+        // A checker that never ran (npx missing / tsc unavailable) must not be
+        // reported as a passing validation.
+        if (!res.ok && raw.length === 0) {
+            const fallback = await checkTypeScriptSyntax(full);
+            return {
+                ok: true,
+                result: {
+                    passed: fallback.passed,
+                    command: "stripTypeScriptTypes",
+                    tool: "in-process",
+                    errors: fallback.errors.length > 0 ? fallback.errors.slice(0, 40) : undefined,
+                    tookMs: Date.now() - started,
+                },
+            };
+        }
+        return {
+            ok: true,
+            result: {
+                passed: res.ok && relevant.length === 0,
+                command: "tsc --noEmit",
+                tool: "typecheck",
+                errors: relevant.length > 0 ? relevant.slice(0, 40) : undefined,
+                tookMs: Date.now() - started,
+            },
+        };
+    }
+    if (language === "javascript") {
+        const res = await runCommandTool(`node --check "${full}"`, root, 60_000);
+        const errors = extractErrorLines(res.stderr);
+        return {
+            ok: true,
+            result: {
+                passed: res.ok && errors.length === 0,
+                command: "node --check",
+                tool: "syntax",
+                errors: errors.length > 0 ? errors.slice(0, 40) : undefined,
+                tookMs: Date.now() - started,
+            },
+        };
+    }
+    if (language === "python") {
+        const res = await runCommandTool(`python -m py_compile "${full}"`, root, 60_000);
+        const errors = extractErrorLines(res.stderr);
+        return {
+            ok: true,
+            result: {
+                passed: res.ok && errors.length === 0,
+                command: "python -m py_compile",
+                tool: "syntax",
+                errors: errors.length > 0 ? errors.slice(0, 40) : undefined,
+                tookMs: Date.now() - started,
+            },
+        };
+    }
+    if (language === "json") {
+        try {
+            const raw = await fs.readFile(full, "utf8");
+            JSON.parse(raw);
+            return { ok: true, result: { passed: true, command: "JSON.parse", tool: "in-process", tookMs: Date.now() - started } };
+        }
+        catch (e) {
+            return {
+                ok: true,
+                result: {
+                    passed: false,
+                    command: "JSON.parse",
+                    tool: "in-process",
+                    errors: [`JSON parse error: ${e.message}`],
+                    tookMs: Date.now() - started,
+                },
+            };
+        }
+    }
+    return {
+        ok: false,
+        code: "no_checker_available",
+        error: `no syntax/type checker found for "${language}" ("${relPath}"). Use run_command to run an appropriate compiler/linter for this language.`,
+    };
+}
+/** Pulls only error/warning lines out of mixed output — never file bodies. */
+function extractErrorLines(output) {
+    return output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l !== "" && /(?:error|Error|❌|✖|failed|Cannot find|TS\d+|SyntaxError|ModuleNotFound)/.test(l))
+        .slice(0, 40);
+}

package/dist/tools/workspace-index.d.ts

@@ -0,0 +1,46 @@
+export interface IndexEntry {
+    relPath: string;
+    sizeBytes: number;
+    mtimeMs: number;
+    sha1: string;
+    language: string;
+}
+export interface WorkspaceIndex {
+    root: string;
+    builtAt: string;
+    entries: IndexEntry[];
+}
+export declare const IGNORE_DIRS: Set<string>;
+/**
+ * Files above this size are never hashed or indexed.
+ *
+ * Exported because the freshness probe must apply the same threshold as the
+ * builder. If it did not, every file above the cap would look like a missing
+ * index entry on every probe and the index would be rebuilt forever.
+ */
+export declare const MAX_INDEXED_FILE_BYTES = 5000000;
+/**
+ * Every path this module stores or compares goes through this first.
+ *
+ * `path.relative()` uses the OS-native separator — backslashes on Windows.
+ * The model, quite reasonably, tends to write and request paths with
+ * forward slashes regardless of platform (it's the universal convention
+ * in code, docs, and every other tool's examples). Without normalization,
+ * a Windows index stores `requirements\design.md` while the model asks
+ * for `requirements/design.md`, the exact-string lookup in `findInIndex`
+ * fails, and `read_file` reports a false `file_not_found` for a file that
+ * genuinely exists — burning iterations on rediscovery instead of actual
+ * work. Storing (and comparing against) forward-slash-normalized paths
+ * everywhere makes every lookup, glob, and grep work identically
+ * regardless of which slash style either side happens to use.
+ */
+export declare function toPosixPath(p: string): string;
+/** Full rebuild. This is the expensive path — call it, don't call it often. */
+export declare function buildIndex(root: string): Promise<WorkspaceIndex>;
+export declare function loadIndex(root: string): Promise<WorkspaceIndex | null>;
+export declare function getOrBuildIndex(root: string): Promise<WorkspaceIndex>;
+/** Cheap incremental update after a single write — avoids a full rescan per file. */
+export declare function upsertEntry(root: string, relPath: string): Promise<void>;
+/** Normalizes the lookup path the same way stored paths are normalized, so a lookup succeeds regardless of which slash style the caller used. */
+export declare function findInIndex(index: WorkspaceIndex, relPath: string): IndexEntry | undefined;
+export declare function searchIndex(index: WorkspaceIndex, query: string, limit?: number): IndexEntry[];

package/dist/tools/workspace-index.js

@@ -0,0 +1,173 @@
+// xcoder:version 3 | xcoder:task task-e16f85 | xcoder:updated 2026-10-30T18:13:45.828Z | xcoder:subtask code-st-791be4
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+export const IGNORE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".xcoder",
+    ".next",
+    ".venv",
+    "__pycache__",
+    "coverage",
+    ".turbo",
+]);
+/**
+ * Files above this size are never hashed or indexed.
+ *
+ * Exported because the freshness probe must apply the same threshold as the
+ * builder. If it did not, every file above the cap would look like a missing
+ * index entry on every probe and the index would be rebuilt forever.
+ */
+export const MAX_INDEXED_FILE_BYTES = 5_000_000;
+const LANGUAGE_BY_EXT = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".py": "python",
+    ".go": "go",
+    ".java": "java",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".json": "json",
+    ".md": "markdown",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".sql": "sql",
+    ".sh": "shell",
+};
+function indexPath(root) {
+    return path.join(root, ".xcoder", "workspace-index.json");
+}
+/**
+ * Every path this module stores or compares goes through this first.
+ *
+ * `path.relative()` uses the OS-native separator — backslashes on Windows.
+ * The model, quite reasonably, tends to write and request paths with
+ * forward slashes regardless of platform (it's the universal convention
+ * in code, docs, and every other tool's examples). Without normalization,
+ * a Windows index stores `requirements\design.md` while the model asks
+ * for `requirements/design.md`, the exact-string lookup in `findInIndex`
+ * fails, and `read_file` reports a false `file_not_found` for a file that
+ * genuinely exists — burning iterations on rediscovery instead of actual
+ * work. Storing (and comparing against) forward-slash-normalized paths
+ * everywhere makes every lookup, glob, and grep work identically
+ * regardless of which slash style either side happens to use.
+ */
+export function toPosixPath(p) {
+    return p.split(path.sep).join("/").replace(/\\/g, "/");
+}
+function guessLanguage(p) {
+    return LANGUAGE_BY_EXT[path.extname(p)] ?? "text";
+}
+async function hashFile(fullPath) {
+    const buf = await fs.readFile(fullPath);
+    return crypto.createHash("sha1").update(buf).digest("hex");
+}
+async function walk(dir, root, acc) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".env.example") {
+            if (entry.isDirectory() && !IGNORE_DIRS.has(entry.name)) {
+                // allow hidden dirs the user explicitly wants scanned in the future;
+                // for now, skip all dotfiles/dotdirs except the explicit allowlist above.
+            }
+            continue;
+        }
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.has(entry.name))
+                continue;
+            await walk(full, root, acc);
+        }
+        else if (entry.isFile()) {
+            try {
+                const stat = await fs.stat(full);
+                // Skip anything absurdly large — it has no business being hashed
+                // wholesale and inlined-by-reference is the right pattern anyway.
+                if (stat.size > MAX_INDEXED_FILE_BYTES)
+                    continue;
+                const sha1 = await hashFile(full);
+                acc.push({
+                    relPath: toPosixPath(path.relative(root, full)),
+                    sizeBytes: stat.size,
+                    mtimeMs: stat.mtimeMs,
+                    sha1,
+                    language: guessLanguage(full),
+                });
+            }
+            catch {
+                // unreadable file (permissions, race with a concurrent delete) — skip it
+            }
+        }
+    }
+}
+/** Full rebuild. This is the expensive path — call it, don't call it often. */
+export async function buildIndex(root) {
+    const entries = [];
+    await walk(root, root, entries);
+    const index = { root, builtAt: new Date().toISOString(), entries };
+    await fs.mkdir(path.join(root, ".xcoder"), { recursive: true });
+    await fs.writeFile(indexPath(root), JSON.stringify(index, null, 2), "utf8");
+    return index;
+}
+export async function loadIndex(root) {
+    try {
+        const raw = await fs.readFile(indexPath(root), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function getOrBuildIndex(root) {
+    const existing = await loadIndex(root);
+    if (existing)
+        return existing;
+    return buildIndex(root);
+}
+/** Cheap incremental update after a single write — avoids a full rescan per file. */
+export async function upsertEntry(root, relPath) {
+    const index = (await loadIndex(root)) ?? { root, builtAt: new Date().toISOString(), entries: [] };
+    const normalizedRelPath = toPosixPath(relPath);
+    const full = path.join(root, relPath); // path.join/resolve handle forward slashes fine on every OS, including Windows
+    try {
+        const stat = await fs.stat(full);
+        const sha1 = await hashFile(full);
+        const next = {
+            relPath: normalizedRelPath,
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs,
+            sha1,
+            language: guessLanguage(full),
+        };
+        const idx = index.entries.findIndex((e) => e.relPath === normalizedRelPath);
+        if (idx >= 0)
+            index.entries[idx] = next;
+        else
+            index.entries.push(next);
+        await fs.writeFile(indexPath(root), JSON.stringify(index, null, 2), "utf8");
+    }
+    catch {
+        // file vanished between write and index update — ignore, next full
+        // reindex will reconcile it.
+    }
+}
+/** Normalizes the lookup path the same way stored paths are normalized, so a lookup succeeds regardless of which slash style the caller used. */
+export function findInIndex(index, relPath) {
+    const normalized = toPosixPath(relPath).replace(/^\.\//, "");
+    return index.entries.find((e) => e.relPath === normalized);
+}
+export function searchIndex(index, query, limit = 30) {
+    const q = toPosixPath(query).toLowerCase();
+    return index.entries.filter((e) => e.relPath.toLowerCase().includes(q)).slice(0, limit);
+}

package/dist/types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Core contracts. Everything else in this codebase is built around these
+ * shapes — the same principle Agent Factory's `af-shared-contracts` repo
+ * follows: one definition, imported everywhere, never hand-copied.
+ */
+import type { BylawLayer } from "./skills/secure-architect.bylaws.js";
+export type SdlcStage = "requirements" | "design" | "code" | "refactor" | "test" | "ui_api_test" | "fix_defect" | "document" | "deploy" | "conversation" | "quality_gate";
+export type Role = "requirements-analyst" | "architect" | "programmer" | "refactorer" | "tester" | "ui-api-tester" | "technical-writer" | "devops" | "conversation" | "business-analyst" | "defect-manager" | "scrum-master" | "system-architect" | "security-lead";
+export type EngineName = "react-v1" | "rewoo-v1" | "plan-execute-v1" | "reflexion-v1";
+/** Raw inputs as described in the brief: code / design / defect / url / credential. */
+export interface TaskInputs {
+    code?: string;
+    design?: string;
+    defectDetail?: string;
+    url?: string;
+    credentialRef?: string;
+    freeText?: string;
+    /**
+     * Workspace-relative POSIX path of the markdown/WBS source this task was
+     * ingested from (`xcoder task add --from <path>`). This is the idempotency
+     * key, readable back off the record. Inert data — it is NEVER re-interpreted
+     * as a path, command, URL or model directive at read time.
+     */
+    sourcePath?: string;
+    /**
+     * Workspace-relative POSIX path to the author-supplied requirements document
+     * that drives the QA workflow (requirement -> plan -> Playwright specs ->
+     * run -> report). Additive: its presence is what opts a task into that
+     * route, and no pre-existing intake rule changes behaviour without it.
+     */
+    requirementsPath?: string;
+    /**
+     * Minimum fraction (0<t<=1) of requirements whose tests must actually run
+     * and pass before the QA workflow may report a pass. Defaults to 1.0 - the
+     * brief asks for coverage of every requirement (design T1).
+     */
+    coverageThreshold?: number;
+}
+export interface TaskSpec {
+    taskId: string;
+    goal: string;
+    inputs: TaskInputs;
+    constraints: {
+        budgetUsd?: number;
+        maxHealingAttempts: number;
+        concurrency: number;
+    };
+    createdAt: string;
+    /**
+     * Audit trail for `xcoder task add --from <path>` ingestion. Absent on
+     * free-text tasks, which keeps every existing record byte-compatible.
+     * Recorded for provenance only — nothing downstream acts on it.
+     */
+    provenance?: {
+        sourcePath: string;
+        sourceSha256: string;
+        ingestedAt: string;
+        ingestVersion: 1;
+    };
+}
+export type SubtaskStatus = "pending" | "ready" | "in_progress" | "validating" | "healing" | "escalated" | "blocked" | "done" | "failed";
+export interface AcceptanceCriterion {
+    id: string;
+    type: "schema" | "command" | "rubric" | "file-exists" | "bylaw-review";
+    description: string;
+    /** For `command` type: a shell command run from the workspace root; exit code 0 = pass. */
+    command?: string;
+    /** For `file-exists` type: a glob pattern relative to the workspace root. At least one matching file must exist. */
+    pathGlob?: string;
+    /** For `bylaw-review` type: restrict the review scope to these layers.
+     *  Omitted => inferLayers(goal) at validation time. */
+    bylawLayers?: BylawLayer[];
+}
+/**
+ * A fully self-contained work order. A Sub Agent must be able to execute
+ * this in isolation, with its own memory loop, using nothing beyond this
+ * node, the tool registry, and its role's directive/skills.
+ */
+export interface SubtaskNode {
+    id: string;
+    stage: SdlcStage;
+    role: Role;
+    engine: EngineName;
+    dependsOn: string[];
+    goal: string;
+    /** Inlined outputs from upstream nodes — never a lookup id. */
+    upstreamContext: Record<string, unknown>;
+    /** What this subtask must hand back to the Master Orchestrator. */
+    deliverableSpec: string;
+    acceptanceCriteria: AcceptanceCriterion[];
+    status: SubtaskStatus;
+    healing: {
+        attempts: number;
+        maxAttempts: number;
+        log: string[];
+    };
+    result?: SubtaskResult;
+    /** Computed once per attempt by orchestrator/reasoning-score.ts, after validation. Not a pass/fail gate — see that file's doc comment for what this is and isn't for. */
+    reasoningScore?: {
+        score: number;
+        breakdown: string[];
+    };
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Tracks the operation type for each file touched by a subtask. */
+export type FileTouchOperation = "created" | "modified" | "touched";
+export interface FileTouchEntry {
+    path: string;
+    operation: FileTouchOperation;
+}
+export interface SubtaskResult {
+    summary: string;
+    deliverable: unknown;
+    filesTouched: string[];
+    /**
+     * Optional additive field carrying operation type per file.
+     * Populated alongside filesTouched when context is available.
+     * When absent, consumers fall back to `filesTouched: string[]` with a
+     * generic `[touched]` label.
+     */
+    _filesTouchedMeta?: FileTouchEntry[];
+    selfCheck?: {
+        ran: boolean;
+        passed: boolean;
+        detail: string;
+    };
+    raoTrace: RaoStep[];
+    tokenUsage: TokenUsage;
+    /** Number of ReAct loop turns taken to reach this result — the "iteration count" the benchmark harness and reasoning score both key off. */
+    iterations: number;
+    /** True if this result is a synthetic stand-in produced after the Sub Agent's
+     *  process crashed — the Master Orchestrator never crashes with it (see
+     *  `orchestrator/swarm.ts`); it treats a crash as a failed subtask that can
+     *  still go through the normal bounded healing/escalation path. */
+    crashed?: boolean;
+    /** True if the attempt was aborted early because DuplicateActionDetector flagged it as a stuck loop rather than running to the full iteration cap. */
+    stuckLoop?: boolean;
+    /** True when the sub-agent exhausted its maxIterations without producing a final_answer. Set ONLY by SubAgent.run() in that case; never set in crashResult or stuckLoop returns. */
+    iterationsExhausted?: boolean;
+}
+export interface RaoStep {
+    thought: string;
+    action: {
+        tool: string;
+        input: unknown;
+    } | null;
+    observation: string;
+}
+export interface TaskRun {
+    spec: TaskSpec;
+    dag: SubtaskNode[];
+    status: "planning" | "running" | "done" | "halted" | "escalated";
+    escalations: {
+        subtaskId: string;
+        reason: string;
+    }[];
+    orchestratorTrace: RaoStep[];
+    finalDeliverable?: string;
+    totalTokenUsage: TokenUsage;
+    /** Interactive steering injections captured during this run, in order. */
+    steeringLog?: import("./orchestrator/interactive-steering.js").SteeringInjection[];
+}
+export type OrchestratorAction = {
+    type: "dispatch";
+    subtaskIds: string[];
+} | {
+    type: "retry";
+    subtaskId: string;
+    hint: string;
+} | {
+    type: "replan";
+    patch: {
+        addNodes?: SubtaskNode[];
+        removeNodeIds?: string[];
+    };
+} | {
+    type: "escalate";
+    subtaskId: string;
+    reason: string;
+} | {
+    type: "halt";
+    reason: string;
+};
+export interface DecisionContext {
+    dag: SubtaskNode[];
+    triggeringEvent: "subtask_failed" | "subtask_done" | "budget_warning" | "stuck_timeout";
+    subtask?: SubtaskNode;
+}
+export interface ReasoningEngine {
+    name: EngineName;
+    decide(context: DecisionContext): Promise<OrchestratorAction>;
+}
+export interface LoadedSkill {
+    header: SkillHeader;
+    body: string;
+    path: string;
+}
+export interface SkillHeader {
+    name: string;
+    role: string;
+    description: string;
+    triggers: string[];
+    version: string;
+    requires_tools: string[];
+    composes_with: string[];
+}
+/** A single lesson recorded into .xcoder/lesson.md. */
+export interface LessonEntry {
+    /** Who recorded this — "orchestrator" | "sub-agent:<role>" | "samurai" */
+    source: string;
+    /** The task ID this was learned under, or "N/A" for standalone samurai. */
+    taskId: string;
+    /** Free-form tags for later categorisation (e.g. ["build-failure", "npm"]). */
+    tags: string[];
+    /** Brief description of what was happening when the lesson was recorded. */
+    context: string;
+    /** The actual insight — what was hard, why, and what was figured out. */
+    lesson: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+// xcoder:version 4 | xcoder:task task-a91099 | xcoder:updated 2026-10-23T10:52:21.073Z | xcoder:subtask code-st-03748c
+/**
+ * Core contracts. Everything else in this codebase is built around these
+ * shapes — the same principle Agent Factory's `af-shared-contracts` repo
+ * follows: one definition, imported everywhere, never hand-copied.
+ */
+export {};

package/dist/updater/index.d.ts

@@ -0,0 +1,14 @@
+/** Auto-Update Module — §3.5 of design-desktop-installer.md */
+export interface UpdaterOptions {
+    currentVersion: string;
+    repo: string;
+    checkIntervalMs?: number;
+}
+export interface UpdateCheckResult {
+    updateAvailable: boolean;
+    latestVersion: string | null;
+    downloadUrl: string | null;
+    releaseNotes: string | null;
+}
+export declare function checkForUpdate(opts: UpdaterOptions): Promise<UpdateCheckResult>;
+export declare function downloadAndApplyUpdate(downloadUrl: string, sha256Url: string): Promise<void>;