@warpgogol/forge 2.7.0 → 2.8.1

package/os/adr/handlers/implement-stamp.ts

@@ -0,0 +1,331 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0727: adr.implement.stamp — the exclusive atomic path for
+accepted/proposed → implemented ADR transitions. Validates preconditions
+and atomically mutates ADR frontmatter.
+</purpose>
+<non-goals>
+  <item>Does not transition ADRs not in accepted or proposed status.</item>
+  <item>Does not add acceptance criteria or evidence checks — ADRs do not have these.</item>
+  <item>Does not call the GitHub API or require network access.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0727: initial implementation — mirrors rfc.implement.stamp for ADRs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { execFile } from "node:child_process";
+import { readFile, unlink, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+import { writeFileAtomic } from "../../../src/utils/fs-atomic.ts";
+
+import { listAdrFiles, readAndParseAdr, adrFileMatchesId } from "../frontmatter-io.ts";
+import { ADR_DIR } from "../types.ts";
+import type { AdrStatus, AdrImplementStampViolation, AdrImplementStampResult } from "../types.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+
+// ─── Git helpers ─────────────────────────────────────────────────────────────
+
+function execGit(workspaceRoot: string, args: string[]): Promise<string> {
+  return new Promise((resolve) => {
+    execFile("git", args, { cwd: workspaceRoot, timeout: 10000 }, (err, stdout) => {
+      if (err) {
+        resolve("");
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+async function isAdrFileClean(workspaceRoot: string, adrRelPath: string): Promise<boolean> {
+  const status = await execGit(workspaceRoot, ["status", "--porcelain", "--", adrRelPath]);
+  return status.length === 0;
+}
+
+async function commitReachableFromHead(workspaceRoot: string, commitSha: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile(
+      "git",
+      ["merge-base", "--is-ancestor", commitSha, "HEAD"],
+      { cwd: workspaceRoot, timeout: 10000 },
+      (err) => {
+        resolve(!err);
+      },
+    );
+  });
+}
+
+async function commitReferencesAdr(
+  workspaceRoot: string,
+  commitSha: string,
+  adrId: string,
+): Promise<boolean> {
+  const commitMsg = await execGit(workspaceRoot, ["log", "-1", "--format=%B", commitSha]);
+  if (commitMsg.includes(adrId)) return true;
+
+  const changedFiles = await execGit(workspaceRoot, [
+    "show",
+    "--name-only",
+    "--format=",
+    commitSha,
+  ]);
+  const slug = adrId.toLowerCase();
+  if (changedFiles.toLowerCase().includes(slug)) return true;
+
+  return false;
+}
+
+// ─── ADR-specific exclusive lock ─────────────────────────────────────────────
+
+function lockFilePath(workspaceRoot: string, adrId: string): string {
+  const slug = adrId.toLowerCase();
+  return join(workspaceRoot, ".adr-locks", `${slug}.lock`);
+}
+
+async function acquireAdrLock(
+  workspaceRoot: string,
+  adrId: string,
+): Promise<{ acquired: boolean; lockPath: string }> {
+  const lockPath = lockFilePath(workspaceRoot, adrId);
+  const lockDir = dirname(lockPath);
+  await mkdir(lockDir, { recursive: true });
+
+  const { open } = await import("node:fs/promises");
+  try {
+    const handle = await open(lockPath, "wx");
+    await handle.writeFile(
+      JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }),
+    );
+    await handle.close();
+    return { acquired: true, lockPath };
+  } catch {
+    return { acquired: false, lockPath };
+  }
+}
+
+async function releaseAdrLock(lockPath: string): Promise<void> {
+  try {
+    await unlink(lockPath);
+  } catch {
+    // Lock file already removed — safe
+  }
+}
+
+// ─── Frontmatter mutation ────────────────────────────────────────────────────
+
+function mutateAdrFrontmatter(
+  source: string,
+  status: "implemented",
+  implementedAt: string,
+  updatedAt: string,
+): string {
+  let content = source;
+
+  content = content.replace(/^status: \w+$/m, `status: ${status}`);
+
+  if (/^implementedAt:.*$/m.test(content)) {
+    content = content.replace(/^implementedAt:.*$/m, `implementedAt: ${implementedAt}`);
+  } else {
+    content = content.replace(
+      /^updatedAt: .*$/m,
+      `updatedAt: ${updatedAt}\nimplementedAt: ${implementedAt}`,
+    );
+  }
+
+  content = content.replace(/^updatedAt: .*$/m, `updatedAt: ${updatedAt}`);
+
+  return content;
+}
+
+function toIsoDate(date: Date): string {
+  return date.toISOString().split("T")[0]!;
+}
+
+// ─── Main handler ────────────────────────────────────────────────────────────
+
+export async function runAdrImplementStamp(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<AdrImplementStampResult>> {
+  const { workspaceRoot, logger, outputFormat, dryRun } = context;
+  const adrDirPath = join(workspaceRoot, ADR_DIR);
+
+  const targetId = input.flags["id"] as string | undefined;
+  const implementationCommit = input.flags["implementation-commit"] as string | undefined;
+
+  // ── Flag validation ───────────────────────────────────────────────────────
+  if (!targetId) {
+    throw new Error("adr.implement.stamp requires --id flag (e.g. --id ADR-0003).");
+  }
+  if (!implementationCommit) {
+    throw new Error(
+      "adr.implement.stamp requires --implementation-commit flag (the SHA of the implementation commit).",
+    );
+  }
+
+  const violations: AdrImplementStampViolation[] = [];
+  const isDryRun = dryRun || input.flags["dry-run"] === true;
+
+  // ── Find the target ADR ───────────────────────────────────────────────────
+  const files = await listAdrFiles(adrDirPath);
+  const targetFile = files.find((f) => adrFileMatchesId(f, targetId));
+
+  if (!targetFile) {
+    violations.push({
+      rule: "ADR-IMP-01",
+      message: `ADR ${targetId} not found in ${ADR_DIR}.`,
+    });
+    return stampFailResult(violations, isDryRun, outputFormat, logger);
+  }
+
+  const targetParsed = await readAndParseAdr(adrDirPath, targetFile);
+  if (!targetParsed) {
+    violations.push({
+      rule: "ADR-IMP-01",
+      message: `Could not parse target ADR ${targetId}.`,
+    });
+    return stampFailResult(violations, isDryRun, outputFormat, logger);
+  }
+
+  const fm = targetParsed.parsed.frontmatter;
+  const currentStatus = String(fm["status"] ?? "") as AdrStatus;
+
+  // ── ADR-IMP-01: must be in accepted or proposed status ─────────────────────
+  if (currentStatus !== "accepted" && currentStatus !== "proposed") {
+    violations.push({
+      rule: "ADR-IMP-01",
+      message: `ADR ${targetId} has status "${currentStatus}" — only "accepted" or "proposed" ADRs can be stamped to "implemented".`,
+    });
+    return stampFailResult(violations, isDryRun, outputFormat, logger);
+  }
+
+  // ── ADR-IMP-04: ADR file must be clean (no uncommitted edits to the target ADR) ──
+  const adrRelPath = join(ADR_DIR, targetFile);
+  const adrFileClean = await isAdrFileClean(workspaceRoot, adrRelPath);
+  if (!adrFileClean) {
+    violations.push({
+      rule: "ADR-IMP-04",
+      message: `ADR file ${adrRelPath} has uncommitted changes. Commit the ADR file before stamping.`,
+    });
+  }
+
+  // ── ADR-IMP-03: implementation commit validation ──────────────────────────
+  const reachable = await commitReachableFromHead(workspaceRoot, implementationCommit);
+  if (!reachable) {
+    violations.push({
+      rule: "ADR-IMP-03",
+      message: `Implementation commit ${implementationCommit} is not reachable from HEAD. The commit must be an ancestor of the current HEAD.`,
+    });
+  } else {
+    const referencesAdr = await commitReferencesAdr(workspaceRoot, implementationCommit, targetId);
+    if (!referencesAdr) {
+      violations.push({
+        rule: "ADR-IMP-03",
+        message: `Implementation commit ${implementationCommit} does not reference ${targetId} in its message or changed files.`,
+      });
+    }
+  }
+
+  // If any violations found, return without mutation
+  if (violations.length > 0) {
+    return stampFailResult(violations, isDryRun, outputFormat, logger);
+  }
+
+  // ── ADR-IMP-05: acquire ADR-specific exclusive lock ───────────────────────
+  const { acquired, lockPath } = await acquireAdrLock(workspaceRoot, targetId);
+  if (!acquired) {
+    violations.push({
+      rule: "ADR-IMP-05",
+      message: `A concurrent stamp operation is in progress for ${targetId}. Wait for it to complete and retry.`,
+    });
+    return stampFailResult(violations, isDryRun, outputFormat, logger);
+  }
+
+  try {
+    // ── Atomic mutation ──────────────────────────────────────────────────────
+    const adrFilePath = join(adrDirPath, targetFile);
+    const adrSource = await readFile(adrFilePath, "utf-8");
+
+    const today = toIsoDate(new Date());
+    const stampedAt = new Date().toISOString();
+    const mutatedSource = mutateAdrFrontmatter(adrSource, "implemented", today, today);
+
+    if (isDryRun) {
+      if (outputFormat === "pretty") {
+        logger.success(`[dry-run] ${targetId} would be stamped as implemented`);
+        logger.info(`  implementation commit: ${implementationCommit}`);
+        logger.info(`  stamped at: ${stampedAt}`);
+      }
+      return {
+        data: {
+          command: "adr.implement.stamp",
+          status: "pass",
+          data: {
+            adrId: targetId,
+            implementationCommit,
+            stampedAt,
+          },
+          violations: [],
+        },
+        exitCode: 0,
+        summary: `adr.implement.stamp: dry-run — ${targetId} would be stamped`,
+      };
+    }
+
+    await writeFileAtomic(adrFilePath, mutatedSource);
+
+    if (outputFormat === "pretty") {
+      logger.success(`${targetId} stamped as implemented`);
+      logger.info(`  implementation commit: ${implementationCommit}`);
+      logger.info(`  stamped at: ${stampedAt}`);
+    }
+
+    return {
+      data: {
+        command: "adr.implement.stamp",
+        status: "pass",
+        data: {
+          adrId: targetId,
+          implementationCommit,
+          stampedAt,
+        },
+        violations: [],
+      },
+      exitCode: 0,
+      summary: `adr.implement.stamp: ${targetId} stamped as implemented`,
+    };
+  } finally {
+    await releaseAdrLock(lockPath);
+  }
+}
+
+function stampFailResult(
+  violations: AdrImplementStampViolation[],
+  isDryRun: boolean,
+  outputFormat: string,
+  logger: { warn: (msg: string) => void; info: (msg: string) => void },
+): ForgeCommandResult<AdrImplementStampResult> {
+  const prefix = isDryRun ? "[dry-run] " : "";
+  if (outputFormat === "pretty") {
+    for (const v of violations) {
+      logger.warn(`${prefix}${v.rule}: ${v.message}`);
+    }
+  }
+  return {
+    data: {
+      command: "adr.implement.stamp",
+      status: "fail",
+      violations,
+    },
+    exitCode: 1,
+    summary: `${prefix}adr.implement.stamp: ${violations.length} violation(s)`,
+  };
+}

package/os/adr/handlers/list-create.ts

@@ -0,0 +1,207 @@
+/*
+<MODULE_CONTRACT>
+<purpose>ADR list and create handlers mirroring the RFC domain.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0366: create ADR list and create handlers mirroring the RFC domain.</item>
+  <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { toKebabCase } from "../../../src/utils/string-utils.ts";
+import { listAdrFiles, readAndParseAdr } from "../frontmatter-io.ts";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import type {
+  AdrListEntry,
+  AdrListResult,
+  AdrCreateResult,
+  AdrStatus,
+  AdrScope,
+} from "../types.ts";
+import { ADR_DIR, ADR_TEMPLATE_FILE, ADR_SCOPES, ADR_STATUSES } from "../types.ts";
+
+function toIsoDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+export async function runAdrList(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<AdrListResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const adrDirPath = path.join(workspaceRoot, ADR_DIR);
+
+  const filterStatus = input.flags["status"] as string | undefined;
+  const filterScope = input.flags["scope"] as string | undefined;
+  const filterDecider = input.flags["decider"] as string | undefined;
+
+  const files = await listAdrFiles(adrDirPath);
+  const entries: AdrListEntry[] = [];
+
+  for (const fileName of files) {
+    const result = await readAndParseAdr(adrDirPath, fileName);
+    if (!result) continue;
+
+    const fm = result.parsed.frontmatter;
+    const id = String(fm["id"] ?? "");
+    const status = String(fm["status"] ?? "") as AdrStatus;
+    const scope = String(fm["scope"] ?? "") as AdrScope;
+    const decider = String(fm["decider"] ?? "");
+
+    if (filterStatus && status !== filterStatus) continue;
+    if (filterScope && scope !== filterScope) continue;
+    if (filterDecider && decider !== filterDecider) continue;
+
+    entries.push({
+      id,
+      title: String(fm["title"] ?? ""),
+      status,
+      scope,
+      decider,
+      updatedAt: String(fm["updatedAt"] ?? ""),
+      file: path.join(ADR_DIR, fileName),
+    });
+  }
+
+  if (outputFormat === "pretty") {
+    if (entries.length === 0) {
+      logger.info("No ADRs found matching the given filters.");
+    } else {
+      logger.section(`ADRs (${entries.length})`);
+      for (const entry of entries) {
+        logger.info(
+          `${entry.id}  ${entry.status.padEnd(12)} ${entry.scope.padEnd(10)} ${entry.decider.padEnd(20)} ${entry.title}`,
+        );
+      }
+    }
+  }
+
+  return {
+    data: {
+      command: "adr.list",
+      status: "ok",
+      count: entries.length,
+      entries,
+    },
+    summary: `${entries.length} ADR(s) found`,
+  };
+}
+
+export async function runAdrCreate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<AdrCreateResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const adrDirPath = path.join(workspaceRoot, ADR_DIR);
+
+  const title = input.flags["title"] as string | undefined;
+  if (!title) {
+    throw new Error(
+      'adr.create requires --title flag, e.g. --title="Use DuckDB for local analytics"',
+    );
+  }
+
+  const scope = (input.flags["scope"] as string | undefined) ?? "package";
+  const decider = (input.flags["decider"] as string | undefined) ?? "architecture";
+  const status = (input.flags["status"] as string | undefined) ?? "proposed";
+  const relatedRaw = input.flags["related"] as string | undefined;
+
+  if (!ADR_SCOPES.includes(scope as AdrScope)) {
+    throw new Error(`Invalid scope: ${scope}. Must be one of: ${ADR_SCOPES.join(", ")}`);
+  }
+  if (!ADR_STATUSES.includes(status as AdrStatus)) {
+    throw new Error(`Invalid status: ${status}. Must be one of: ${ADR_STATUSES.join(", ")}`);
+  }
+
+  const files = await listAdrFiles(adrDirPath);
+  let maxId = 0;
+  for (const f of files) {
+    const basename = path.basename(f);
+    const match = basename.match(/^adr-(\d{4})/);
+    if (match) {
+      const num = parseInt(match[1]!, 10);
+      if (num > maxId) maxId = num;
+    }
+  }
+  const nextNum = maxId + 1;
+  const paddedNum = String(nextNum).padStart(4, "0");
+  const nextSlug = `adr-${paddedNum}`;
+  const nextId = `ADR-${paddedNum}`;
+
+  const templateRelPath = ADR_TEMPLATE_FILE;
+  const templatePath = path.join(workspaceRoot, templateRelPath);
+  let templateContent: string;
+  try {
+    templateContent = await fs.readFile(templatePath, "utf-8");
+  } catch {
+    throw new Error(
+      `ADR template not found at ${templateRelPath}. Ensure docs/adrs/ contains the template.`,
+    );
+  }
+
+  const today = toIsoDate(new Date());
+  const kebabTitle = toKebabCase(title);
+  const fileName = `${nextSlug}-${kebabTitle}.md`;
+
+  let content = templateContent;
+  content = content.replace(/^id: ADR-0000$/m, `id: ${nextId}`);
+  const escapedTitle = title.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  content = content.replace(/^title: ".*"$/m, `title: "${escapedTitle}"`);
+  content = content.replace(/^status: \w+$/m, `status: ${status}`);
+  content = content.replace(/^scope: \w+$/m, `scope: ${scope}`);
+  content = content.replace(/^decider: \w+$/m, `decider: ${decider}`);
+  content = content.replace(/^createdAt: YYYY-MM-DD$/m, `createdAt: ${today}`);
+  content = content.replace(/^updatedAt: YYYY-MM-DD$/m, `updatedAt: ${today}`);
+  content = content.replace(/^# ADR-0000: .+$/m, `# ${nextId}: ${title}`);
+
+  const relatedIds = relatedRaw
+    ? relatedRaw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+  if (relatedIds.length > 0) {
+    content = content.replace(
+      /^related:\s*\n\s*- RFC-0001\s*$/m,
+      `related:\n${relatedIds.map((id) => `  - ${id}`).join("\n")}`,
+    );
+  } else {
+    content = content.replace(/^related:\s*\n\s*- RFC-0001\s*$/m, `related: []`);
+  }
+
+  try {
+    await fs.mkdir(adrDirPath, { recursive: true });
+  } catch {
+    // ignore
+  }
+
+  const targetPath = path.join(adrDirPath, fileName);
+  await fs.writeFile(targetPath, content, "utf-8");
+
+  const relativeFile = path.join(ADR_DIR, fileName);
+
+  if (outputFormat === "pretty") {
+    logger.success(`Created ${nextId}: ${title}`);
+    logger.info(`File: ${relativeFile}`);
+    logger.info(`Status: ${status} (only the named decider may change status)`);
+  }
+
+  return {
+    data: {
+      command: "adr.create",
+      status: "ok",
+      file: relativeFile,
+      id: nextId,
+    },
+    summary: `Created ${nextId}: ${title}`,
+  };
+}