@rryando/arcs 3.0.0

package/dist/cli/commands/loop.js

@@ -0,0 +1,192 @@
+// ---------------------------------------------------------------------------
+// Loop commands — start, cancel, status, tick (registry-based)
+// ---------------------------------------------------------------------------
+import { existsSync } from "node:fs";
+import { cancelLoop, clearLoopState, findActiveLoop, incrementLoopIteration, readLoopState, startLoop, } from "../../utils/loop-state.js";
+import { getProjectDir } from "../../utils/paths.js";
+import { defineCommand, ERROR_CODES, } from "../command-registry.js";
+import { failure, success } from "../output-envelope.js";
+// ---------------------------------------------------------------------------
+// loop start
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "loop start",
+    description: "Start an iterative loop for a project session",
+    mutation: true,
+    params: {
+        slug: { type: "string", required: true, positional: 0, description: "Project slug" },
+        prompt: { type: "string", required: true, description: "Loop prompt text" },
+        session: { type: "string", required: true, description: "Session ID" },
+        "max-iterations": { type: "number", default: 100, description: "Maximum iteration count" },
+        "completion-promise": {
+            type: "string",
+            default: "DONE",
+            description: "Completion promise tag",
+        },
+        strategy: {
+            type: "string",
+            enum: ["continue", "reset"],
+            default: "continue",
+            description: "Loop strategy",
+        },
+    },
+    handler: handleLoopStart,
+});
+async function handleLoopStart(params, flags) {
+    const slug = params.slug;
+    const prompt = params.prompt;
+    const session = params.session;
+    const maxIterations = params["max-iterations"] ?? 100;
+    const completionPromise = params["completion-promise"] ?? "DONE";
+    const strategy = params.strategy ?? "continue";
+    const projectDir = getProjectDir(slug);
+    if (!existsSync(projectDir)) {
+        return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found`);
+    }
+    if (flags.dryRun) {
+        return success({
+            dryRun: true,
+            wouldStart: { slug, session, prompt, maxIterations, completionPromise, strategy },
+        });
+    }
+    try {
+        const state = await startLoop(projectDir, {
+            sessionId: session,
+            prompt,
+            maxIterations,
+            completionPromise,
+            strategy,
+            projectSlug: slug,
+        });
+        return success({ message: `Loop started for project "${slug}"`, state });
+    }
+    catch (err) {
+        return failure("loop_error", err instanceof Error ? err.message : String(err));
+    }
+}
+// ---------------------------------------------------------------------------
+// loop cancel
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "loop cancel",
+    description: "Cancel an active loop for a project session",
+    mutation: true,
+    params: {
+        slug: { type: "string", required: true, positional: 0, description: "Project slug" },
+        session: { type: "string", required: true, description: "Session ID to cancel" },
+    },
+    handler: handleLoopCancel,
+});
+async function handleLoopCancel(params, flags) {
+    const slug = params.slug;
+    const session = params.session;
+    const projectDir = getProjectDir(slug);
+    if (!existsSync(projectDir)) {
+        return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found`);
+    }
+    if (flags.dryRun) {
+        return success({ dryRun: true, wouldCancel: { slug, session } });
+    }
+    try {
+        const cancelled = await cancelLoop(projectDir, session);
+        return success({ slug, session, cancelled });
+    }
+    catch (err) {
+        return failure("loop_error", err instanceof Error ? err.message : String(err));
+    }
+}
+// ---------------------------------------------------------------------------
+// loop status
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "loop status",
+    description: "Show loop status for a project or find active loop globally",
+    mutation: false,
+    params: {
+        slug: {
+            type: "string",
+            required: false,
+            positional: 0,
+            description: "Project slug (omit to find any active loop)",
+        },
+    },
+    handler: handleLoopStatus,
+});
+async function handleLoopStatus(params, _flags) {
+    const slug = params.slug;
+    try {
+        if (slug) {
+            const projectDir = getProjectDir(slug);
+            if (!existsSync(projectDir)) {
+                return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found`);
+            }
+            const state = await readLoopState(projectDir);
+            return success({ slug, state });
+        }
+        const active = await findActiveLoop();
+        if (active) {
+            return success({ slug: active.slug, state: active.state });
+        }
+        return success({ message: "No active loop found.", state: null });
+    }
+    catch (err) {
+        return failure("loop_error", err instanceof Error ? err.message : String(err));
+    }
+}
+// ---------------------------------------------------------------------------
+// loop tick
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "loop tick",
+    description: "Atomically increment loop iteration and return updated state",
+    mutation: true,
+    params: {
+        slug: { type: "string", required: true, positional: 0, description: "Project slug" },
+        session: { type: "string", required: true, description: "Session ID (must match active loop)" },
+    },
+    handler: handleLoopTick,
+});
+async function handleLoopTick(params, flags) {
+    const slug = params.slug;
+    const session = params.session;
+    const projectDir = getProjectDir(slug);
+    if (!existsSync(projectDir)) {
+        return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found`);
+    }
+    const state = await readLoopState(projectDir);
+    if (!state?.active) {
+        return failure("loop_error", `No active loop for project "${slug}"`);
+    }
+    if (state.sessionId !== session) {
+        return failure("loop_error", `Session mismatch: loop owns "${state.sessionId}", got "${session}"`);
+    }
+    // Check max iterations before incrementing
+    if (typeof state.maxIterations === "number" && state.iteration >= state.maxIterations) {
+        if (flags.dryRun) {
+            return success({
+                dryRun: true,
+                wouldClear: { slug, session, reason: "max_iterations_reached" },
+            });
+        }
+        await clearLoopState(projectDir);
+        return success({ slug, session, maxReached: true, iteration: state.iteration, state: null });
+    }
+    if (flags.dryRun) {
+        return success({
+            dryRun: true,
+            wouldTick: { slug, session, nextIteration: state.iteration + 1 },
+        });
+    }
+    const updated = await incrementLoopIteration(projectDir);
+    if (!updated) {
+        return failure("loop_error", "Failed to increment loop iteration");
+    }
+    return success({
+        slug,
+        session,
+        iteration: updated.iteration,
+        maxReached: false,
+        state: updated,
+    });
+}
+//# sourceMappingURL=loop.js.map

package/dist/cli/commands/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../../src/cli/commands/loop.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/maintenance.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/cli/commands/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/maintenance.ts"],"names":[],"mappings":""}

package/dist/cli/commands/maintenance.js

@@ -0,0 +1,231 @@
+// ---------------------------------------------------------------------------
+// Maintenance commands — git-log, sync-agents-md (registry-based)
+// ---------------------------------------------------------------------------
+import { existsSync, readFileSync } from "node:fs";
+import { lstat, readFile, symlink, unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { extractDependenciesContent, extractInProgressTasks, extractOverviewContent, } from "../../utils/content-assembly.js";
+import { readRootMeta } from "../../utils/dag.js";
+import { getGitLog, isGitRepo } from "../../utils/git.js";
+import { readJsonSafe, validateJson } from "../../utils/json.js";
+import { projectMetaSchema } from "../../utils/json-schemas.js";
+import { getDataDir, getProjectDir } from "../../utils/paths.js";
+import { readPlanIndex } from "../../utils/project-memory.js";
+import { defineCommand, ERROR_CODES, } from "../command-registry.js";
+import { failure, success } from "../output-envelope.js";
+// ---------------------------------------------------------------------------
+// git-log
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "git-log",
+    description: "Show git commit history for a project workspace",
+    mutation: false,
+    params: {
+        slug: { type: "string", required: true, positional: 0, description: "Project slug" },
+        since: { type: "string", description: "Git commit hash or ISO date to start from" },
+        limit: { type: "number", default: 20, description: "Max number of commits to return" },
+    },
+    handler: handleGitLog,
+});
+async function handleGitLog(params, _flags) {
+    const slug = params.slug;
+    const since = params.since;
+    const limit = params.limit ?? 20;
+    const projectDir = getProjectDir(slug);
+    const metaPath = resolve(projectDir, "meta.json");
+    if (!existsSync(metaPath)) {
+        return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found`);
+    }
+    const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+    const workspacePaths = meta.workspacePaths ?? [];
+    if (workspacePaths.length === 0) {
+        return failure("missing_param", `Project "${slug}" has no workspace paths configured`);
+    }
+    const cwd = workspacePaths[0];
+    if (!isGitRepo(cwd)) {
+        return success({ commits: [], info: "Workspace path is not a git repository" });
+    }
+    const commits = getGitLog(cwd, { since, limit });
+    return success(commits);
+}
+// ---------------------------------------------------------------------------
+// sync-agents-md
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "sync-agents-md",
+    description: "Regenerate AGENTS.md from analysis data",
+    mutation: true,
+    params: {
+        slug: { type: "string", required: true, positional: 0, description: "Project slug" },
+        "analysis-file": { type: "string", required: true, description: "Path to JSON analysis file" },
+    },
+    handler: handleSyncAgentsMd,
+});
+async function handleSyncAgentsMd(params, flags) {
+    const slug = params.slug;
+    const analysisFile = params["analysis-file"];
+    if (flags.dryRun) {
+        return success({ dryRun: true, wouldSync: { slug, analysisFile } });
+    }
+    if (!existsSync(analysisFile)) {
+        return failure("missing_param", `Analysis file not found: ${analysisFile}`);
+    }
+    let analysis;
+    try {
+        const raw = readFileSync(analysisFile, "utf-8");
+        analysis = JSON.parse(raw);
+    }
+    catch {
+        return failure("invalid_type", `Could not parse analysis file as JSON: ${analysisFile}`);
+    }
+    const codebaseAnalysis = analysis;
+    if (!codebaseAnalysis.directoryStructure ||
+        !codebaseAnalysis.fileNaming ||
+        !codebaseAnalysis.codePatterns ||
+        !codebaseAnalysis.techStack) {
+        return failure("invalid_type", "Analysis file must contain directoryStructure, fileNaming, codePatterns, and techStack fields");
+    }
+    try {
+        const dataDir = getDataDir();
+        const rootMeta = await readRootMeta(dataDir);
+        const projectNode = rootMeta.projects.find((p) => p.id === slug);
+        if (!projectNode) {
+            return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found`);
+        }
+        const projectDir = getProjectDir(slug);
+        const metaPath = resolve(projectDir, "meta.json");
+        const rawMeta = await readJsonSafe(metaPath);
+        if (rawMeta === undefined) {
+            return failure("internal_error", `Could not read project meta at ${metaPath}`);
+        }
+        const meta = validateJson(rawMeta, projectMetaSchema, metaPath);
+        const name = meta.name ?? slug;
+        const workspacePaths = Array.isArray(meta.workspacePaths)
+            ? meta.workspacePaths
+            : [];
+        if (workspacePaths.length === 0) {
+            return failure("missing_param", `Project "${slug}" has no workspace paths configured`);
+        }
+        // Build preamble
+        const preamble = `# AGENTS.md — ${name}\n\n> Auto-generated by ARCS. Do not edit manually.\n> Regenerate: \`arcs sync-agents-md ${slug} --analysis-file=<path>\`\n\n---\n\n## Coding Discipline\n\nYou are working in an existing codebase maintained by a team.\nYour code must be indistinguishable from the team's existing code.`;
+        // Build analysis sections
+        const analysisSections = [];
+        analysisSections.push(`\n## Tech Stack\n\n${codebaseAnalysis.techStack}`);
+        analysisSections.push(`\n## Directory Structure\n\n${codebaseAnalysis.directoryStructure}`);
+        analysisSections.push(`\n## File Naming Conventions\n\n${codebaseAnalysis.fileNaming}`);
+        analysisSections.push(`\n## Code Patterns\n\n${codebaseAnalysis.codePatterns}`);
+        if (codebaseAnalysis.testingPatterns?.trim()) {
+            analysisSections.push(`\n## Testing Patterns\n\n${codebaseAnalysis.testingPatterns}`);
+        }
+        if (codebaseAnalysis.additionalNotes?.trim()) {
+            analysisSections.push(`\n## Additional Notes\n\n${codebaseAnalysis.additionalNotes}`);
+        }
+        // Build project context
+        const contextSections = [];
+        const overviewPath = resolve(projectDir, "overview.md");
+        if (existsSync(overviewPath)) {
+            const overviewRaw = await readFile(overviewPath, "utf-8");
+            const overviewContent = extractOverviewContent(overviewRaw);
+            if (overviewContent)
+                contextSections.push(`\n## Project Overview\n\n${overviewContent}`);
+        }
+        const tasksPath = resolve(projectDir, "tasks.md");
+        if (existsSync(tasksPath)) {
+            const tasksRaw = await readFile(tasksPath, "utf-8");
+            const inProgress = extractInProgressTasks(tasksRaw);
+            if (inProgress.length > 0)
+                contextSections.push(`\n## Current Focus\n\n${inProgress.join("\n")}`);
+        }
+        const depsPath = resolve(projectDir, "dependencies.md");
+        if (existsSync(depsPath)) {
+            const depsRaw = await readFile(depsPath, "utf-8");
+            const depsContent = extractDependenciesContent(depsRaw);
+            if (depsContent)
+                contextSections.push(`\n## Dependencies\n\n${depsContent}`);
+        }
+        const planIndex = await readPlanIndex(projectDir);
+        const activePlans = planIndex.plans.filter((p) => p.status === "in_progress" || p.status === "planned");
+        if (activePlans.length > 0) {
+            const bullets = activePlans
+                .map((p) => `- **${p.title}** (${p.status})${p.summary ? `: ${p.summary}` : ""}`)
+                .join("\n");
+            contextSections.push(`\n## Active Plans\n\n${bullets}`);
+        }
+        const content = `${preamble}\n\n---${analysisSections.join("")}\n${contextSections.length > 0 ? `\n---${contextSections.join("")}` : ""}\n`;
+        // Write source and symlink
+        const sourcePath = resolve(projectDir, "AGENTS.md");
+        await writeFile(sourcePath, content, "utf-8");
+        const symlinked = [];
+        const warnings = [];
+        for (const wsPath of workspacePaths) {
+            if (!existsSync(wsPath)) {
+                warnings.push(`Warning: workspace path "${wsPath}" does not exist, skipped.`);
+                continue;
+            }
+            const linkPath = join(wsPath, "AGENTS.md");
+            try {
+                await lstat(linkPath);
+                await unlink(linkPath);
+            }
+            catch {
+                /* does not exist */
+            }
+            await symlink(sourcePath, linkPath);
+            symlinked.push(linkPath);
+        }
+        return success({ sourcePath, symlinked, warnings });
+    }
+    catch (err) {
+        return failure("internal_error", err instanceof Error ? err.message : String(err));
+    }
+}
+// ---------------------------------------------------------------------------
+// graphify-sync
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "graphify-sync",
+    description: "Re-extract codebase graph and ingest new structural knowledge",
+    mutation: true,
+    params: {
+        slug: { type: "string", required: true, positional: 0, description: "Project slug" },
+    },
+    handler: handleGraphifySync,
+});
+async function handleGraphifySync(params, _flags) {
+    const slug = params.slug;
+    const projectDir = getProjectDir(slug);
+    const metaPath = join(projectDir, "meta.json");
+    if (!existsSync(metaPath)) {
+        return failure(ERROR_CODES.PROJECT_NOT_FOUND, `Project "${slug}" not found.`);
+    }
+    const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+    const workspacePaths = meta.workspacePaths ?? [];
+    if (workspacePaths.length === 0) {
+        return failure("missing_param", "No workspace paths configured for this project.");
+    }
+    const { detectGraphify, runExtraction, ingestGraph } = await import("../../utils/graphify.js");
+    const { persistProposals } = await import("../../utils/graphify-knowledge.js");
+    const info = detectGraphify();
+    if (!info.available) {
+        return failure("internal_error", "graphify is not available on PATH.");
+    }
+    const workspace = workspacePaths[0];
+    const extraction = runExtraction(workspace);
+    if (!extraction.success) {
+        return failure("internal_error", `Extraction failed: ${extraction.error ?? "unknown error"}`);
+    }
+    const { proposals, stats } = ingestGraph(extraction.graphJsonPath, slug);
+    let created = 0;
+    if (proposals.length > 0) {
+        const result = await persistProposals(slug, proposals);
+        created = result.created;
+    }
+    return success({
+        workspace,
+        graphJsonPath: extraction.graphJsonPath,
+        stats,
+        proposed: proposals.length,
+        created,
+    });
+}
+//# sourceMappingURL=maintenance.js.map

package/dist/cli/commands/maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.js","sourceRoot":"","sources":["../../../src/cli/commands/maintenance.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/next.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=next.d.ts.map

package/dist/cli/commands/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/next.ts"],"names":[],"mappings":""}

package/dist/cli/commands/next.js

@@ -0,0 +1,116 @@
+// ---------------------------------------------------------------------------
+// next — Tell the user what to work on next with relevant context
+// ---------------------------------------------------------------------------
+import { buildProjectRetrievalIndex } from "../../retrieval/index-builder.js";
+import { listTasks, readKnowledgeIndex, readPlanIndex } from "../../utils/project-memory.js";
+import { resolveProject } from "../../utils/project-resolver.js";
+import { deriveOperatingBrief } from "../../utils/workflow-policy.js";
+import { defineCommand } from "../command-registry.js";
+import { success } from "../output-envelope.js";
+// ---------------------------------------------------------------------------
+defineCommand({
+    path: "next",
+    description: "Show the next task to work on with relevant context",
+    params: {
+        slug: {
+            type: "string",
+            positional: 0,
+            description: "Project slug or path",
+        },
+    },
+    handler: handleNext,
+});
+// ---------------------------------------------------------------------------
+async function handleNext(params, flags) {
+    const rawArg = params.slug;
+    const resolved = await resolveProject(rawArg);
+    if (!resolved.ok)
+        return resolved.result;
+    const { slug, projectDir } = resolved;
+    const [allTasks, planIndex, retrievalIndex] = await Promise.all([
+        listTasks(projectDir),
+        readPlanIndex(projectDir),
+        buildProjectRetrievalIndex(slug),
+    ]);
+    const openTasks = allTasks.filter((t) => t.status !== "done" && t.status !== "cancelled");
+    if (openTasks.length === 0) {
+        if (flags.json) {
+            return success({ message: "Nothing to do. All tasks complete or no active plans." });
+        }
+        return success("Nothing to do. All tasks complete or no active plans.");
+    }
+    const brief = deriveOperatingBrief({
+        tasks: allTasks.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            planId: t.planId,
+            priority: t.priority,
+        })),
+        plans: planIndex.plans.map((p) => ({ id: p.id, title: p.title, status: p.status })),
+    });
+    // Pick the top open task — prefer in_progress, then backlog by priority order
+    const priorityOrder = { high: 0, medium: 1, low: 2 };
+    const sorted = [...openTasks].sort((a, b) => {
+        if (a.status === "in_progress" && b.status !== "in_progress")
+            return -1;
+        if (b.status === "in_progress" && a.status !== "in_progress")
+            return 1;
+        const pa = priorityOrder[a.priority ?? "medium"] ?? 1;
+        const pb = priorityOrder[b.priority ?? "medium"] ?? 1;
+        return pa - pb;
+    });
+    const task = sorted[0];
+    const plan = task.planId ? planIndex.plans.find((p) => p.id === task.planId) : undefined;
+    const contextParts = [];
+    if (plan?.summary)
+        contextParts.push(plan.summary);
+    if (brief.why)
+        contextParts.push(brief.why);
+    const context = contextParts.join(" ") || `Work on: ${task.title}`;
+    const doneCommand = `arcs done ${slug} ${task.id}`;
+    // Fetch top 2 related knowledge entries
+    const knowledgeResults = retrievalIndex.searchKnowledge(task.title, 2);
+    const relatedKnowledge = knowledgeResults.map((r) => ({
+        id: r.id,
+        title: r.title,
+        kind: r.kind ?? "lesson",
+    }));
+    // Also pull kind from the index for gotcha prefixing
+    const knowledgeIndex = await readKnowledgeIndex(projectDir);
+    const enrichedRelated = relatedKnowledge.map((rk) => {
+        const entry = knowledgeIndex.entries.find((e) => e.id === rk.id);
+        return { id: rk.id, title: rk.title, kind: entry?.kind ?? "lesson" };
+    });
+    if (flags.json) {
+        return success({
+            task: {
+                id: task.id,
+                title: task.title,
+                status: task.status,
+                priority: task.priority ?? "medium",
+            },
+            context,
+            planTitle: plan?.title ?? null,
+            command: doneCommand,
+            relatedKnowledge: enrichedRelated,
+        });
+    }
+    const knowledgeLines = enrichedRelated.map((rk) => {
+        const prefix = rk.kind === "gotcha" ? "⚠️  Watch out:" : "ℹ️ ";
+        return `  ${prefix} ${rk.title}`;
+    });
+    const lines = [
+        `Next: ${task.title}`,
+        plan ? `Plan: ${plan.title}` : "",
+        `Priority: ${task.priority ?? "medium"}`,
+        "",
+        "Context:",
+        context,
+        ...(knowledgeLines.length > 0 ? ["", "Related knowledge:", ...knowledgeLines] : []),
+        "",
+        `When done: ${doneCommand}`,
+    ].filter((l, i) => i === 0 || l !== "" || i > 3);
+    return success(lines.join("\n"));
+}
+//# sourceMappingURL=next.js.map

package/dist/cli/commands/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../../../src/cli/commands/next.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/plan.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plan.d.ts.map

package/dist/cli/commands/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/plan.ts"],"names":[],"mappings":""}