loadout-ai 0.9.0 → 0.9.2

package/dist/src/core/coordination/quick-start.js

@@ -0,0 +1,200 @@
+/**
+ * One-command coordination setup.
+ *
+ * `loadout coord start --agents claude-code,codex` detects the project
+ * structure, assigns file ownership, and prints a ready-to-go status —
+ * replacing the 6-command manual setup.
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { claimOwnership, getOwnership, snapshot, } from "./coordinator.js";
+/** Well-known directory groupings. Order matters — first match wins. */
+const SPLIT_PATTERNS = {
+    "backend/frontend": {
+        label: "backend / frontend",
+        groups: [
+            /^(server|backend|api|src\/api|src\/server|src\/backend|app\/api|packages\/api|packages\/server|packages\/backend|lib|services)/,
+            /^(client|frontend|web|app|src\/app|src\/web|src\/client|src\/frontend|src\/components|src\/pages|src\/views|packages\/web|packages\/client|packages\/frontend|components|pages|views|ui)/,
+        ],
+    },
+    "core/tests": {
+        label: "core / tests",
+        groups: [
+            /^(src|lib|app|packages)/,
+            /^(tests|test|__tests__|spec|specs|e2e|cypress)/,
+        ],
+    },
+};
+async function listTopDirs(projectRoot) {
+    const entries = await readdir(projectRoot, { withFileTypes: true });
+    const dirs = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        if (["dist", "build", "out", "coverage", "test-results", ".next"].includes(entry.name))
+            continue;
+        dirs.push(entry.name);
+    }
+    // Also check src/ subdirectories since many projects keep everything under src/
+    try {
+        const srcEntries = await readdir(join(projectRoot, "src"), {
+            withFileTypes: true,
+        });
+        const nested = [];
+        for (const entry of srcEntries) {
+            if (entry.isDirectory() && !entry.name.startsWith(".")) {
+                nested.push(`src/${entry.name}`);
+            }
+        }
+        if (nested.length > 0) {
+            const srcIndex = dirs.indexOf("src");
+            if (srcIndex >= 0)
+                dirs.splice(srcIndex, 1);
+            dirs.push(...nested);
+        }
+    }
+    catch {
+        // No src/ directory — that's fine.
+    }
+    return dirs;
+}
+function collapsePaths(paths) {
+    const sorted = [...new Set(paths)].sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+    return sorted.filter((path, index) => !sorted
+        .slice(0, index)
+        .some((parent) => path === parent || path.startsWith(`${parent}/`)));
+}
+export async function detectSplit(projectRoot, agents, preferredSplit) {
+    if (agents.some((agent) => !agent.trim()) || agents[0] === agents[1])
+        throw new Error("Coordination requires two distinct, non-empty agents");
+    if (preferredSplit && !SPLIT_PATTERNS[preferredSplit])
+        throw new Error(`Unknown split strategy '${preferredSplit}'`);
+    const dirs = await listTopDirs(projectRoot);
+    // Try preferred split first, then all patterns
+    const order = preferredSplit
+        ? [
+            preferredSplit,
+            ...Object.keys(SPLIT_PATTERNS).filter((k) => k !== preferredSplit),
+        ]
+        : Object.keys(SPLIT_PATTERNS);
+    for (const key of order) {
+        const pattern = SPLIT_PATTERNS[key];
+        if (!pattern)
+            continue;
+        const groupA = dirs.filter((d) => pattern.groups[0].test(d));
+        const groupB = dirs.filter((d) => pattern.groups[1].test(d));
+        if (groupA.length > 0 && groupB.length > 0) {
+            const assigned = new Set([...groupA, ...groupB]);
+            return {
+                assignments: new Map([
+                    [agents[0], collapsePaths(groupA)],
+                    [agents[1], collapsePaths(groupB)],
+                ]),
+                unassigned: dirs.filter((d) => !assigned.has(d)),
+                strategy: pattern.label,
+            };
+        }
+    }
+    // Fallback: even split by directory count
+    const sorted = [...dirs].sort();
+    const mid = Math.ceil(sorted.length / 2);
+    return {
+        assignments: new Map([
+            [agents[0], collapsePaths(sorted.slice(0, mid))],
+            [agents[1], collapsePaths(sorted.slice(mid))],
+        ]),
+        unassigned: [],
+        strategy: "even split (no recognized pattern)",
+    };
+}
+export async function quickStart(projectRoot, agents, options = {}) {
+    const split = await detectSplit(projectRoot, agents, options.split);
+    // Check existing ownership
+    const existing = await getOwnership(projectRoot);
+    const existingOwnership = existing.size > 0;
+    let ownershipClaimed = false;
+    if (!options.dryRun && !existingOwnership) {
+        // Claim ownership for each agent
+        for (const [agent, paths] of split.assignments) {
+            if (paths.length === 0)
+                continue;
+            const claimOptions = {
+                agent,
+                paths,
+                mode: "exclusive",
+                reason: `Auto-assigned by coord start (${split.strategy})`,
+            };
+            await claimOwnership(projectRoot, claimOptions);
+        }
+        ownershipClaimed = true;
+    }
+    // Get snapshot summary
+    const snap = await snapshot(projectRoot, agents[1]);
+    const lines = [];
+    if (snap.activeContracts.length > 0) {
+        lines.push(`${snap.activeContracts.length} contract(s): ${snap.activeContracts.map((c) => `${c.name} rev${c.revision}`).join(", ")}`);
+    }
+    if (snap.ownership.length > 0) {
+        lines.push(`${snap.ownership.length} owned path(s)`);
+    }
+    if (snap.unackedForAgent.length > 0) {
+        lines.push(`${snap.unackedForAgent.length} unacknowledged event(s)`);
+    }
+    return {
+        split,
+        ownershipClaimed,
+        existingOwnership,
+        snapshotSummary: lines.join(" · ") || "empty — ready for first events",
+    };
+}
+// ── Terminal formatting ─────────────────────────────────────────────
+export function formatQuickStart(result) {
+    const lines = [];
+    lines.push("\x1b[1m╔══════════════════════════════════════════╗\x1b[0m");
+    lines.push("\x1b[1m║       COORDINATION READY                 ║\x1b[0m");
+    lines.push("\x1b[1m╚══════════════════════════════════════════╝\x1b[0m");
+    lines.push("");
+    lines.push(`  Strategy: \x1b[36m${result.split.strategy}\x1b[0m`);
+    lines.push("");
+    for (const [agent, paths] of result.split.assignments) {
+        const color = agent.includes("claude") ? "\x1b[36m" : "\x1b[33m";
+        lines.push(`  ${color}${agent}\x1b[0m`);
+        for (const p of paths) {
+            lines.push(`    \x1b[90m└─\x1b[0m ${p}/`);
+        }
+        lines.push("");
+    }
+    if (result.split.unassigned.length > 0) {
+        lines.push("  \x1b[90mUnassigned (shared):\x1b[0m");
+        for (const p of result.split.unassigned) {
+            lines.push(`    \x1b[90m└─\x1b[0m ${p}/`);
+        }
+        lines.push("");
+    }
+    if (result.existingOwnership) {
+        lines.push("  \x1b[33m⚠ Existing ownership detected — skipped auto-assignment.\x1b[0m");
+        lines.push("    Run \x1b[90mloadout coord status\x1b[0m to see current ownership.");
+    }
+    else if (result.ownershipClaimed) {
+        lines.push("  \x1b[32m✓ Ownership claimed for both agents.\x1b[0m");
+    }
+    else {
+        lines.push("  \x1b[90mDry run — no ownership claimed. Add --yes to apply.\x1b[0m");
+    }
+    lines.push("");
+    lines.push("\x1b[90m─────────────────────────────────────────────\x1b[0m");
+    lines.push("");
+    lines.push("  \x1b[1mWhat each agent should do now:\x1b[0m");
+    lines.push("");
+    const agentList = [...result.split.assignments.keys()];
+    lines.push(`  1. Open \x1b[36m${agentList[0]}\x1b[0m → it checks its snapshot and starts working`);
+    lines.push(`  2. Open \x1b[33m${agentList[1]}\x1b[0m → it sees the ownership split and builds against contracts`);
+    lines.push("  3. When either creates/changes a shared interface → it publishes a contract");
+    lines.push("  4. The other agent sees the contract on its next snapshot check");
+    lines.push("");
+    lines.push("  The \x1b[90mloadout-handoff\x1b[0m skill handles steps 1-4 automatically.");
+    lines.push("  Just tell each agent what to build — it runs the coord commands for you.");
+    return lines.join("\n");
+}

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

@@ -9,6 +9,8 @@ import { readFile, writeFile, rename, stat, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { assertCoordinationEnabled, readCoordLog } from "./coordinator.js";
 import { withCoordinationLock } from "./lock.js";
+/** Event types whose latest value defines current system state. */
+const STATE_BEARING_TYPES = new Set(["ownership", "contract", "decision"]);
 const COORD_DIR = ".handoff";
 const COORD_LOG = "coordination.jsonl";
 export const DEFAULT_RETENTION = {
@@ -34,8 +36,12 @@ export async function compact(projectRoot, config = DEFAULT_RETENTION) {
         const ageStart = firstFresh === -1 ? log.events.length : firstFresh;
         const countStart = Math.max(0, log.events.length - config.maxEvents);
         const keepStart = Math.max(ageStart, countStart);
-        const remove = log.events.slice(0, keepStart);
-        const finalRetained = log.events.slice(keepStart);
+        const removable = log.events.slice(0, keepStart);
+        const keptByIndex = log.events.slice(keepStart);
+        // Preserve state-bearing events that would otherwise be lost.
+        const stateCheckpoints = extractStateCheckpoints(removable, keptByIndex);
+        const finalRetained = [...stateCheckpoints, ...keptByIndex];
+        const remove = removable.filter((e) => !stateCheckpoints.includes(e));
         if (remove.length === 0) {
             return {
                 before: log.events.length,
@@ -82,9 +88,19 @@ export async function compact(projectRoot, config = DEFAULT_RETENTION) {
             payload: summaryPayload,
         });
         const lines = [
-            summaryLine,
-            ...finalRetained.map((e) => JSON.stringify(e)),
-        ].join("\n");
+            ...stateCheckpoints.map((event) => ({
+                seq: event.seq,
+                line: JSON.stringify(event),
+            })),
+            { seq: remove[remove.length - 1].seq, line: summaryLine },
+            ...keptByIndex.map((event) => ({
+                seq: event.seq,
+                line: JSON.stringify(event),
+            })),
+        ]
+            .sort((left, right) => left.seq - right.seq)
+            .map(({ line }) => line)
+            .join("\n");
         // Atomic write: write to temp, rename over
         const tmpPath = `${logPath}.tmp`;
         await writeFile(tmpPath, lines + "\n", {
@@ -126,3 +142,49 @@ export async function logSize(projectRoot) {
         throw error;
     }
 }
+/**
+ * Extract the latest state-bearing events from the removable set that are not
+ * already represented in the kept set. Ownership, contracts, and decisions
+ * define current system state — losing them during compaction would silently
+ * drop ownership claims, contract revisions, or active decisions.
+ */
+function extractStateCheckpoints(removable, kept) {
+    const keptKeys = new Set();
+    for (const e of kept) {
+        const key = stateKey(e);
+        if (key)
+            keptKeys.add(key);
+    }
+    // Walk removable in reverse to find the *latest* event per state key.
+    const seen = new Set();
+    const checkpoints = [];
+    for (let i = removable.length - 1; i >= 0; i--) {
+        const e = removable[i];
+        const key = stateKey(e);
+        if (!key)
+            continue;
+        if (keptKeys.has(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        checkpoints.push(e);
+    }
+    // Return in original chronological order.
+    return checkpoints.reverse();
+}
+function stateKey(event) {
+    if (!STATE_BEARING_TYPES.has(event.type) || !event.payload)
+        return undefined;
+    const p = event.payload;
+    switch (event.type) {
+        case "ownership":
+            // Key by agent + sorted paths — an ownership event replaces the previous
+            // one for the same agent/path combination.
+            return `ownership:${event.from}:${[...(p.paths ?? [])].sort().join(",")}`;
+        case "contract":
+            return `contract:${p.name}`;
+        case "decision":
+            return `decision:${p.title}`;
+        default:
+            return undefined;
+    }
+}

package/dist/src/core/delegation/handoff-bundle.js

@@ -0,0 +1,253 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readFile, realpath, rm } from "node:fs/promises";
+import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { redactString } from "../coordination/redaction.js";
+export const HANDOFF_BUNDLE_MAX_FILES = 20;
+export const HANDOFF_BUNDLE_MAX_FILE_BYTES = 32 * 1024;
+export const HANDOFF_BUNDLE_MAX_TOTAL_BYTES = 50 * 1024;
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const handoffBundleFileSchema = z
+    .object({
+    path: z
+        .string()
+        .trim()
+        .min(1)
+        .refine((path) => !path.startsWith("/") &&
+        !path.split("/").includes("..") &&
+        ![".git", ".handoff"].includes(path.split("/")[0] ?? ""), "must be a safe project-relative source path"),
+    sourceBytes: z.number().int().nonnegative(),
+    storedBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(HANDOFF_BUNDLE_MAX_FILE_BYTES),
+    sourceSha256: sha256Schema,
+    isTruncated: z.boolean(),
+    content: z.string(),
+})
+    .strict();
+const handoffBundleSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    createdAt: z.iso.datetime({ offset: true }),
+    files: z
+        .array(handoffBundleFileSchema)
+        .min(1)
+        .max(HANDOFF_BUNDLE_MAX_FILES),
+})
+    .strict()
+    .superRefine((bundle, context) => {
+    let total = 0;
+    bundle.files.forEach((file, index) => {
+        const actual = Buffer.byteLength(file.content);
+        if (actual !== file.storedBytes) {
+            context.addIssue({
+                code: "custom",
+                path: ["files", index, "storedBytes"],
+                message: "does not match the UTF-8 content byte length",
+            });
+        }
+        total += actual;
+    });
+    if (total > HANDOFF_BUNDLE_MAX_TOTAL_BYTES) {
+        context.addIssue({
+            code: "custom",
+            path: ["files"],
+            message: `stored content exceeds ${HANDOFF_BUNDLE_MAX_TOTAL_BYTES} bytes`,
+        });
+    }
+});
+export const handoffBundleReferenceSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    path: z.string().regex(/^\.handoff\/bundles\/[a-f0-9-]+\.json$/),
+    fileCount: z.number().int().min(1).max(HANDOFF_BUNDLE_MAX_FILES),
+    storedBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(HANDOFF_BUNDLE_MAX_TOTAL_BYTES),
+    isTruncated: z.boolean(),
+})
+    .strict();
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+async function assertNoSymlinkComponents(root, relativePath, allowMissing) {
+    let current = root;
+    let finalInfo;
+    for (const segment of relativePath.split("/")) {
+        current = join(current, segment);
+        try {
+            finalInfo = await lstat(current);
+        }
+        catch (error) {
+            if (allowMissing && errorCode(error) === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        if (finalInfo.isSymbolicLink())
+            throw new Error(`Bundle path cannot use a symlink: ${relativePath}`);
+    }
+    return finalInfo;
+}
+async function readBoundedTextFile(absolute, path, maximumBytes) {
+    const hash = createHash("sha256");
+    const utf8Validator = new TextDecoder("utf-8", { fatal: true });
+    const captured = [];
+    let capturedBytes = 0;
+    let sourceBytes = 0;
+    try {
+        for await (const value of createReadStream(absolute)) {
+            const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            sourceBytes += chunk.byteLength;
+            hash.update(chunk);
+            utf8Validator.decode(chunk, { stream: true });
+            if (chunk.includes(0))
+                throw new Error(`Bundle path appears to be binary: ${path}`);
+            if (capturedBytes < maximumBytes) {
+                const remaining = maximumBytes - capturedBytes;
+                const part = chunk.subarray(0, remaining);
+                captured.push(part);
+                capturedBytes += part.byteLength;
+            }
+        }
+        utf8Validator.decode();
+    }
+    catch (error) {
+        if (error instanceof Error && /appears to be binary/.test(error.message))
+            throw error;
+        if (error instanceof TypeError)
+            throw new Error(`Bundle path appears to be binary: ${path}`);
+        throw error;
+    }
+    const prefix = Buffer.concat(captured);
+    let decoded = "";
+    let trim = 0;
+    for (; trim <= Math.min(3, prefix.byteLength); trim += 1) {
+        try {
+            decoded = new TextDecoder("utf-8", { fatal: true }).decode(prefix.subarray(0, prefix.byteLength - trim));
+            break;
+        }
+        catch {
+            // A bounded prefix can end in the middle of one UTF-8 code point.
+        }
+    }
+    if (trim > Math.min(3, prefix.byteLength))
+        throw new Error(`Bundle path appears to be binary: ${path}`);
+    const redacted = redactString(decoded);
+    const redactedBytes = Buffer.from(redacted);
+    let content = redacted;
+    if (redactedBytes.byteLength > maximumBytes) {
+        for (let remove = 0; remove <= 3; remove += 1) {
+            try {
+                content = new TextDecoder("utf-8", { fatal: true }).decode(redactedBytes.subarray(0, maximumBytes - remove));
+                break;
+            }
+            catch {
+                // Keep trimming until the byte cap lands on a UTF-8 boundary.
+            }
+        }
+    }
+    const storedBytes = Buffer.byteLength(content);
+    return {
+        sourceBytes,
+        sourceSha256: hash.digest("hex"),
+        content,
+        storedBytes,
+        isTruncated: sourceBytes > capturedBytes ||
+            trim > 0 ||
+            redactedBytes.byteLength > maximumBytes,
+    };
+}
+function projectRelativePath(projectRoot, requestedPath) {
+    if (!requestedPath.trim())
+        throw new Error("Bundle path cannot be empty");
+    if (isAbsolute(requestedPath))
+        throw new Error(`Bundle path must be project-relative: ${requestedPath}`);
+    const root = resolve(projectRoot);
+    const absolute = resolve(root, requestedPath);
+    const local = relative(root, absolute);
+    if (!local || local === ".." || local.startsWith(`..${sep}`))
+        throw new Error(`Bundle path must stay inside the project: ${requestedPath}`);
+    const normalized = local.split(sep).join(posix.sep);
+    const firstSegment = normalized.split(posix.sep)[0];
+    if (firstSegment === ".git" || firstSegment === ".handoff")
+        throw new Error(`Bundle path cannot read Loadout or Git internal state: ${requestedPath}`);
+    return normalized;
+}
+export async function createHandoffBundle(projectRoot, requestedPaths) {
+    if (!requestedPaths.length)
+        throw new Error("Bundle requires at least one file");
+    if (requestedPaths.length > HANDOFF_BUNDLE_MAX_FILES)
+        throw new Error(`Bundle accepts at most ${HANDOFF_BUNDLE_MAX_FILES} files`);
+    const files = [];
+    const canonicalRoot = await realpath(projectRoot);
+    let totalStoredBytes = 0;
+    for (const requestedPath of requestedPaths) {
+        const path = projectRelativePath(projectRoot, requestedPath);
+        const absolute = resolve(canonicalRoot, path);
+        const info = await assertNoSymlinkComponents(canonicalRoot, path, false);
+        if (!info)
+            throw new Error(`Bundle path does not exist: ${path}`);
+        if (!info.isFile())
+            throw new Error(`Bundle path is not a file: ${path}`);
+        const remaining = HANDOFF_BUNDLE_MAX_TOTAL_BYTES - totalStoredBytes;
+        const snapshot = await readBoundedTextFile(absolute, path, Math.min(HANDOFF_BUNDLE_MAX_FILE_BYTES, remaining));
+        files.push({
+            path,
+            ...snapshot,
+        });
+        totalStoredBytes += snapshot.storedBytes;
+    }
+    const bundle = {
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        files,
+    };
+    const id = randomUUID();
+    const path = `.handoff/bundles/${id}.json`;
+    await assertNoSymlinkComponents(canonicalRoot, ".handoff/bundles", true);
+    await writeFileAtomically(resolve(projectRoot, path), `${JSON.stringify(bundle, null, 2)}\n`);
+    return {
+        schemaVersion: 1,
+        path,
+        fileCount: files.length,
+        storedBytes: totalStoredBytes,
+        isTruncated: files.some((file) => file.isTruncated),
+    };
+}
+export async function readHandoffBundle(projectRoot, reference) {
+    const validReference = handoffBundleReferenceSchema.parse(reference);
+    const canonicalRoot = await realpath(projectRoot);
+    await assertNoSymlinkComponents(canonicalRoot, validReference.path, false);
+    const raw = await readFile(resolve(canonicalRoot, validReference.path), "utf8");
+    let bundle;
+    try {
+        bundle = handoffBundleSchema.parse(JSON.parse(raw));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "unparseable JSON";
+        throw new Error(`Invalid handoff bundle '${validReference.path}': ${reason}`);
+    }
+    const storedBytes = bundle.files.reduce((total, file) => total + file.storedBytes, 0);
+    const isTruncated = bundle.files.some((file) => file.isTruncated);
+    if (validReference.fileCount !== bundle.files.length ||
+        validReference.storedBytes !== storedBytes ||
+        validReference.isTruncated !== isTruncated) {
+        throw new Error(`Handoff bundle reference does not match '${validReference.path}'`);
+    }
+    return bundle;
+}
+/** Remove only a schema-valid bundle path, used to roll back a failed send. */
+export async function removeHandoffBundle(projectRoot, reference) {
+    const validReference = handoffBundleReferenceSchema.parse(reference);
+    const canonicalRoot = await realpath(projectRoot);
+    await assertNoSymlinkComponents(canonicalRoot, validReference.path, true);
+    await rm(resolve(canonicalRoot, validReference.path), { force: true });
+}