loadout-ai 0.9.0 → 0.9.2

package/dist/src/core/coordination/adapters/claude-code.js

@@ -5,14 +5,20 @@
  * turn; the CLI does not provide mid-turn injection or global session listing.
  */
 import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-const exec = promisify(execFile);
 const PROVIDER = "claude-code";
 const CLI = "claude";
-const defaultCommandDriver = async (command, args, options) => {
-    const { stdout } = await exec(command, [...args], options);
-    return { stdout: String(stdout) };
-};
+export const runClaudeCommand = async (command, args, options) => new Promise((resolve, reject) => {
+    const child = execFile(command, [...args], { ...options, encoding: "utf8" }, (error, stdout) => {
+        if (error) {
+            reject(error);
+            return;
+        }
+        resolve({ stdout: String(stdout) });
+    });
+    // execFile opens a writable stdin pipe. Claude waits briefly for input
+    // unless the parent closes it, so end it as soon as the process starts.
+    child.stdin?.end();
+});
 function parseSessionOutput(stdout) {
     let parsed;
     try {
@@ -40,7 +46,7 @@ export class ClaudeCodeAdapter {
     provider = PROVIDER;
     sessions = new Map();
     responses = new Map();
-    constructor(runCommand = defaultCommandDriver) {
+    constructor(runCommand = runClaudeCommand) {
         this.runCommand = runCommand;
     }
     capabilities = {
@@ -73,6 +79,7 @@ export class ClaudeCodeAdapter {
         const { stdout } = await this.runCommand(CLI, args, {
             cwd: options.cwd,
             timeout: options.timeout ?? 30000,
+            ...(options.signal ? { signal: options.signal } : {}),
         });
         const output = parseSessionOutput(stdout);
         const sessionId = output.sessionId;
@@ -122,6 +129,7 @@ export class ClaudeCodeAdapter {
             const { stdout } = await this.runCommand(CLI, args, {
                 cwd: session.cwd,
                 timeout: options.timeout ?? 30000,
+                ...(options.signal ? { signal: options.signal } : {}),
             });
             const output = parseSessionOutput(stdout);
             if (output.response) {

package/dist/src/core/coordination/adapters/codex.js

@@ -17,6 +17,26 @@ function requireThreadId(thread) {
     }
     return id;
 }
+async function runWithCancellation(thread, prompt, options) {
+    if (options.timeout === undefined) {
+        return thread.run(prompt, options.signal ? { signal: options.signal } : undefined);
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+        onAbort();
+    else
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(new Error(`Codex provider turn timed out after ${options.timeout}ms`)), options.timeout);
+    timer.unref();
+    try {
+        return await thread.run(prompt, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
 function responseFromRun(result) {
     if (typeof result === "object" &&
         result !== null &&
@@ -60,10 +80,14 @@ export class CodexAdapter {
         if (options.resumeSessionId) {
             throw new Error("Use resume() to continue a Codex thread");
         }
+        options.signal?.throwIfAborted();
         const thread = this.driver.startThread({
             workingDirectory: options.cwd,
         });
-        const result = await thread.run(options.prompt ?? "");
+        const result = await runWithCancellation(thread, options.prompt ?? "", {
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+        });
         const sessionId = requireThreadId(thread);
         const session = {
             sessionId,
@@ -109,7 +133,10 @@ export class CodexAdapter {
             return false;
         session.busy = true;
         try {
-            const result = await thread.run(options.message);
+            const result = await runWithCancellation(thread, options.message, {
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+            });
             const response = responseFromRun(result);
             if (response)
                 this.responses.set(session.sessionId, response);

package/dist/src/core/coordination/auto-contract.js

@@ -0,0 +1,457 @@
+/**
+ * Auto-contract detection — scans for cross-boundary exports and suggests
+ * contracts when shared interfaces change.
+ *
+ * Uses regex-based scanning (no TS compiler dependency) to find exported
+ * symbols and cross-ownership imports. Runs as a pre-handoff check or
+ * standalone via `loadout coord detect`.
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, posix } from "node:path";
+import { getOwnership, getContracts, } from "./coordinator.js";
+// ── Export scanning ────────────────────────────────────────────────────
+const EXPORT_PATTERNS = [
+    {
+        pattern: /^export\s+(?:declare\s+)?interface\s+(\w+)/,
+        kind: "interface",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?type\s+(\w+)/,
+        kind: "type",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?(?:async\s+)?function\s+(\w+)/,
+        kind: "function",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?const\s+(\w+)/,
+        kind: "const",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?let\s+(\w+)/,
+        kind: "const",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?class\s+(\w+)/,
+        kind: "class",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?enum\s+(\w+)/,
+        kind: "enum",
+    },
+    {
+        pattern: /^export\s+(?:declare\s+)?abstract\s+class\s+(\w+)/,
+        kind: "class",
+    },
+];
+// Matches `export { Foo, Bar } from "./module"` and `export { Foo, Bar }`
+const RE_EXPORT = /^export\s*\{([^}]+)\}(?:\s*from\s*["']([^"']+)["'])?/;
+function scanExports(content, filePath) {
+    const symbols = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trimStart();
+        if (!line.startsWith("export"))
+            continue;
+        // Named export patterns
+        for (const { pattern, kind } of EXPORT_PATTERNS) {
+            const match = line.match(pattern);
+            if (match) {
+                const declaration = exactDeclaration(line.trim(), kind);
+                symbols.push({
+                    name: match[1],
+                    kind,
+                    file: filePath,
+                    line: i + 1,
+                    ...(declaration ? { declaration } : {}),
+                });
+                break;
+            }
+        }
+        // Re-exports: export { X, Y } from "..."
+        const reMatch = line.match(RE_EXPORT);
+        if (reMatch) {
+            const names = reMatch[1]
+                .split(",")
+                .map((s) => s
+                .trim()
+                .split(/\s+as\s+/)
+                .pop()
+                .trim())
+                .filter(Boolean);
+            for (const name of names) {
+                symbols.push({
+                    name,
+                    kind: "re-export",
+                    file: filePath,
+                    line: i + 1,
+                    declaration: line.trim(),
+                });
+            }
+        }
+    }
+    return symbols;
+}
+function exactDeclaration(line, kind) {
+    if (kind === "function") {
+        const close = line.lastIndexOf(")");
+        const body = close >= 0 ? line.indexOf("{", close) : -1;
+        if (body > close)
+            return `${line.slice(0, body).trimEnd()};`;
+        return line.endsWith(";") ? line : undefined;
+    }
+    if (kind === "interface" || kind === "class" || kind === "enum") {
+        return line.includes("{") && line.includes("}") ? line : undefined;
+    }
+    if (kind === "type" || kind === "const") {
+        if (!line.includes("="))
+            return undefined;
+        // Reject incomplete multi-line declarations (opens a block without closing it).
+        const afterEq = line.slice(line.indexOf("=") + 1).trim();
+        if (afterEq.includes("{") && !afterEq.includes("}"))
+            return undefined;
+        if (afterEq.includes("(") && !afterEq.includes(")"))
+            return undefined;
+        if (afterEq.includes("[") && !afterEq.includes("]"))
+            return undefined;
+        return line;
+    }
+    return undefined;
+}
+// ── Import scanning ────────────────────────────────────────────────────
+// Matches: import { X, Y } from "./path"
+//          import type { X } from "./path"
+//          import X from "./path"
+const IMPORT_PATTERNS = [
+    // Named imports: import { A, B } from "..."
+    /import\s+(?:type\s+)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g,
+    // Default import: import X from "..."
+    /import\s+(\w+)\s+from\s*["']([^"']+)["']/g,
+    // Side-effect import is excluded (no symbols)
+];
+function scanImports(content) {
+    const imports = [];
+    for (const pattern of IMPORT_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const symbolPart = match[1];
+            const source = match[2];
+            // Skip node_modules / bare specifiers
+            if (!source.startsWith(".") && !source.startsWith("/"))
+                continue;
+            const symbols = symbolPart.includes(",") || symbolPart.includes("{")
+                ? symbolPart
+                    .split(",")
+                    .map((s) => s
+                    .trim()
+                    .replace(/^type\s+/, "")
+                    .split(/\s+as\s+/)[0]
+                    .trim())
+                    .filter(Boolean)
+                : [symbolPart.trim()];
+            imports.push({ symbols, source });
+        }
+    }
+    return imports;
+}
+// ── File walking ───────────────────────────────────────────────────────
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".handoff",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    "coverage",
+    "__pycache__",
+]);
+const TS_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts"]);
+const JS_EXTENSIONS = new Set([".js", ".jsx", ".mjs", ".cjs"]);
+const ALL_EXTENSIONS = new Set([...TS_EXTENSIONS, ...JS_EXTENSIONS]);
+async function walkFiles(dir, rootDir, maxFiles) {
+    const files = [];
+    async function walk(current) {
+        if (files.length >= maxFiles)
+            return;
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                return;
+            if (entry.name.startsWith(".") && entry.name !== ".")
+                continue;
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            const fullPath = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const ext = entry.name.slice(entry.name.lastIndexOf("."));
+                if (ALL_EXTENSIONS.has(ext)) {
+                    files.push(normalizeProjectPath(relative(rootDir, fullPath)));
+                }
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+export function normalizeProjectPath(value) {
+    const normalized = posix.normalize(value.replaceAll("\\", "/"));
+    return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+}
+function findOwner(filePath, ownership) {
+    // Find the most specific (longest) owned path that covers this file
+    let bestMatch = "";
+    let bestAgent;
+    const normalizedFile = normalizeProjectPath(filePath);
+    for (const [, claim] of ownership) {
+        for (const ownedPath of claim.paths) {
+            const claimPath = normalizeProjectPath(ownedPath);
+            const normalized = claimPath.endsWith("/")
+                ? claimPath.slice(0, -1)
+                : claimPath;
+            if ((normalizedFile === normalized ||
+                normalizedFile.startsWith(normalized + "/") ||
+                normalized === ".") &&
+                normalized.length > bestMatch.length) {
+                bestMatch = normalized;
+                bestAgent = claim.agent;
+            }
+        }
+    }
+    return bestAgent;
+}
+// ── Import resolution ──────────────────────────────────────────────────
+function resolveImportPath(importSource, importerFile) {
+    const importerDir = posix.dirname(normalizeProjectPath(importerFile));
+    let resolved = posix.normalize(posix.join(importerDir, normalizeProjectPath(importSource)));
+    if (resolved === ".." || resolved.startsWith("../"))
+        return "";
+    // Strip .js extension (TS files import as .js)
+    resolved = resolved.replace(/\.js$/, "");
+    return resolved;
+}
+function matchSourceFile(resolvedImport, allFiles) {
+    // Try exact match, then with extensions
+    for (const ext of ["", ".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs"]) {
+        const candidate = resolvedImport + ext;
+        if (allFiles.includes(candidate))
+            return candidate;
+    }
+    // Try index file
+    for (const ext of [".ts", ".tsx", ".js", ".jsx"]) {
+        const candidate = resolvedImport + "/index" + ext;
+        if (allFiles.includes(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+// ── Main detection ─────────────────────────────────────────────────────
+/** Max files to scan to keep detection fast. */
+const MAX_FILES = 5_000;
+export async function detectContracts(projectRoot, options = {}) {
+    const ownership = await getOwnership(projectRoot);
+    const existingContracts = await getContracts(projectRoot);
+    // If no ownership is set up, can't detect cross-boundary imports
+    if (ownership.size === 0) {
+        return { crossBoundaryImports: [], candidates: [], filesScanned: 0 };
+    }
+    const maxFiles = options.maxFiles ?? MAX_FILES;
+    // Walk project files
+    const walkedFiles = options.scope
+        ? (await Promise.all(options.scope.map((dir) => {
+            const scope = normalizeProjectPath(dir);
+            if (!scope ||
+                posix.isAbsolute(scope) ||
+                scope === ".." ||
+                scope.startsWith("../"))
+                throw new Error(`Scope must stay inside the project: ${dir}`);
+            return walkFiles(join(projectRoot, ...scope.split("/")), projectRoot, maxFiles);
+        }))).flat()
+        : await walkFiles(projectRoot, projectRoot, maxFiles);
+    const allFiles = [...new Set(walkedFiles)].slice(0, maxFiles);
+    // Scan exports for every file
+    const exportsByFile = new Map();
+    for (const file of allFiles) {
+        try {
+            const content = await readFile(join(projectRoot, file), "utf8");
+            const exports = scanExports(content, file);
+            if (exports.length > 0) {
+                exportsByFile.set(file, exports);
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    // Scan imports and find cross-boundary references
+    const crossBoundaryImports = [];
+    for (const file of allFiles) {
+        const importerAgent = findOwner(file, ownership);
+        if (!importerAgent)
+            continue;
+        let content;
+        try {
+            content = await readFile(join(projectRoot, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const imports = scanImports(content);
+        for (const imp of imports) {
+            const resolved = resolveImportPath(imp.source, file);
+            const sourceFile = matchSourceFile(resolved, allFiles);
+            if (!sourceFile)
+                continue;
+            const sourceAgent = findOwner(sourceFile, ownership);
+            if (!sourceAgent || sourceAgent === importerAgent)
+                continue;
+            crossBoundaryImports.push({
+                importer: file,
+                importerAgent,
+                source: sourceFile,
+                sourceAgent,
+                symbols: imp.symbols,
+            });
+        }
+    }
+    // Group by source file → contract candidate
+    const candidateMap = new Map();
+    for (const xbi of crossBoundaryImports) {
+        const existing = candidateMap.get(xbi.source);
+        if (existing) {
+            existing.consumers.add(xbi.importerAgent);
+            for (const s of xbi.symbols)
+                existing.symbols.add(s);
+        }
+        else {
+            candidateMap.set(xbi.source, {
+                sourceAgent: xbi.sourceAgent,
+                consumers: new Set([xbi.importerAgent]),
+                symbols: new Set(xbi.symbols),
+            });
+        }
+    }
+    // Build candidates
+    const candidates = [];
+    for (const [sourceFile, info] of candidateMap) {
+        const allExports = exportsByFile.get(sourceFile) ?? [];
+        const sharedSymbols = allExports.filter((e) => info.symbols.has(e.name));
+        // Generate contract name from file path
+        const name = contractNameFromPath(sourceFile);
+        // Check if contract already exists
+        const existingContract = existingContracts.get(name);
+        // Build suggested body from shared exports
+        const generated = buildContractBody(sourceFile, sharedSymbols);
+        const coverageState = !existingContract
+            ? "uncovered"
+            : existingContract.body === generated.body
+                ? "current"
+                : "stale";
+        candidates.push({
+            name,
+            sourceFile,
+            sourceAgent: info.sourceAgent,
+            consumers: [...info.consumers],
+            sharedSymbols,
+            existingContract,
+            suggestedBody: generated.body,
+            sourceHash: generated.sourceHash,
+            publishable: generated.publishable,
+            coverageState,
+        });
+    }
+    // Sort: uncovered (no existing contract) first, then by consumer count
+    candidates.sort((a, b) => {
+        if (!a.existingContract && b.existingContract)
+            return -1;
+        if (a.existingContract && !b.existingContract)
+            return 1;
+        return b.consumers.length - a.consumers.length;
+    });
+    return {
+        crossBoundaryImports,
+        candidates,
+        filesScanned: allFiles.length,
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────────
+function contractNameFromPath(filePath) {
+    // src/api/types.ts → api-types
+    // src/core/coordination/events.ts → coordination-events
+    return filePath
+        .replace(/^src\//, "")
+        .replace(/\.(ts|tsx|js|jsx|mts|mjs|cts|cjs)$/, "")
+        .replace(/\/index$/, "")
+        .replace(/\//g, "-");
+}
+function buildContractBody(sourceFile, symbols) {
+    if (symbols.length === 0) {
+        const manual = `// MANUAL: no exact typed exports detected for ${sourceFile}`;
+        return {
+            body: manual,
+            sourceHash: createHash("sha256").update("").digest("hex"),
+            publishable: false,
+        };
+    }
+    const declarations = symbols.map((symbol) => symbol.declaration ??
+        `// MANUAL: copy the complete ${symbol.kind} declaration for ${symbol.name}`);
+    const declarationBlock = declarations.join("\n");
+    const sourceHash = createHash("sha256")
+        .update(declarationBlock)
+        .digest("hex");
+    const lines = [
+        `// Auto-detected contract for ${sourceFile}`,
+        "// Snapshot only — the canonical source module remains authoritative.",
+        `// ${symbols.length} shared export(s)`,
+        `// loadout-source-sha256: sha256-${sourceHash}`,
+        "",
+        ...declarations,
+    ];
+    return {
+        body: lines.join("\n"),
+        sourceHash,
+        publishable: symbols.every((symbol) => !!symbol.declaration),
+    };
+}
+// ── Terminal formatting ────────────────────────────────────────────────
+export function formatDetectionResult(result) {
+    const lines = [];
+    if (result.candidates.length === 0) {
+        lines.push("No cross-boundary exports detected.");
+        lines.push(`Scanned ${result.filesScanned} file(s).`);
+        if (result.crossBoundaryImports.length === 0) {
+            lines.push("\x1b[90mEither no ownership is set, or all imports stay within owned boundaries.\x1b[0m");
+        }
+        return lines.join("\n");
+    }
+    lines.push(`\x1b[1mAuto-detected ${result.candidates.length} contract candidate(s)\x1b[0m`);
+    lines.push(`\x1b[90m${result.filesScanned} files scanned · ${result.crossBoundaryImports.length} cross-boundary import(s)\x1b[0m`);
+    lines.push("");
+    for (const c of result.candidates) {
+        const status = c.coverageState === "current"
+            ? `\x1b[32m✓ current at rev${c.existingContract.revision}\x1b[0m`
+            : c.coverageState === "stale"
+                ? `\x1b[33m⚠ stale at rev${c.existingContract.revision}\x1b[0m`
+                : "\x1b[33m⚠ no contract\x1b[0m";
+        lines.push(`  \x1b[1m${c.name}\x1b[0m  ${status}`);
+        lines.push(`    Source: \x1b[36m${c.sourceFile}\x1b[0m (owned by ${c.sourceAgent})`);
+        lines.push(`    Consumers: ${c.consumers.join(", ")}`);
+        lines.push(`    Shared: ${c.sharedSymbols.map((s) => s.name).join(", ") || "(barrel/re-exports)"}`);
+        if (!c.publishable)
+            lines.push("    \x1b[31mManual declaration required before publishing.\x1b[0m");
+        lines.push("");
+    }
+    const uncovered = result.candidates.filter((c) => c.coverageState !== "current");
+    if (uncovered.length > 0) {
+        lines.push(`\x1b[33m${uncovered.length} uncovered boundary(ies).\x1b[0m Publish with:`);
+        for (const c of uncovered) {
+            lines.push(`  loadout coord contract ${c.name} --agent ${c.sourceAgent} --body "..." --format typescript`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/src/core/coordination/coordinator.js

@@ -240,7 +240,7 @@ function ownershipFromEvents(events) {
             }
             ownership.set(path, {
                 agent: event.from,
-                paths,
+                paths: [path],
                 mode: payload.mode,
                 eventId: event.id,
                 seq: event.seq,
@@ -502,12 +502,13 @@ export function formatSnapshot(snap) {
         lines.push(`File ownership (${snap.ownership.length} paths):`);
         const byAgent = new Map();
         for (const claim of snap.ownership) {
-            const existing = byAgent.get(claim.agent) ?? [];
-            existing.push(...claim.paths);
+            const existing = byAgent.get(claim.agent) ?? new Set();
+            for (const p of claim.paths)
+                existing.add(p);
             byAgent.set(claim.agent, existing);
         }
         for (const [agent, paths] of byAgent) {
-            lines.push(`  ${agent}: ${paths.join(", ")}`);
+            lines.push(`  ${agent}: ${[...paths].join(", ")}`);
         }
         lines.push("");
     }

package/dist/src/core/coordination/daemon.js

@@ -631,8 +631,11 @@ export async function startDaemon(projectRoot, port = 4510) {
             }
         });
         server.listen(port, "127.0.0.1", async () => {
+            // Resolve the actual port (differs from `port` when port === 0)
+            const addr = server.address();
+            const actualPort = typeof addr === "object" && addr ? addr.port : port;
             // Write PID file after successful bind
-            await writePidFile(projectRoot, port);
+            await writePidFile(projectRoot, actualPort);
             // Clean up PID file on exit — only register once per process
             const onExit = () => removePidFile(projectRoot);
             const onTerm = async () => {
@@ -642,9 +645,9 @@ export async function startDaemon(projectRoot, port = 4510) {
             process.once("exit", onExit);
             process.once("SIGTERM", onTerm);
             resolve({
-                port,
+                port: actualPort,
                 token,
-                dashboardUrl: `http://127.0.0.1:${port}/#token=${encodeURIComponent(token)}`,
+                dashboardUrl: `http://127.0.0.1:${actualPort}/#token=${encodeURIComponent(token)}`,
                 close() {
                     process.removeListener("exit", onExit);
                     process.removeListener("SIGTERM", onTerm);