@leonarto/spec-embryo 0.1.0

package/src/services/spec-import.ts

@@ -0,0 +1,217 @@
+import { readdir, readFile } from "node:fs/promises";
+import { extname, join, relative } from "node:path";
+import { buildManagedPaths } from "./layout.ts";
+
+const SUPPORTED_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".rst", ".yaml", ".yml", ".toml", ".json"]);
+
+export interface SpecImportSourceFile {
+  absolutePath: string;
+  relativePath: string;
+  extension: string;
+  chars: number;
+  headings: string[];
+  excerpt: string;
+}
+
+export interface SpecImportBundle {
+  sourceRoot: string;
+  fileCount: number;
+  files: SpecImportSourceFile[];
+  userInstructions?: string;
+  targetStructure: {
+    specsDir: string;
+    tasksDir: string;
+    specFrontmatterFields: string[];
+    taskFrontmatterFields: string[];
+  };
+  migrationRules: string[];
+  recommendedPrompt: string;
+  expectedOutputFormat: {
+    requiredFiles: string[];
+    migrationChecklist: string[];
+    outputSections: string[];
+  };
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\r\n/g, "\n").trim();
+}
+
+function truncate(value: string, limit: number): string {
+  if (value.length <= limit) {
+    return value;
+  }
+
+  return `${value.slice(0, Math.max(0, limit - 14))}\n...[truncated]`;
+}
+
+function extractHeadings(content: string): string[] {
+  return normalizeWhitespace(content)
+    .split("\n")
+    .filter((line) => /^#{1,6}\s+/.test(line))
+    .slice(0, 12)
+    .map((line) => line.replace(/^#{1,6}\s+/, "").trim())
+    .filter(Boolean);
+}
+
+async function walkSupportedFiles(rootDir: string, currentDir = rootDir): Promise<string[]> {
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  const results: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name === ".git" || entry.name === "node_modules") {
+      continue;
+    }
+
+    const fullPath = join(currentDir, entry.name);
+
+    if (entry.isDirectory()) {
+      results.push(...(await walkSupportedFiles(rootDir, fullPath)));
+      continue;
+    }
+
+    if (entry.isFile() && entry.name !== "AGENTS.md" && SUPPORTED_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      results.push(fullPath);
+    }
+  }
+
+  return results.sort();
+}
+
+export async function buildSpecImportBundle(
+  rootDir: string,
+  sourceDir: string,
+  options?: {
+    instructions?: string;
+    maxCharsPerFile?: number;
+    targetMemoryDir?: string;
+  },
+): Promise<SpecImportBundle> {
+  const maxCharsPerFile = options?.maxCharsPerFile ?? 1800;
+  const managed = buildManagedPaths(options?.targetMemoryDir ?? "docs/spm");
+  const absoluteSourceDir = sourceDir.startsWith("/") ? sourceDir : join(rootDir, sourceDir);
+  const files = await walkSupportedFiles(absoluteSourceDir);
+
+  const fileEntries = await Promise.all(
+    files.map(async (filePath) => {
+      const content = await readFile(filePath, "utf8");
+      return {
+        absolutePath: filePath,
+        relativePath: relative(rootDir, filePath),
+        extension: extname(filePath).toLowerCase(),
+        chars: content.length,
+        headings: extractHeadings(content),
+        excerpt: truncate(normalizeWhitespace(content), maxCharsPerFile),
+      };
+    }),
+  );
+
+  const sourceSummary = fileEntries
+    .slice(0, 10)
+    .map((file) => `- ${file.relativePath} (${file.chars} chars${file.headings.length > 0 ? `; headings: ${file.headings.join(" | ")}` : ""})`)
+    .join("\n");
+
+  const instructionSuffix = options?.instructions?.trim()
+    ? `\nAdditional migration instructions from the user:\n${options.instructions.trim()}`
+    : "";
+
+  return {
+    sourceRoot: absoluteSourceDir,
+    fileCount: fileEntries.length,
+    files: fileEntries,
+    userInstructions: options?.instructions?.trim() || undefined,
+    targetStructure: {
+      specsDir: `${managed.specsDir}/`,
+      tasksDir: `${managed.tasksDir}/`,
+      specFrontmatterFields: ["doc_kind", "id", "title", "status", "summary", "task_ids", "tags", "owner", "updated_at"],
+      taskFrontmatterFields: ["doc_kind", "id", "title", "status", "summary", "spec_ids", "depends_on", "blocked_by", "priority", "owner_role", "tags", "updated_at"],
+    },
+    migrationRules: [
+      "Create Markdown files with TOML frontmatter so Spec Embryo can parse them deterministically.",
+      "Use `doc_kind = \"spec\"` for specs and `doc_kind = \"task\"` for tasks.",
+      "Keep facts faithful to the source docs. Do not invent requirements, dependencies, or statuses unless the user explicitly asked for interpretation.",
+      "When dependencies are unclear, prefer leaving `depends_on = []` and note ambiguity in the body instead of guessing.",
+      "Prefer one coherent spec per product slice and create linked tasks for executable work.",
+      "Preserve important goals, constraints, decisions, and non-goals in Markdown body sections.",
+      "Use stable IDs like `SPEC-001` and `TASK-001`.",
+      `If the source folder mixes strategy and execution notes, separate them into \`${managed.specsDir}/\` and \`${managed.tasksDir}/\` rather than flattening everything into one file.`,
+    ],
+    recommendedPrompt: [
+      "You are migrating an existing project spec/docs folder into Spec Embryo's deterministic format.",
+      "Use the scanned source file inventory and excerpts as the source of truth.",
+      `Produce repo-native Markdown files under \`${managed.specsDir}/\` and \`${managed.tasksDir}/\` using TOML frontmatter.`,
+      "The result must be deterministic-friendly: explicit IDs, linked tasks, and no missing required frontmatter fields.",
+      "Do not invent facts. When something is ambiguous, preserve the ambiguity in the Markdown body or add a concise note instead of fabricating structure.",
+      "Prefer stable spec intent in spec files and actionable execution slices in task files.",
+      "",
+      "Source inventory:",
+      sourceSummary || "- No supported files found.",
+      instructionSuffix,
+    ]
+      .filter(Boolean)
+      .join("\n"),
+    expectedOutputFormat: {
+      requiredFiles: [`${managed.specsDir}/*.md`, `${managed.tasksDir}/*.md`],
+      migrationChecklist: [
+        "Every generated spec file has the required TOML frontmatter fields.",
+        "Every generated task file links back to one or more spec IDs.",
+        "No task dependency is invented unless explicit in the source.",
+        "Body sections preserve meaningful goals, scope, decisions, and notes from the source docs.",
+      ],
+      outputSections: ["migration-summary", "files-created-or-updated", "ambiguities", "follow-up-gaps"],
+    },
+  };
+}
+
+export function renderSpecImportBundle(bundle: SpecImportBundle): string {
+  const lines: string[] = [];
+
+  lines.push("Spec import prompt bundle");
+  lines.push("");
+  lines.push(`Source root: ${bundle.sourceRoot}`);
+  lines.push(`Supported files scanned: ${bundle.fileCount}`);
+  lines.push(`Target specs dir: ${bundle.targetStructure.specsDir}`);
+  lines.push(`Target tasks dir: ${bundle.targetStructure.tasksDir}`);
+  lines.push("");
+  lines.push("Target spec frontmatter fields:");
+  lines.push(`- ${bundle.targetStructure.specFrontmatterFields.join(", ")}`);
+  lines.push("Target task frontmatter fields:");
+  lines.push(`- ${bundle.targetStructure.taskFrontmatterFields.join(", ")}`);
+  lines.push("");
+  lines.push("Migration rules:");
+  for (const rule of bundle.migrationRules) {
+    lines.push(`- ${rule}`);
+  }
+  lines.push("");
+  lines.push("Scanned source files:");
+  if (bundle.files.length === 0) {
+    lines.push("- none");
+  } else {
+    for (const file of bundle.files) {
+      const headingText = file.headings.length > 0 ? ` | headings: ${file.headings.join(" | ")}` : "";
+      lines.push(`- ${file.relativePath} (${file.chars} chars${headingText})`);
+    }
+  }
+  lines.push("");
+  lines.push("Recommended prompt:");
+  lines.push(bundle.recommendedPrompt);
+  lines.push("");
+  lines.push("Expected output format:");
+  lines.push(`- required files: ${bundle.expectedOutputFormat.requiredFiles.join(", ")}`);
+  lines.push(`- output sections: ${bundle.expectedOutputFormat.outputSections.join(", ")}`);
+
+  if (bundle.userInstructions) {
+    lines.push("");
+    lines.push(`User instructions: ${bundle.userInstructions}`);
+  }
+
+  lines.push("");
+  lines.push("File excerpts:");
+  for (const file of bundle.files) {
+    lines.push("");
+    lines.push(`## ${file.relativePath}`);
+    lines.push(file.excerpt || "[empty file]");
+  }
+
+  return lines.join("\n");
+}

package/src/services/spec-questions.ts

@@ -0,0 +1,343 @@
+export interface MarkdownSection {
+  heading: string;
+  depth: number;
+  lines: string[];
+}
+
+export interface SplitMarkdownSectionsResult {
+  preamble: string[];
+  sections: MarkdownSection[];
+}
+
+export interface SpecOpenQuestion {
+  id: string;
+  question: string;
+}
+
+export interface ResolvedDecisionEntry {
+  id: string;
+  question?: string;
+  answer: string;
+}
+
+export interface ParsedSpecQuestionSections {
+  openQuestions: SpecOpenQuestion[];
+  resolvedDecisions: ResolvedDecisionEntry[];
+}
+
+export interface SpecAnswerInput {
+  question: string;
+  answer: string;
+}
+
+export interface AppliedSpecAnswers {
+  body: string;
+  answeredQuestions: string[];
+  remainingQuestions: SpecOpenQuestion[];
+  resolvedDecisions: ResolvedDecisionEntry[];
+}
+
+function normalizeHeading(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+    .replace(/\s+/g, " ");
+}
+
+function normalizeQuestion(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function splitSectionItems(lines: string[]): string[][] {
+  const items: string[][] = [];
+  let current: string[] = [];
+  let currentMode: "bullet" | "paragraph" | undefined;
+
+  function flush() {
+    if (current.length === 0) {
+      return;
+    }
+
+    items.push(current.map((line) => line.trimEnd()));
+    current = [];
+    currentMode = undefined;
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed.length === 0) {
+      flush();
+      continue;
+    }
+
+    const bulletMatch = trimmed.match(/^[-*]\s+(.*)$/);
+    if (bulletMatch) {
+      flush();
+      currentMode = "bullet";
+      current.push(bulletMatch[1]!.trim());
+      continue;
+    }
+
+    if (!currentMode) {
+      currentMode = "paragraph";
+    }
+
+    current.push(currentMode === "bullet" ? trimmed : trimmed);
+  }
+
+  flush();
+  return items;
+}
+
+function parseQuestionBlock(lines: string[], index: number): SpecOpenQuestion | undefined {
+  const question = normalizeQuestion(lines.join(" "));
+  if (!question) {
+    return undefined;
+  }
+
+  return {
+    id: `open-question-${index + 1}`,
+    question,
+  };
+}
+
+function parseResolvedDecisionBlock(lines: string[], index: number): ResolvedDecisionEntry | undefined {
+  const normalizedLines = lines.map((line) => line.trim()).filter(Boolean);
+  if (normalizedLines.length === 0) {
+    return undefined;
+  }
+
+  let question: string | undefined;
+  const answerLines: string[] = [];
+  let collectingAnswer = false;
+
+  for (const line of normalizedLines) {
+    const questionMatch = line.match(/^Question:\s*(.*)$/i);
+    if (questionMatch) {
+      question = normalizeQuestion(questionMatch[1] ?? "");
+      continue;
+    }
+
+    const decisionMatch = line.match(/^Decision:\s*(.*)$/i);
+    if (decisionMatch) {
+      answerLines.push(decisionMatch[1]!.trim());
+      collectingAnswer = true;
+      continue;
+    }
+
+    const answerMatch = line.match(/^Answer:\s*(.*)$/i);
+    if (answerMatch) {
+      const initialAnswer = answerMatch[1]!.trim();
+      if (initialAnswer) {
+        answerLines.push(initialAnswer);
+      }
+      collectingAnswer = true;
+      continue;
+    }
+
+    if (collectingAnswer) {
+      answerLines.push(line);
+      continue;
+    }
+
+    answerLines.push(line);
+  }
+
+  const answer = answerLines.join("\n").trim();
+  if (!answer) {
+    return undefined;
+  }
+
+  return {
+    id: `resolved-decision-${index + 1}`,
+    question,
+    answer,
+  };
+}
+
+function renderOpenQuestions(items: SpecOpenQuestion[]): string[] {
+  return items.map((item) => `- ${item.question}`);
+}
+
+function renderResolvedDecisions(items: ResolvedDecisionEntry[]): string[] {
+  const lines: string[] = [];
+
+  for (const [index, item] of items.entries()) {
+    if (index > 0) {
+      lines.push("");
+    }
+
+    if (item.question) {
+      lines.push(`- Question: ${item.question}`);
+    } else {
+      lines.push("- Decision:");
+    }
+
+    const answerLines = item.answer
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+
+    if (answerLines.length === 0) {
+      lines.push("  Answer:");
+      continue;
+    }
+
+    lines.push("  Answer:");
+    for (const line of answerLines) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  return lines;
+}
+
+function renderMarkdownSections(result: SplitMarkdownSectionsResult): string {
+  const chunks: string[] = [];
+  const trimmedPreamble = result.preamble.join("\n").trim();
+
+  if (trimmedPreamble) {
+    chunks.push(trimmedPreamble);
+  }
+
+  for (const section of result.sections) {
+    const content = section.lines.join("\n").trimEnd();
+    const sectionLines = [`${"#".repeat(section.depth)} ${section.heading}`];
+    if (content.length > 0) {
+      sectionLines.push("", content);
+    }
+    chunks.push(sectionLines.join("\n"));
+  }
+
+  return `${chunks.join("\n\n").trim()}\n`;
+}
+
+export function splitMarkdownSections(body: string): SplitMarkdownSectionsResult {
+  const lines = body.replace(/\r\n/g, "\n").split("\n");
+  const preamble: string[] = [];
+  const sections: MarkdownSection[] = [];
+  let currentSection: MarkdownSection | undefined;
+
+  for (const line of lines) {
+    const match = line.trim().match(/^(#{1,6})\s+(.*)$/);
+    if (match) {
+      currentSection = {
+        heading: match[2]!.trim(),
+        depth: match[1]!.length,
+        lines: [],
+      };
+      sections.push(currentSection);
+      continue;
+    }
+
+    if (currentSection) {
+      currentSection.lines.push(line);
+    } else {
+      preamble.push(line);
+    }
+  }
+
+  return {
+    preamble,
+    sections,
+  };
+}
+
+export function parseSpecQuestionSections(body: string): ParsedSpecQuestionSections {
+  const { sections } = splitMarkdownSections(body);
+  const openQuestionsSection = sections.find((section) => normalizeHeading(section.heading) === "open questions");
+  const resolvedDecisionsSection = sections.find((section) => normalizeHeading(section.heading) === "resolved decisions");
+
+  const openQuestions = openQuestionsSection
+    ? splitSectionItems(openQuestionsSection.lines)
+        .map((lines, index) => parseQuestionBlock(lines, index))
+        .filter((item): item is SpecOpenQuestion => Boolean(item))
+    : [];
+
+  const resolvedDecisions = resolvedDecisionsSection
+    ? splitSectionItems(resolvedDecisionsSection.lines)
+        .map((lines, index) => parseResolvedDecisionBlock(lines, index))
+        .filter((item): item is ResolvedDecisionEntry => Boolean(item))
+    : [];
+
+  return {
+    openQuestions,
+    resolvedDecisions,
+  };
+}
+
+export function applySpecAnswers(body: string, answers: SpecAnswerInput[]): AppliedSpecAnswers {
+  const filteredAnswers = answers
+    .map((answer) => ({
+      question: normalizeQuestion(answer.question),
+      answer: answer.answer.trim(),
+    }))
+    .filter((answer) => answer.question.length > 0 && answer.answer.length > 0);
+
+  if (filteredAnswers.length === 0) {
+    throw new Error("At least one answered question is required.");
+  }
+
+  const split = splitMarkdownSections(body);
+  const openQuestionsIndex = split.sections.findIndex((section) => normalizeHeading(section.heading) === "open questions");
+  if (openQuestionsIndex === -1) {
+    throw new Error("This spec does not have an Open Questions section.");
+  }
+
+  const resolvedDecisionsIndex = split.sections.findIndex((section) => normalizeHeading(section.heading) === "resolved decisions");
+  const existing = parseSpecQuestionSections(body);
+  const answerByQuestion = new Map(filteredAnswers.map((answer) => [answer.question, answer.answer]));
+  const openQuestionSet = new Set(existing.openQuestions.map((entry) => entry.question));
+
+  for (const question of answerByQuestion.keys()) {
+    if (!openQuestionSet.has(question)) {
+      throw new Error(`Open question not found in spec: ${question}`);
+    }
+  }
+
+  const answeredQuestions = existing.openQuestions
+    .map((entry) => entry.question)
+    .filter((question) => answerByQuestion.has(question));
+  const remainingQuestions = existing.openQuestions.filter((entry) => !answerByQuestion.has(entry.question));
+  const nextResolvedDecisions = [
+    ...existing.resolvedDecisions,
+    ...answeredQuestions.map((question, index) => ({
+      id: `resolved-decision-new-${index + 1}`,
+      question,
+      answer: answerByQuestion.get(question) ?? "",
+    })),
+  ];
+
+  if (remainingQuestions.length > 0) {
+    split.sections[openQuestionsIndex] = {
+      ...split.sections[openQuestionsIndex]!,
+      lines: renderOpenQuestions(remainingQuestions),
+    };
+  } else {
+    split.sections.splice(openQuestionsIndex, 1);
+  }
+
+  const resolvedSection: MarkdownSection = {
+    heading: "Resolved Decisions",
+    depth: 2,
+    lines: renderResolvedDecisions(nextResolvedDecisions),
+  };
+
+  if (resolvedDecisionsIndex >= 0) {
+    const adjustedIndex = remainingQuestions.length === 0 && resolvedDecisionsIndex > openQuestionsIndex ? resolvedDecisionsIndex - 1 : resolvedDecisionsIndex;
+    split.sections[adjustedIndex] = resolvedSection;
+  } else if (openQuestionsIndex >= 0 && remainingQuestions.length > 0) {
+    split.sections.splice(openQuestionsIndex, 0, resolvedSection);
+  } else {
+    split.sections.push(resolvedSection);
+  }
+
+  return {
+    body: renderMarkdownSections(split),
+    answeredQuestions,
+    remainingQuestions,
+    resolvedDecisions: nextResolvedDecisions,
+  };
+}

package/src/services/ui.ts

@@ -0,0 +1,34 @@
+import { fileURLToPath } from "node:url";
+import type { ParsedArgs } from "../cli.ts";
+import { flagValue } from "../cli.ts";
+import { pathExists } from "../storage.ts";
+
+export interface UiLaunchConfig {
+  webDir: string;
+  host: string;
+  port: number;
+}
+
+const PACKAGED_WEB_DIR = fileURLToPath(new URL("../../web", import.meta.url));
+
+export async function resolveUiLaunchConfig(rootDir: string, parsed: ParsedArgs): Promise<UiLaunchConfig> {
+  const webDir = PACKAGED_WEB_DIR;
+
+  if (!(await pathExists(webDir))) {
+    throw new Error("Packaged web app not found. Reinstall Spec Embryo so the UI assets are available.");
+  }
+
+  const host = flagValue(parsed, "host") ?? "127.0.0.1";
+  const portRaw = flagValue(parsed, "port");
+  const port = portRaw ? Number.parseInt(portRaw, 10) : 4173;
+
+  if (!Number.isFinite(port) || port <= 0) {
+    throw new Error("`ui --port` must be a positive integer.");
+  }
+
+  return {
+    webDir,
+    host,
+    port,
+  };
+}

package/src/storage.ts

@@ -0,0 +1,57 @@
+import { readdir, mkdir, readFile, writeFile, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, extname, join } from "node:path";
+
+export async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function readUtf8(filePath: string): Promise<string> {
+  return readFile(filePath, "utf8");
+}
+
+export async function writeUtf8(filePath: string, content: string): Promise<void> {
+  await ensureDir(dirname(filePath));
+  await writeFile(filePath, content, "utf8");
+}
+
+export async function writeIfMissing(filePath: string, content: string): Promise<boolean> {
+  if (await pathExists(filePath)) {
+    return false;
+  }
+
+  await writeUtf8(filePath, content);
+  return true;
+}
+
+export async function listMarkdownFiles(dirPath: string): Promise<string[]> {
+  if (!(await pathExists(dirPath))) {
+    return [];
+  }
+
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  const results: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await listMarkdownFiles(fullPath)));
+      continue;
+    }
+
+    if (entry.isFile() && extname(entry.name) === ".md" && entry.name !== "AGENTS.md") {
+      results.push(fullPath);
+    }
+  }
+
+  return results.sort();
+}