@arungeorgesaji/assembly 0.1.0

package/src/orchestrator.js

@@ -0,0 +1,221 @@
+import { createAgentRunner } from "./agent-runner.js";
+import { resolveApproval } from "./approval.js";
+import { applyFileUpdates, validateAdditiveFileUpdates } from "./file-updates.js";
+import { applyPatch } from "./patch.js";
+import { createPlan } from "./planner.js";
+import { createFinalReport } from "./report.js";
+import { validateTaskResult } from "./result-validation.js";
+import { validatePlan } from "./validation.js";
+import { runVerificationCommands } from "./verification-runner.js";
+import {
+  appendEvent,
+  createRunId,
+  initializeRun,
+  readRun,
+  writeArtifact,
+  writeRunFile,
+  writeState,
+} from "./run-store.js";
+
+export async function createRun(request, { rootDir = process.cwd(), agentRunner, metadata = {} } = {}) {
+  const resolvedAgentRunner = agentRunner ?? createAgentRunner();
+  const plan = createPlan(request, { rootDir });
+  const errors = validatePlan(plan);
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+
+  const runId = createRunId();
+  const state = await initializeRun({ runId, request: plan.request, plan, metadata }, rootDir);
+
+  await executeReadyTasks({ runId, plan, state, rootDir, agentRunner: resolvedAgentRunner });
+
+  return { runId, plan, state };
+}
+
+async function executeReadyTasks({ runId, plan, state, rootDir, agentRunner }) {
+  state.status = "running";
+  await writeState(runId, state, rootDir);
+  await appendEvent(runId, { type: "run.started" }, rootDir);
+
+  while (true) {
+    const task = nextReadyTask(plan, state);
+    if (!task) {
+      break;
+    }
+
+    state.currentTaskId = task.id;
+    state.tasks[task.id].status = "in_progress";
+    await writeState(runId, state, rootDir);
+    await appendEvent(runId, { type: "task.started", taskId: task.id }, rootDir);
+
+    let result;
+    try {
+      result = await agentRunner(task, { rootDir, plan, state, runId });
+    } catch (error) {
+      const failure = {
+        taskId: task.id,
+        status: "failed",
+        summary: "Agent execution failed.",
+        changedFiles: [],
+        artifacts: [],
+        risks: [error.message],
+      };
+      state.tasks[task.id].status = "failed";
+      state.currentTaskId = null;
+      await writeState(runId, state, rootDir);
+      await appendEvent(runId, { type: "task.failed", taskId: task.id, data: failure }, rootDir);
+      break;
+    }
+    const resultErrors = validateTaskResult(task, result);
+    resultErrors.push(...(await validateAdditiveFileUpdates(task, result, rootDir)));
+    await writeArtifact(runId, task.id, "result.json", result, rootDir);
+    if (result.patch) {
+      await writeRunFile(runId, `artifacts/${task.id}/patch.diff`, result.patch, rootDir);
+    }
+    if (result.fileUpdates?.length > 0) {
+      await writeArtifact(runId, task.id, "file-updates.json", result.fileUpdates, rootDir);
+    }
+
+    if (resultErrors.length > 0) {
+      const failure = {
+        taskId: task.id,
+        status: "failed",
+        summary: "Agent result failed contract validation.",
+        changedFiles: [],
+        artifacts: ["result.json"],
+        risks: resultErrors,
+      };
+      state.tasks[task.id].status = "failed";
+      state.currentTaskId = null;
+      await writeArtifact(runId, task.id, "validation-errors.json", { errors: resultErrors }, rootDir);
+      await writeState(runId, state, rootDir);
+      await appendEvent(runId, { type: "task.failed", taskId: task.id, data: failure }, rootDir);
+      break;
+    }
+
+    const approval = resolveApproval({ task, result });
+    await appendEvent(runId, { type: `approval.${approval.status}`, taskId: task.id, data: approval }, rootDir);
+    if (!approval.approved) {
+      const status = approval.status === "dry_run" || approval.status === "pending" ? "blocked" : "failed";
+      const failure = {
+        taskId: task.id,
+        status,
+        summary: approval.reason,
+        changedFiles: result.changedFiles,
+        artifacts: result.artifacts,
+        risks: [approval.reason],
+      };
+      state.tasks[task.id].status = status;
+      state.currentTaskId = null;
+      await writeState(runId, state, rootDir);
+      await appendEvent(runId, { type: `task.${status}`, taskId: task.id, data: failure }, rootDir);
+      break;
+    }
+
+    if (result.status === "complete" && result.fileUpdates?.length > 0) {
+      try {
+        await applyFileUpdates(result.fileUpdates, rootDir);
+        await appendEvent(runId, { type: "files.updated", taskId: task.id, data: { changedFiles: result.changedFiles } }, rootDir);
+      } catch (error) {
+        const failure = {
+          taskId: task.id,
+          status: "failed",
+          summary: "File updates failed to apply.",
+          changedFiles: result.changedFiles,
+          artifacts: ["result.json", "file-updates.json"],
+          risks: [error.message],
+        };
+        state.tasks[task.id].status = "failed";
+        state.currentTaskId = null;
+        await writeArtifact(runId, task.id, "file-update-errors.json", { error: error.message }, rootDir);
+        await writeState(runId, state, rootDir);
+        await appendEvent(runId, { type: "task.failed", taskId: task.id, data: failure }, rootDir);
+        break;
+      }
+    }
+
+    if (result.status === "complete" && result.patch) {
+      try {
+        await applyPatch(result.patch, rootDir);
+        await appendEvent(runId, { type: "patch.applied", taskId: task.id, data: { changedFiles: result.changedFiles } }, rootDir);
+      } catch (error) {
+        const failure = {
+          taskId: task.id,
+          status: "failed",
+          summary: "Patch failed to apply.",
+          changedFiles: result.changedFiles,
+          artifacts: ["result.json", "patch.diff"],
+          risks: [error.message],
+        };
+        state.tasks[task.id].status = "failed";
+        state.currentTaskId = null;
+        await writeArtifact(runId, task.id, "patch-errors.json", { error: error.message }, rootDir);
+        await writeState(runId, state, rootDir);
+        await appendEvent(runId, { type: "task.failed", taskId: task.id, data: failure }, rootDir);
+        break;
+      }
+    }
+
+    if (result.status === "complete" && task.owner === "implementation-agent" && plan.verification.length > 0) {
+      await runVerification(runId, plan, rootDir);
+    }
+
+    state.tasks[task.id].status = result.status;
+    state.currentTaskId = null;
+    await writeState(runId, state, rootDir);
+    await appendEvent(runId, { type: `task.${result.status}`, taskId: task.id, data: result }, rootDir);
+
+    if (result.status !== "complete") {
+      break;
+    }
+  }
+
+  state.status = determineRunStatus(state);
+
+  if (state.status === "complete" && hasFailedVerification(await readRun(runId, rootDir))) {
+    state.status = "failed";
+  }
+
+  await writeState(runId, state, rootDir);
+  await appendEvent(runId, { type: `run.${state.status}` }, rootDir);
+
+  const run = await readRun(runId, rootDir);
+  await writeRunFile(runId, "final-report.md", createFinalReport(run), rootDir);
+}
+
+async function runVerification(runId, plan, rootDir) {
+  await appendEvent(runId, { type: "verification.started", data: { commands: plan.verification } }, rootDir);
+  const verificationResults = await runVerificationCommands(plan.verification, rootDir);
+  await writeArtifact(runId, "verification", "result.json", verificationResults, rootDir);
+  await appendEvent(runId, { type: "verification.completed", data: { results: verificationResults } }, rootDir);
+}
+
+function hasFailedVerification(run) {
+  return run.events
+    .filter((event) => event.type === "verification.completed")
+    .some((event) => event.data.results.some((result) => result.exitCode !== 0));
+}
+
+function nextReadyTask(plan, state) {
+  return plan.tasks.find((task) => {
+    if (state.tasks[task.id].status !== "pending") {
+      return false;
+    }
+    return task.dependencies.every((dependency) => state.tasks[dependency]?.status === "complete");
+  });
+}
+
+function allTasksComplete(state) {
+  return Object.values(state.tasks).every((task) => task.status === "complete");
+}
+
+function determineRunStatus(state) {
+  if (allTasksComplete(state)) {
+    return "complete";
+  }
+  if (Object.values(state.tasks).some((task) => task.status === "failed")) {
+    return "failed";
+  }
+  return "blocked";
+}

package/src/patch.js

@@ -0,0 +1,78 @@
+import { spawn } from "node:child_process";
+
+import { validateChangedFilesWithinScope } from "./scope.js";
+
+export function extractPatchChangedFiles(patch) {
+  const files = new Set();
+
+  for (const line of String(patch ?? "").split(/\r?\n/)) {
+    if (line.startsWith("diff --git ")) {
+      const match = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+      if (match) {
+        files.add(match[1]);
+        files.add(match[2]);
+      }
+      continue;
+    }
+
+    if (line.startsWith("+++ ") || line.startsWith("--- ")) {
+      const rawPath = line.slice(4).trim().split(/\t/)[0];
+      if (rawPath === "/dev/null") {
+        continue;
+      }
+      files.add(rawPath.replace(/^a\//, "").replace(/^b\//, ""));
+    }
+  }
+
+  return [...files].sort();
+}
+
+export function validatePatchForTask(task, result) {
+  const errors = [];
+  if (!result.patch) {
+    return errors;
+  }
+
+  const patchFiles = extractPatchChangedFiles(result.patch);
+  if (patchFiles.length === 0) {
+    errors.push(`task ${task.id} patch does not include changed files`);
+    return errors;
+  }
+
+  errors.push(...validateChangedFilesWithinScope(task, patchFiles));
+
+  const declaredFiles = new Set(result.changedFiles);
+  for (const patchFile of patchFiles) {
+    if (!declaredFiles.has(patchFile)) {
+      errors.push(`task ${task.id} patch changes ${patchFile} but result.changedFiles does not list it`);
+    }
+  }
+
+  return errors;
+}
+
+export async function applyPatch(patch, rootDir = process.cwd()) {
+  await runGitApply(["apply", "--check", "-"], patch, rootDir);
+  await runGitApply(["apply", "-"], patch, rootDir);
+}
+
+function runGitApply(args, patch, rootDir) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, { cwd: rootDir });
+    let stderr = "";
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(stderr.trim() || `git ${args.join(" ")} failed with code ${code}`));
+      }
+    });
+
+    child.stdin.end(patch);
+  });
+}

package/src/planner.js

@@ -0,0 +1,279 @@
+import { attachAgentProfiles } from "./agent-profiles.js";
+import { createExecutionPlan, createTask } from "./models.js";
+import { inspectRepository } from "./repo-inspector.js";
+
+export function createPlan(request, { rootDir = process.cwd(), repoContext = inspectRepository(rootDir) } = {}) {
+  const normalizedRequest = normalizeRequest(request);
+  const slug = slugify(normalizedRequest);
+  const implementationScope = repoContext.suggestedScopes.implementation;
+  const reviewScope = repoContext.suggestedScopes.review;
+  const verification = repoContext.verificationCommands;
+  const changePolicy = normalizedRequest.toLowerCase().startsWith("add ") ? "additive" : "modify";
+  const requestKind = classifyRequest(normalizedRequest);
+  const targetContext = inferTargetContext(normalizedRequest, repoContext);
+  const implementationTasks = createImplementationTasks({
+    slug,
+    requestKind,
+    implementationScope,
+    changePolicy,
+    targetContext,
+  });
+
+  const baseTasks = [
+    createTask({
+      id: `${slug}-plan`,
+      title: "Define implementation plan",
+      owner: "planner",
+      description:
+        `Inspect the ${repoContext.language ?? "unknown"} repository, clarify scope, and produce task ownership with acceptance criteria.`,
+      files: ["README.md"],
+      scope: {
+        paths: ["README.md"],
+        allowlist: [],
+        denylist: [".env", ".env.*", ".git/"],
+      },
+      acceptanceCriteria: [
+        "Plan lists owned files or systems for each task.",
+        "Plan identifies blockers, dependencies, and verification steps.",
+        "Plan uses repository structure to narrow implementation and review scope where possible.",
+      ],
+    }),
+    ...implementationTasks,
+    createTask({
+      id: `${slug}-verify`,
+      title: "Verify and review output",
+      owner: "review-agent",
+      description:
+        "Run relevant checks, review the diff, and summarize risks before human handoff.",
+      scope: reviewScope,
+      dependencies: implementationTasks.map((task) => task.id),
+      acceptanceCriteria: [
+        "Automated checks pass or failures are documented.",
+        "Review notes include known risks and follow-up recommendations.",
+      ],
+    }),
+  ];
+  const { tasks, agentProfiles } = attachAgentProfiles(baseTasks);
+
+  return createExecutionPlan({
+    request: normalizedRequest,
+    summary: `Coordinate delivery for: ${normalizedRequest}`,
+    tasks,
+    agentProfiles,
+    risks: [
+      targetContext.files.length > 0
+        ? `Planner inferred likely target files: ${targetContext.files.join(", ")}.`
+        : "Planner could not infer exact target files; implementation scope remains broader.",
+      "Planner is deterministic and repository-aware; deeper semantic decomposition is still evolving.",
+    ],
+    verification,
+  });
+}
+
+function classifyRequest(request) {
+  const lower = request.toLowerCase();
+  if (/\b(readme|docs?|documentation)\b/.test(lower)) {
+    return "docs";
+  }
+  if (/\b(test|tests|coverage|spec)\b/.test(lower)) {
+    return "tests";
+  }
+  if (/\b(refactor|cleanup|rename)\b/.test(lower)) {
+    return "refactor";
+  }
+  return "code";
+}
+
+function createImplementationTasks({ slug, requestKind, implementationScope, changePolicy, targetContext }) {
+  if (requestKind === "docs") {
+    const docsScope = targetContext.docs.length > 0
+      ? scopeForFiles(targetContext.docs, [".env", ".env.*", ".git/", ".assembly/"])
+      : {
+          paths: [],
+          allowlist: ["README.md"],
+          denylist: [".env", ".env.*", ".git/", ".assembly/"],
+        };
+    return [
+      createTask({
+        id: `${slug}-docs`,
+        title: "Update documentation",
+        owner: "implementation-agent",
+        description: "Make the requested documentation change while preserving unrelated content.",
+        scope: docsScope,
+        changePolicy,
+        dependencies: [`${slug}-plan`],
+        acceptanceCriteria: [
+          "Documentation change directly addresses the request.",
+          "Unrelated documentation content remains intact.",
+        ],
+      }),
+    ];
+  }
+
+  if (requestKind === "tests") {
+    const testScope = targetContext.tests.length > 0
+      ? scopeForFiles(targetContext.tests, [".env", ".env.*", ".git/", ".assembly/"])
+      : {
+          paths: ["tests/"],
+          allowlist: ["package.json", "package-lock.json"],
+          denylist: [".env", ".env.*", ".git/", ".assembly/"],
+        };
+    return [
+      createTask({
+        id: `${slug}-tests`,
+        title: "Update tests",
+        owner: "implementation-agent",
+        description: "Add or update tests for the requested behavior.",
+        scope: testScope,
+        changePolicy,
+        dependencies: [`${slug}-plan`],
+        acceptanceCriteria: [
+          "Tests cover the requested behavior or regression.",
+          "Test changes stay within the assigned test scope.",
+        ],
+      }),
+    ];
+  }
+
+  if (requestKind === "refactor") {
+    return [
+      createTask({
+        id: `${slug}-refactor`,
+        title: "Refactor implementation",
+        owner: "implementation-agent",
+        description: "Refactor the relevant implementation while preserving behavior.",
+        scope: targetContext.implementation.length > 0
+          ? scopeForFiles(targetContext.implementation, [".env", ".env.*", ".git/", ".assembly/"])
+          : implementationScope,
+        changePolicy,
+        dependencies: [`${slug}-plan`],
+        acceptanceCriteria: [
+          "Behavior remains unchanged unless the request explicitly says otherwise.",
+          "Refactor stays inside the assigned ownership scope.",
+        ],
+      }),
+    ];
+  }
+
+  const codeScope = targetContext.implementation.length > 0
+    ? scopeForFiles(targetContext.implementation, [".env", ".env.*", ".git/", ".assembly/"])
+    : implementationScope;
+  const tasks = [
+    createTask({
+      id: `${slug}-implement`,
+      title: "Implement requested change",
+      owner: "implementation-agent",
+      description:
+        "Make the smallest coherent code changes needed to satisfy the approved plan.",
+      scope: codeScope,
+      changePolicy,
+      dependencies: [`${slug}-plan`],
+      acceptanceCriteria: [
+        "Changes are limited to the assigned ownership area.",
+        "Implementation satisfies the request and preserves existing behavior.",
+      ],
+    }),
+  ];
+
+  if (targetContext.tests.length > 0) {
+    tasks.push(createTask({
+      id: `${slug}-tests`,
+      title: "Update targeted tests",
+      owner: "implementation-agent",
+      description: "Update tests directly related to the inferred implementation target.",
+      scope: scopeForFiles(targetContext.tests, [".env", ".env.*", ".git/", ".assembly/"]),
+      changePolicy,
+      dependencies: [`${slug}-implement`],
+      acceptanceCriteria: [
+        "Tests cover the requested behavior or regression.",
+        "Test changes correspond to the inferred implementation target.",
+      ],
+    }));
+  }
+
+  return tasks;
+}
+
+function inferTargetContext(request, repoContext) {
+  const sourceFiles = repoContext.sourceFiles ?? [];
+  const testFiles = repoContext.testFiles ?? [];
+  const docs = repoContext.documentationFiles ?? [];
+  const configFiles = repoContext.configFiles ?? [];
+  const candidates = [...sourceFiles, ...testFiles, ...docs, ...configFiles];
+  const terms = new Set(tokenize(request));
+  const mentionedFiles = candidates.filter((file) => fileMatchesTerms(file, terms));
+  const implementation = mentionedFiles.filter((file) => file.startsWith("src/") || isConfigFile(file));
+  const tests = [
+    ...mentionedFiles.filter((file) => file.startsWith("tests/")),
+    ...findRelatedTestFiles(implementation, testFiles),
+  ];
+
+  return {
+    files: unique([...implementation, ...tests, ...mentionedFiles.filter((file) => docs.includes(file))]),
+    implementation: unique(implementation),
+    tests: unique(tests),
+    docs: unique(mentionedFiles.filter((file) => docs.includes(file))),
+  };
+}
+
+function tokenize(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 3 && !GENERIC_MATCH_TERMS.has(token));
+}
+
+const GENERIC_MATCH_TERMS = new Set([
+  "add",
+  "change",
+  "code",
+  "docs",
+  "file",
+  "fix",
+  "for",
+  "implementation",
+  "improve",
+  "src",
+  "test",
+  "tests",
+  "update",
+]);
+
+function fileMatchesTerms(file, terms) {
+  const fileTokens = tokenize(file);
+  return fileTokens.some((token) => terms.has(token));
+}
+
+function findRelatedTestFiles(implementationFiles, testFiles) {
+  const implementationTerms = new Set(implementationFiles.flatMap((file) => tokenize(file)));
+  return testFiles.filter((file) => tokenize(file).some((token) => implementationTerms.has(token)));
+}
+
+function scopeForFiles(files, denylist) {
+  return {
+    paths: [],
+    allowlist: unique(files).sort(),
+    denylist,
+  };
+}
+
+function isConfigFile(file) {
+  return /(^|\/)(package(-lock)?\.json|\.gitignore|eslint|prettier|tsconfig|vite|webpack|rollup)/i.test(file);
+}
+
+function unique(values) {
+  return [...new Set(values)].sort();
+}
+
+function normalizeRequest(request) {
+  const normalized = String(request ?? "").trim().replace(/\s+/g, " ");
+  if (!normalized) {
+    throw new Error("request cannot be empty");
+  }
+  return normalized;
+}
+
+function slugify(value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug.slice(0, 32).replace(/-$/g, "") || "request";
+}

package/src/repo-inspector.js

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+export function inspectRepository(rootDir = process.cwd()) {
+  const files = listTopLevelFiles(rootDir);
+  const hasPackageJson = files.includes("package.json");
+  const hasTests = existsSync(path.join(rootDir, "tests"));
+  const allFiles = listRepositoryFiles(rootDir);
+  const packageJson = readPackageJson(rootDir);
+
+  return {
+    rootDir,
+    files,
+    sourceFiles: allFiles.filter((file) => file.startsWith("src/")),
+    testFiles: allFiles.filter((file) => file.startsWith("tests/")),
+    documentationFiles: allFiles.filter((file) => /(^|\/)(readme|docs?|documentation)|\.md$/i.test(file)),
+    configFiles: allFiles.filter((file) => /(^|\/)(package(-lock)?\.json|\.gitignore|eslint|prettier|tsconfig|vite|webpack|rollup)/i.test(file)),
+    language: hasPackageJson ? "javascript" : "unknown",
+    packageManager: hasPackageJson ? "npm" : null,
+    scripts: packageJson?.scripts ?? {},
+    verificationCommands: hasPackageJson ? ["npm test"] : [],
+    suggestedScopes: {
+      implementation: {
+        paths: ["src/", "tests/"],
+        allowlist: ["package.json", "package-lock.json", "README.md", ".gitignore"],
+        denylist: [".env", ".env.*", ".git/", ".assembly/"],
+      },
+      review: {
+        paths: hasTests ? ["tests/", ".assembly/"] : [".assembly/"],
+        allowlist: ["README.md"],
+        denylist: [".env", ".env.*", ".git/"],
+      },
+    },
+  };
+}
+
+function listTopLevelFiles(rootDir) {
+  try {
+    return readdirSync(rootDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() || entry.isDirectory())
+      .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function listRepositoryFiles(rootDir) {
+  const ignoredDirectories = new Set([".git", ".assembly", "node_modules", "dist", "build", "coverage"]);
+  const results = [];
+
+  function visit(relativeDir = "") {
+    const absoluteDir = path.join(rootDir, relativeDir);
+    let entries;
+    try {
+      entries = readdirSync(absoluteDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") && ![".gitignore"].includes(entry.name)) {
+        continue;
+      }
+      const relativePath = path.posix.join(relativeDir.split(path.sep).join(path.posix.sep), entry.name);
+      if (entry.isDirectory()) {
+        if (!ignoredDirectories.has(entry.name)) {
+          visit(relativePath);
+        }
+        continue;
+      }
+      if (entry.isFile()) {
+        results.push(relativePath);
+      }
+    }
+  }
+
+  visit();
+  return results.sort();
+}
+
+function readPackageJson(rootDir) {
+  try {
+    return JSON.parse(readFileSync(path.join(rootDir, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}