htmlspec-kit 0.1.0

package/skills/htmlspec-kit/assets/spec.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://htmlspec.dev/schemas/spec.schema.json",
+  "title": "HTMLSpec SPEC payload",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "version", "id", "title", "status", "owner", "createdAt", "updatedAt", "summaryHtml", "proposal", "spec", "design", "tasks", "history"],
+  "properties": {
+    "format": { "const": "htmlspec" },
+    "version": { "type": "string" },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["draft", "ready", "in-progress", "done", "archived"] },
+    "owner": { "type": "string" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "summaryHtml": { "type": "string" },
+    "proposal": { "$ref": "#/$defs/proposal" },
+    "spec": { "$ref": "#/$defs/spec" },
+    "design": { "$ref": "#/$defs/design" },
+    "tasks": { "type": "array", "items": { "$ref": "#/$defs/taskGroup" } },
+    "history": { "type": "array", "items": { "$ref": "#/$defs/historyEntry" } }
+  },
+  "$defs": {
+    "proposal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["whyHtml", "whatChanges", "capabilities", "impact"],
+      "properties": {
+        "whyHtml": { "type": "string" },
+        "whatChanges": { "type": "array", "items": { "type": "string" } },
+        "capabilities": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["new", "modified"],
+          "properties": {
+            "new": { "type": "array", "items": { "$ref": "#/$defs/capability" } },
+            "modified": { "type": "array", "items": { "$ref": "#/$defs/capability" } }
+          }
+        },
+        "impact": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "description"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "description": { "type": "string" }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["overviewHtml", "operations"],
+      "properties": {
+        "overviewHtml": { "type": "string" },
+        "operations": { "type": "array", "items": { "$ref": "#/$defs/requirementDelta" } }
+      }
+    },
+    "requirementDelta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "requirements"],
+      "properties": {
+        "type": { "enum": ["ADDED", "MODIFIED", "REMOVED", "RENAMED"] },
+        "requirements": { "type": "array", "items": { "$ref": "#/$defs/requirement" } }
+      }
+    },
+    "requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "bodyHtml", "scenarios"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "bodyHtml": { "type": "string" },
+        "scenarios": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/scenario" } },
+        "reasonHtml": { "type": "string" },
+        "migrationHtml": { "type": "string" },
+        "from": { "type": "string" },
+        "to": { "type": "string" }
+      }
+    },
+    "scenario": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "when", "then"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "given": { "type": "string" },
+        "when": { "type": "string" },
+        "then": { "type": "string" }
+      }
+    },
+    "design": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contextHtml", "goals", "nonGoals", "decisions", "risksTradeoffs", "migrationPlan", "openQuestions"],
+      "properties": {
+        "contextHtml": { "type": "string" },
+        "goals": { "type": "array", "items": { "type": "string" } },
+        "nonGoals": { "type": "array", "items": { "type": "string" } },
+        "decisions": { "type": "array", "items": { "$ref": "#/$defs/designDecision" } },
+        "risksTradeoffs": { "type": "array", "items": { "type": "string" } },
+        "migrationPlan": { "type": "array", "items": { "type": "string" } },
+        "openQuestions": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "designDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "decisionHtml", "rationaleHtml", "alternatives"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "decisionHtml": { "type": "string" },
+        "rationaleHtml": { "type": "string" },
+        "alternatives": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "taskGroup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "items"],
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "items": { "type": "array", "items": { "$ref": "#/$defs/task" } }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "status"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+$" },
+        "title": { "type": "string" },
+        "status": { "enum": ["todo", "in-progress", "done"] },
+        "notes": { "type": "string" }
+      }
+    },
+    "historyEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["at", "action"],
+      "properties": {
+        "at": { "type": "string", "format": "date-time" },
+        "action": { "type": "string" }
+      }
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,422 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { Command } from "commander";
+import { readSpecData, writeSpecData } from "./html-document";
+import { applyJsonPatch, assertJsonPatch } from "./json-patch";
+import {
+  addTask,
+  createHtmlSpecData,
+  setChangeStatus,
+  setTaskStatus,
+  slugify,
+  titleFromId,
+  touch,
+  validateSpecData,
+} from "./spec-data";
+import type { ChangeStatus, Design, HtmlSpecData, SpecSection, TaskStatus } from "./types";
+import {
+  changePath,
+  copyTemplate,
+  ensureSpecLayout,
+  projectPath,
+  readInputContent,
+  resolveExistingSpecPath,
+  specRoot,
+  templateSourcePath,
+  titleizePath,
+} from "./paths";
+
+type ListEntry = {
+  kind: "change" | "spec" | "archive";
+  id: string;
+  path: string;
+  data?: HtmlSpecData;
+  error?: string;
+};
+
+export async function runCli(argv = process.argv): Promise<void> {
+  const program = new Command();
+
+  program
+    .name("htmlspec")
+    .description("HTML-backed spec-driven development CLI")
+    .version("0.1.0");
+
+  program
+    .command("init")
+    .description("Create the spec/ workspace and copy the HTMLSpec template")
+    .option("-f, --force", "Overwrite spec/templates/change-template.html")
+    .action(async (options: { force?: boolean }) => {
+      await ensureSpecLayout();
+      const template = await copyTemplate(options.force);
+      console.log(`Created ${titleizePath(specRoot())}`);
+      console.log(`Template ${options.force ? "written" : "available"} at ${titleizePath(template)}`);
+    });
+
+  program
+    .command("new <id>")
+    .description("Create spec/changes/<id>.html from the HTMLSpec template")
+    .option("-t, --title <title>", "Human-readable title")
+    .option("-f, --force", "Overwrite an existing change")
+    .action(async (rawId: string, options: { title?: string; force?: boolean }) => {
+      await ensureSpecLayout();
+      const id = slugify(rawId);
+      if (!id) throw new Error("Change id cannot be empty");
+
+      const destination = changePath(id);
+      if (!options.force && existsSync(destination)) {
+        throw new Error(`${titleizePath(destination)} already exists. Use --force to overwrite.`);
+      }
+
+      const template = await readFile(templateSourcePath(), "utf8");
+      await writeFile(destination, template, "utf8");
+      await writeSpecData(destination, createHtmlSpecData(id, options.title ?? titleFromId(id)));
+      console.log(`Created ${titleizePath(destination)}`);
+    });
+
+  program
+    .command("list")
+    .description("List HTMLSpec files")
+    .option("--json", "Output JSON")
+    .action(async (options: { json?: boolean }) => {
+      const entries = await listEntries();
+      if (options.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+      }
+
+      if (entries.length === 0) {
+        console.log("No specs found");
+        return;
+      }
+
+      for (const entry of entries) {
+        const status = entry.data?.status ?? "invalid";
+        const title = entry.data?.title ?? entry.error ?? "";
+        console.log(`${entry.kind.padEnd(7)} ${entry.id.padEnd(24)} ${status.padEnd(12)} ${title}`);
+      }
+    });
+
+  program
+    .command("show <id-or-path>")
+    .description("Show a spec summary or the raw SPEC JSON")
+    .option("--json", "Output the SPEC JSON")
+    .action(async (idOrPath: string, options: { json?: boolean }) => {
+      const filePath = resolveExistingSpecPath(idOrPath);
+      const data = await readSpecData(filePath);
+
+      if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+
+      printSummary(data, filePath);
+    });
+
+  program
+    .command("patch <id-or-path> [patch-file]")
+    .description("Apply an RFC 6902 JSON Patch to SPEC data, or replace one JSON Pointer path")
+    .option("-p, --patch <json>", "Inline JSON Patch array")
+    .option("-f, --from <file>", "Read JSON Patch array from file")
+    .option("--replace <pointer>", "Replace a JSON Pointer path")
+    .option("--value <json>", "JSON value for --replace, for example '\"Ready\"' or '{\"a\":1}'")
+    .option("--value-from <file>", "Read JSON value for --replace from file")
+    .option("--string-value <text>", "String value for --replace")
+    .action(async (
+      idOrPath: string,
+      patchFile: string | undefined,
+      options: { patch?: string; from?: string; replace?: string; value?: string; valueFrom?: string; stringValue?: string },
+    ) => {
+      const operations = await resolvePatchOperations(patchFile, options);
+      await mutateSpec(idOrPath, (data) => touch(applyJsonPatch(data, operations), "patch:applied"));
+    });
+
+  program
+    .command("status [id-or-path]")
+    .description("Show task status for one change or all changes")
+    .action(async (idOrPath?: string) => {
+      if (idOrPath) {
+        const filePath = resolveExistingSpecPath(idOrPath);
+        printTaskStatus(await readSpecData(filePath));
+        return;
+      }
+
+      const entries = await listEntries();
+      for (const entry of entries.filter((item) => item.data)) {
+        const data = entry.data!;
+        const counts = countTasks(data);
+        console.log(`${entry.id}: ${counts.done}/${counts.total} done, ${counts.inProgress} in progress`);
+      }
+    });
+
+  program
+    .command("validate [id-or-path]")
+    .description("Validate one HTMLSpec file or every file under spec/")
+    .option("--json", "Output JSON")
+    .action(async (idOrPath: string | undefined, options: { json?: boolean }) => {
+      const reports = idOrPath
+        ? [await validateFile(resolveExistingSpecPath(idOrPath))]
+        : await Promise.all((await listEntries()).map((entry) => validateFile(entry.path)));
+
+      if (options.json) {
+        console.log(JSON.stringify(reports, null, 2));
+        process.exitCode = reports.some((report) => !report.valid) ? 1 : 0;
+        return;
+      }
+
+      for (const report of reports) {
+        if (report.valid) {
+          console.log(`OK ${titleizePath(report.path)}`);
+        } else {
+          console.error(`FAIL ${titleizePath(report.path)}`);
+          for (const issue of report.issues) console.error(`  - ${issue}`);
+        }
+      }
+      process.exitCode = reports.some((report) => !report.valid) ? 1 : 0;
+    });
+
+  program
+    .command("tasks <id-or-path>")
+    .description("List tasks for a change")
+    .action(async (idOrPath: string) => {
+      const data = await readSpecData(resolveExistingSpecPath(idOrPath));
+      printTaskStatus(data);
+    });
+
+  const task = program.command("task").description("Add or mark HTMLSpec tasks");
+
+  task
+    .command("add <id-or-path> <title>")
+    .description("Add a task to a task group")
+    .option("-g, --group <group>", "Task group id or title", "Implementation")
+    .option("--task-id <taskId>", "Explicit task id")
+    .option("-s, --status <status>", "Initial status: todo, in-progress, done", "todo")
+    .action(async (idOrPath: string, title: string, options: { group?: string; taskId?: string; status?: TaskStatus }) => {
+      assertTaskStatus(options.status);
+      await mutateSpec(idOrPath, (data) => addTask(data, title, options));
+    });
+
+  for (const [name, status] of [
+    ["todo", "todo"],
+    ["start", "in-progress"],
+    ["in-progress", "in-progress"],
+    ["done", "done"],
+  ] as const) {
+    task
+      .command(`${name} <id-or-path> <task-id>`)
+      .description(`Mark a task ${status}`)
+      .action(async (idOrPath: string, taskId: string) => {
+        await mutateSpec(idOrPath, (data) => setTaskStatus(data, taskId, status));
+      });
+  }
+
+  const spec = program.command("spec").description("Update the spec section");
+
+  spec
+    .command("update <id-or-path>")
+    .description("Replace spec.overviewHtml from HTML, or spec from a JSON object")
+    .option("-f, --from <file>", "Read content from file")
+    .option("-m, --message <html>", "Inline HTML or JSON")
+    .action(async (idOrPath: string, options: { from?: string; message?: string }) => {
+      const content = await readInputContent(options);
+      await mutateSpec(idOrPath, (data) => updateSpecSection(data, content));
+    });
+
+  const design = program.command("design").description("Update the design section");
+
+  design
+    .command("update <id-or-path>")
+    .description("Replace design.overviewHtml from HTML, or design from a JSON object")
+    .option("-f, --from <file>", "Read content from file")
+    .option("-m, --message <html>", "Inline HTML or JSON")
+    .action(async (idOrPath: string, options: { from?: string; message?: string }) => {
+      const content = await readInputContent(options);
+      await mutateSpec(idOrPath, (data) => updateDesignSection(data, content));
+    });
+
+  program
+    .command("summary <id-or-path>")
+    .description("Update summaryHtml")
+    .option("-f, --from <file>", "Read content from file")
+    .option("-m, --message <html>", "Inline HTML")
+    .action(async (idOrPath: string, options: { from?: string; message?: string }) => {
+      const content = await readInputContent(options);
+      await mutateSpec(idOrPath, (data) => {
+        data.summaryHtml = content.trim();
+        return touch(data, "summary:updated");
+      });
+    });
+
+  program
+    .command("state <id-or-path> <status>")
+    .description("Set change status: draft, ready, in-progress, done, archived")
+    .action(async (idOrPath: string, status: ChangeStatus) => {
+      assertChangeStatus(status);
+      await mutateSpec(idOrPath, (data) => setChangeStatus(data, status));
+    });
+
+  await program.parseAsync(argv);
+}
+
+async function mutateSpec(idOrPath: string, mutate: (data: HtmlSpecData) => HtmlSpecData): Promise<void> {
+  const filePath = resolveExistingSpecPath(idOrPath);
+  const data = mutate(await readSpecData(filePath));
+  await writeSpecData(filePath, data);
+  console.log(`Updated ${titleizePath(filePath)}`);
+}
+
+async function resolvePatchOperations(
+  patchFile: string | undefined,
+  options: { patch?: string; from?: string; replace?: string; value?: string; valueFrom?: string; stringValue?: string },
+) {
+  const sources = [patchFile, options.from, options.patch, options.replace].filter(Boolean);
+  if (sources.length !== 1) {
+    throw new Error("Provide exactly one of [patch-file], --from, --patch, or --replace");
+  }
+
+  if (options.replace) {
+    const valueOptions = [options.value, options.valueFrom, options.stringValue].filter((value) => value !== undefined);
+    if (valueOptions.length !== 1) {
+      throw new Error("Use --replace with exactly one of --value, --value-from, or --string-value");
+    }
+
+    return assertJsonPatch([
+      {
+        op: "replace",
+        path: options.replace,
+        value: await resolveReplacementValue(options),
+      },
+    ]);
+  }
+
+  const raw = options.patch ?? await readFile(options.from ?? patchFile!, "utf8");
+  return assertJsonPatch(JSON.parse(raw));
+}
+
+async function resolveReplacementValue(options: { value?: string; valueFrom?: string; stringValue?: string }): Promise<unknown> {
+  if (options.stringValue !== undefined) return options.stringValue;
+  if (options.valueFrom) return JSON.parse(await readFile(options.valueFrom, "utf8"));
+  if (options.value !== undefined) return JSON.parse(options.value);
+  throw new Error("Missing replacement value");
+}
+
+function updateSpecSection(data: HtmlSpecData, content: string): HtmlSpecData {
+  const trimmed = content.trim();
+  const parsed = tryParseJson(trimmed);
+
+  if (parsed && Array.isArray(parsed)) {
+    data.spec.operations = parsed.every((item) => item && typeof item === "object" && "type" in item)
+      ? parsed as SpecSection["operations"]
+      : [{ type: "ADDED", requirements: parsed as SpecSection["operations"][number]["requirements"] }];
+  } else if (parsed && typeof parsed === "object") {
+    data.spec = parsed as SpecSection;
+  } else {
+    data.spec.overviewHtml = trimmed;
+  }
+
+  return touch(data, "spec:updated");
+}
+
+function updateDesignSection(data: HtmlSpecData, content: string): HtmlSpecData {
+  const trimmed = content.trim();
+  const parsed = tryParseJson(trimmed);
+
+  if (parsed && Array.isArray(parsed)) {
+    data.design.decisions = parsed;
+  } else if (parsed && typeof parsed === "object") {
+    data.design = parsed as Design;
+  } else {
+    data.design.contextHtml = trimmed;
+  }
+
+  return touch(data, "design:updated");
+}
+
+function tryParseJson(content: string): unknown | undefined {
+  if (!content.startsWith("{") && !content.startsWith("[")) return undefined;
+  return JSON.parse(content);
+}
+
+async function listEntries(): Promise<ListEntry[]> {
+  const dirs: Array<[ListEntry["kind"], string]> = [
+    ["change", projectPath("spec", "changes")],
+    ["spec", projectPath("spec", "specs")],
+    ["archive", projectPath("spec", "archive")],
+  ];
+  const entries: ListEntry[] = [];
+
+  for (const [kind, dir] of dirs) {
+    if (!existsSync(dir)) continue;
+    const files = (await readdir(dir)).filter((file) => file.endsWith(".html")).sort();
+    for (const file of files) {
+      const filePath = join(dir, file);
+      const id = basename(file, ".html");
+      try {
+        entries.push({ kind, id, path: filePath, data: await readSpecData(filePath) });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        entries.push({ kind, id, path: filePath, error: message });
+      }
+    }
+  }
+
+  return entries;
+}
+
+async function validateFile(path: string): Promise<{ path: string; valid: boolean; issues: string[] }> {
+  try {
+    const data = await readSpecData(path);
+    const issues = validateSpecData(data);
+    return { path, valid: issues.length === 0, issues };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { path, valid: false, issues: [message] };
+  }
+}
+
+function printSummary(data: HtmlSpecData, filePath: string): void {
+  const counts = countTasks(data);
+  console.log(`${data.title} (${data.id})`);
+  console.log(`Path: ${titleizePath(filePath)}`);
+  console.log(`Status: ${data.status}`);
+  console.log(`Tasks: ${counts.done}/${counts.total} done, ${counts.inProgress} in progress`);
+  console.log(`Updated: ${data.updatedAt}`);
+}
+
+function printTaskStatus(data: HtmlSpecData): void {
+  console.log(`${data.title} (${data.id})`);
+  for (const group of data.tasks) {
+    console.log(`\n${group.id}. ${group.title}`);
+    for (const item of group.items) {
+      console.log(`${taskMark(item.status)} ${item.id} ${item.title}`);
+    }
+  }
+}
+
+function taskMark(status: TaskStatus): string {
+  if (status === "done") return "[x]";
+  if (status === "in-progress") return "[~]";
+  return "[ ]";
+}
+
+function countTasks(data: HtmlSpecData): { total: number; done: number; inProgress: number } {
+  const tasks = data.tasks.flatMap((group) => group.items);
+  return {
+    total: tasks.length,
+    done: tasks.filter((task) => task.status === "done").length,
+    inProgress: tasks.filter((task) => task.status === "in-progress").length,
+  };
+}
+
+function assertTaskStatus(status: string | undefined): asserts status is TaskStatus {
+  if (!status || !["todo", "in-progress", "done"].includes(status)) {
+    throw new Error("Task status must be todo, in-progress, or done");
+  }
+}
+
+function assertChangeStatus(status: string): asserts status is ChangeStatus {
+  if (!["draft", "ready", "in-progress", "done", "archived"].includes(status)) {
+    throw new Error("Status must be draft, ready, in-progress, done, or archived");
+  }
+}

package/src/html-document.ts

@@ -0,0 +1,56 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { parse } from "parse5";
+import type { HtmlSpecData } from "./types";
+
+function findSpecScript(node: any): any | undefined {
+  if (node?.tagName === "script") {
+    const id = node.attrs?.find((attr: { name: string; value: string }) => attr.name === "id")?.value;
+    if (id === "SPEC") return node;
+  }
+
+  for (const child of node?.childNodes ?? []) {
+    const result = findSpecScript(child);
+    if (result) return result;
+  }
+
+  return undefined;
+}
+
+function getSpecJsonRange(html: string): { start: number; end: number } {
+  const document = parse(html, { sourceCodeLocationInfo: true });
+  const script = findSpecScript(document);
+
+  if (!script?.sourceCodeLocation?.startTag || !script?.sourceCodeLocation?.endTag) {
+    throw new Error('Missing <script id="SPEC" type="application/json"> payload');
+  }
+
+  const start = script.sourceCodeLocation.startTag.endOffset;
+  const end = script.sourceCodeLocation.endTag.startOffset;
+
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start > end) {
+    throw new Error("Could not locate SPEC script content range");
+  }
+
+  return { start, end };
+}
+
+export async function readSpecData(filePath: string): Promise<HtmlSpecData> {
+  const html = await readFile(filePath, "utf8");
+  const { start, end } = getSpecJsonRange(html);
+  const rawJson = html.slice(start, end).trim();
+
+  try {
+    return JSON.parse(rawJson) as HtmlSpecData;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid SPEC JSON in ${filePath}: ${message}`);
+  }
+}
+
+export async function writeSpecData(filePath: string, data: HtmlSpecData): Promise<void> {
+  const html = await readFile(filePath, "utf8");
+  const { start, end } = getSpecJsonRange(html);
+  const nextJson = JSON.stringify(data, null, 2).replace(/<\/script/gi, "<\\/script");
+  const nextHtml = `${html.slice(0, start)}\n${nextJson}\n${html.slice(end)}`;
+  await writeFile(filePath, nextHtml, "utf8");
+}