@leonarto/spec-embryo 0.1.0

package/src/services/adoption.ts

@@ -0,0 +1,169 @@
+import type { DoctorFinding } from "./doctor.ts";
+import type { AdoptionInspection } from "./layout.ts";
+
+export interface AdoptionCommandSuggestion {
+  command: string;
+  reason: string;
+}
+
+export interface AdoptionGuidance {
+  overview: string;
+  whatFound: string[];
+  whatChanged: string[];
+  remainingWork: string[];
+  recommendedCommands: AdoptionCommandSuggestion[];
+  firstWeekSequence: string[];
+}
+
+function uniqueCommands(suggestions: AdoptionCommandSuggestion[]): AdoptionCommandSuggestion[] {
+  const seen = new Set<string>();
+  const deduped: AdoptionCommandSuggestion[] = [];
+
+  for (const suggestion of suggestions) {
+    if (seen.has(suggestion.command)) {
+      continue;
+    }
+
+    seen.add(suggestion.command);
+    deduped.push(suggestion);
+  }
+
+  return deduped;
+}
+
+export function buildAdoptionGuidance(input: {
+  adoption: AdoptionInspection;
+  memoryDir: string;
+  created?: string[];
+  skipped?: string[];
+  doctorFindings?: DoctorFinding[];
+  commandContext?: "init" | "doctor";
+}): AdoptionGuidance {
+  const created = input.created ?? [];
+  const skipped = input.skipped ?? [];
+  const doctorFindings = input.doctorFindings ?? [];
+  const warningOrBlockingFindings = doctorFindings.filter(
+    (finding) => finding.severity === "warning" || finding.severity === "blocking",
+  );
+
+  const whatFound = [...input.adoption.findings];
+  const whatChanged: string[] = [];
+  const remainingWork: string[] = [];
+  const recommendedCommands: AdoptionCommandSuggestion[] = [];
+  const firstWeekSequence: string[] = [];
+
+  if (created.length > 0) {
+    whatChanged.push(`Created ${created.length} managed file${created.length === 1 ? "" : "s"} under \`${input.memoryDir}\` and \`.specpm/\`.`);
+  } else {
+    whatChanged.push("No new managed files were created in this run.");
+  }
+
+  if (skipped.length > 0) {
+    whatChanged.push(`Preserved ${skipped.length} existing file${skipped.length === 1 ? "" : "s"} that were already present.`);
+  }
+
+  switch (input.adoption.state) {
+    case "fresh":
+      remainingWork.push("Create the first active spec and linked tasks so the repo stops being only scaffolded memory.");
+      recommendedCommands.push(
+        {
+          command: "spm spec create --title \"...\" --summary \"...\"",
+          reason: "Define the first real planning anchor for the adopted repo.",
+        },
+        {
+          command: "spm task create --title \"...\" --summary \"...\" --spec-ids SPEC-001",
+          reason: "Create the first executable work items linked to that spec.",
+        },
+      );
+      break;
+    case "legacy-docs": {
+      const source = input.adoption.layoutChoice.adoptedHome ?? input.adoption.layoutChoice.candidates[0]?.relativePath ?? "docs";
+      remainingWork.push("Legacy docs still need migration or import into Spec Embryo-managed specs and tasks.");
+      recommendedCommands.push({
+        command: `spm spec import-prompt --source ${source}`,
+        reason: "Generate an agent-ready migration bundle from the most likely legacy documentation home.",
+      });
+      break;
+    }
+    case "partially-adopted":
+      remainingWork.push("The repo still needs migration or cleanup before normal Spec Embryo flows are fully trustworthy.");
+      recommendedCommands.push({
+        command: "spm doctor",
+        reason: "Inspect missing structure, parse errors, and broken links before continuing migration.",
+      });
+      break;
+    case "adopted":
+      remainingWork.push("The managed layout is in place; the next work is about initializing meaningful project memory, not structure.");
+      break;
+  }
+
+  if (warningOrBlockingFindings.length > 0) {
+    remainingWork.push(`Doctor reported ${warningOrBlockingFindings.length} issue${warningOrBlockingFindings.length === 1 ? "" : "s"} that still need migration or cleanup decisions.`);
+  }
+
+  if (warningOrBlockingFindings.length > 0 && input.commandContext !== "doctor") {
+    recommendedCommands.push({
+      command: "spm doctor --json",
+      reason: "Get a structured report that an active agent can turn into explicit next actions without guessing.",
+    });
+  } else if (!input.commandContext || input.commandContext === "init") {
+    recommendedCommands.push({
+      command: "spm doctor",
+      reason: "Verify the adopted layout before trusting normal resume and UI flows.",
+    });
+  }
+
+  recommendedCommands.push({
+    command: "spm current set --focus \"...\" --summary \"...\"",
+    reason: "Create the first explicit checkpoint so another human or agent can answer where work should continue.",
+  });
+  recommendedCommands.push({
+    command: "spm handoff --title \"Initial adoption checkpoint\"",
+    reason: "Capture the migration state once the first meaningful setup pass is complete.",
+  });
+
+  firstWeekSequence.push(
+    "Run doctor and review its findings before assuming the repo is ready for normal work.",
+    "Import or create the first real specs so the managed memory reflects product intent instead of only scaffolding.",
+    "Create linked tasks and mark the first active slice in current state.",
+    "Write an initial handoff once the adoption choices and first actions are explicit.",
+  );
+
+  return {
+    overview:
+      input.adoption.state === "adopted"
+        ? "This repo already looks structurally adopted; the next step is making the managed memory meaningful."
+        : input.adoption.state === "legacy-docs"
+          ? "This repo looks importable but still needs migration work to turn legacy docs into canonical Spec Embryo memory."
+          : input.adoption.state === "partially-adopted"
+            ? "This repo shows partial Spec Embryo signals and needs cleanup before the workflow becomes fully trustworthy."
+            : "This repo is fresh to Spec Embryo and now needs its first real spec/task/current-state content.",
+    whatFound,
+    whatChanged,
+    remainingWork,
+    recommendedCommands: uniqueCommands(recommendedCommands),
+    firstWeekSequence,
+  };
+}
+
+export function renderAdoptionGuidance(guidance: AdoptionGuidance): string[] {
+  return [
+    "Adoption summary:",
+    `- ${guidance.overview}`,
+    "",
+    "What was found:",
+    ...guidance.whatFound.map((item) => `- ${item}`),
+    "",
+    "What changed:",
+    ...guidance.whatChanged.map((item) => `- ${item}`),
+    "",
+    "What still needs migration or follow-up:",
+    ...guidance.remainingWork.map((item) => `- ${item}`),
+    "",
+    "Recommended next commands:",
+    ...guidance.recommendedCommands.map((item) => `- ${item.command} — ${item.reason}`),
+    "",
+    "First-week sequence:",
+    ...guidance.firstWeekSequence.map((item, index) => `${index + 1}. ${item}`),
+  ];
+}

package/src/services/agents.ts

@@ -0,0 +1,191 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+export interface AgentsBudgetRule {
+  target: number;
+  hardCap: number;
+}
+
+export interface AgentsFileReport {
+  absolutePath: string;
+  relativePath: string;
+  folder: string;
+  estimatedTokens: number;
+  rule: AgentsBudgetRule;
+  ok: boolean;
+}
+
+export interface AgentsChainReport {
+  relativePath: string;
+  chainFolders: string[];
+  estimatedTokens: number;
+  target: number;
+  hardCap: number;
+  ok: boolean;
+}
+
+export interface AgentsHealthReport {
+  files: AgentsFileReport[];
+  chains: AgentsChainReport[];
+  failures: string[];
+  summary: {
+    fileCount: number;
+    failureCount: number;
+    maxFileTokens: number;
+    maxChainTokens: number;
+    ok: boolean;
+  };
+}
+
+const EXCLUDED_DIRS = new Set([".git", "node_modules", "dist", "coverage"]);
+const CHAIN_TARGET = 1800;
+const CHAIN_HARD_CAP = 2200;
+
+const RULES: Record<string, AgentsBudgetRule> = {
+  ".": { target: 900, hardCap: 1200 },
+  ".specpm": { target: 300, hardCap: 400 },
+  "docs": { target: 300, hardCap: 500 },
+  "docs/spm": { target: 280, hardCap: 450 },
+  "docs/spm/specs": { target: 220, hardCap: 450 },
+  "docs/spm/tasks": { target: 220, hardCap: 450 },
+  "docs/spm/skills": { target: 220, hardCap: 450 },
+  "scripts": { target: 220, hardCap: 350 },
+  "skills": { target: 300, hardCap: 500 },
+  "src": { target: 350, hardCap: 600 },
+  "src/backends": { target: 240, hardCap: 450 },
+  "src/commands": { target: 220, hardCap: 450 },
+  "src/services": { target: 220, hardCap: 450 },
+  "tests": { target: 180, hardCap: 350 },
+};
+
+export function estimateTokens(content: string): number {
+  return Math.ceil(content.length / 4);
+}
+
+export function agentsRuleForFolder(folder: string): AgentsBudgetRule {
+  const normalized = folder === "" ? "." : folder;
+  const candidates = Object.keys(RULES).filter((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));
+  const match = candidates.sort((left, right) => right.length - left.length)[0] ?? ".";
+  return RULES[match]!;
+}
+
+export async function findAgentsFiles(rootDir: string, currentDir = rootDir): Promise<string[]> {
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  const results: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) {
+        continue;
+      }
+
+      results.push(...(await findAgentsFiles(rootDir, join(currentDir, entry.name))));
+      continue;
+    }
+
+    if (entry.isFile() && entry.name === "AGENTS.md") {
+      results.push(join(currentDir, entry.name));
+    }
+  }
+
+  return results.sort();
+}
+
+export async function buildAgentsHealthReport(rootDir: string): Promise<AgentsHealthReport> {
+  const files = await findAgentsFiles(rootDir);
+  const tokenByFolder = new Map<string, number>();
+  const fileReports: AgentsFileReport[] = [];
+  const failures: string[] = [];
+
+  for (const file of files) {
+    const relFile = relative(rootDir, file);
+    const folder = dirname(relFile) === "." ? "." : dirname(relFile);
+    const content = await readFile(file, "utf8");
+    const estimatedTokens = estimateTokens(content);
+    const rule = agentsRuleForFolder(folder);
+    const ok = estimatedTokens <= rule.hardCap;
+
+    tokenByFolder.set(folder, estimatedTokens);
+    fileReports.push({
+      absolutePath: file,
+      relativePath: relFile,
+      folder,
+      estimatedTokens,
+      rule,
+      ok,
+    });
+
+    if (!ok) {
+      failures.push(`${relFile} exceeds hard cap (${estimatedTokens} > ${rule.hardCap})`);
+    }
+  }
+
+  const chainReports: AgentsChainReport[] = fileReports.map((file) => {
+    const segments = file.folder === "." ? [] : file.folder.split("/");
+    const chainFolders = ["."];
+
+    for (let index = 0; index < segments.length; index += 1) {
+      chainFolders.push(segments.slice(0, index + 1).join("/"));
+    }
+
+    const estimatedTokens = chainFolders.reduce((sum, entry) => sum + (tokenByFolder.get(entry) ?? 0), 0);
+    const ok = estimatedTokens <= CHAIN_HARD_CAP;
+
+    if (!ok) {
+      failures.push(`${file.relativePath} chain exceeds hard cap (${estimatedTokens} > ${CHAIN_HARD_CAP})`);
+    }
+
+    return {
+      relativePath: file.relativePath,
+      chainFolders,
+      estimatedTokens,
+      target: CHAIN_TARGET,
+      hardCap: CHAIN_HARD_CAP,
+      ok,
+    };
+  });
+
+  return {
+    files: fileReports,
+    chains: chainReports,
+    failures,
+    summary: {
+      fileCount: fileReports.length,
+      failureCount: failures.length,
+      maxFileTokens: fileReports.reduce((max, file) => Math.max(max, file.estimatedTokens), 0),
+      maxChainTokens: chainReports.reduce((max, chain) => Math.max(max, chain.estimatedTokens), 0),
+      ok: failures.length === 0,
+    },
+  };
+}
+
+export function renderAgentsHealthReport(report: AgentsHealthReport): string {
+  if (report.files.length === 0) {
+    return "No AGENTS.md files found.";
+  }
+
+  const lines: string[] = ["AGENTS.md budget report", ""];
+
+  for (const file of report.files) {
+    lines.push(
+      `${file.ok ? "OK" : "FAIL"} ${file.relativePath} | est_tokens=${file.estimatedTokens} | target<=${file.rule.target} | hard_cap<=${file.rule.hardCap}`,
+    );
+  }
+
+  lines.push("", "Chain report", "");
+
+  for (const chain of report.chains) {
+    lines.push(
+      `${chain.ok ? "OK" : "FAIL"} ${chain.relativePath} | active_chain_tokens=${chain.estimatedTokens} | target<=${chain.target} | hard_cap<=${chain.hardCap}`,
+    );
+  }
+
+  if (report.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of report.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+
+  return lines.join("\n");
+}