htmlspec-kit 0.1.0

package/src/json-patch.ts

@@ -0,0 +1,177 @@
+type JsonValue = unknown;
+
+export type JsonPatchOperation =
+  | { op: "add" | "replace" | "test"; path: string; value: JsonValue }
+  | { op: "remove"; path: string }
+  | { op: "move" | "copy"; from: string; path: string };
+
+type PointerToken = string | number | "-";
+
+export function applyJsonPatch<T>(document: T, operations: JsonPatchOperation[]): T {
+  let current: unknown = document;
+
+  for (const operation of operations) {
+    switch (operation.op) {
+      case "add":
+        current = setAtPointer(current, operation.path, cloneJson(operation.value), "add");
+        break;
+      case "replace":
+        current = setAtPointer(current, operation.path, cloneJson(operation.value), "replace");
+        break;
+      case "remove":
+        current = removeAtPointer(current, operation.path);
+        break;
+      case "copy":
+        current = setAtPointer(current, operation.path, cloneJson(getAtPointer(current, operation.from)), "add");
+        break;
+      case "move": {
+        const value = cloneJson(getAtPointer(current, operation.from));
+        current = removeAtPointer(current, operation.from);
+        current = setAtPointer(current, operation.path, value, "add");
+        break;
+      }
+      case "test":
+        if (JSON.stringify(getAtPointer(current, operation.path)) !== JSON.stringify(operation.value)) {
+          throw new Error(`JSON Patch test failed at ${operation.path}`);
+        }
+        break;
+      default:
+        throw new Error(`Unsupported JSON Patch op ${(operation as { op: string }).op}`);
+    }
+  }
+
+  return current as T;
+}
+
+export function assertJsonPatch(value: unknown): JsonPatchOperation[] {
+  if (!Array.isArray(value)) {
+    throw new Error("JSON Patch must be an array of operations");
+  }
+
+  for (const [index, operation] of value.entries()) {
+    if (!operation || typeof operation !== "object") {
+      throw new Error(`JSON Patch operation ${index} must be an object`);
+    }
+    const op = operation as Record<string, unknown>;
+    if (typeof op.op !== "string" || typeof op.path !== "string") {
+      throw new Error(`JSON Patch operation ${index} requires string op and path`);
+    }
+    if ((op.op === "add" || op.op === "replace" || op.op === "test") && !("value" in op)) {
+      throw new Error(`JSON Patch operation ${index} requires value`);
+    }
+    if ((op.op === "move" || op.op === "copy") && typeof op.from !== "string") {
+      throw new Error(`JSON Patch operation ${index} requires string from`);
+    }
+    if (!["add", "replace", "remove", "move", "copy", "test"].includes(op.op)) {
+      throw new Error(`JSON Patch operation ${index} has unsupported op ${op.op}`);
+    }
+  }
+
+  return value as JsonPatchOperation[];
+}
+
+function getAtPointer(document: unknown, pointer: string): unknown {
+  const tokens = parsePointer(pointer);
+  let current = document;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      if (token === "-") throw new Error(`Cannot read array append token in ${pointer}`);
+      current = current[numberToken(token)];
+    } else if (isRecord(current)) {
+      current = current[String(token)];
+    } else {
+      throw new Error(`Cannot resolve ${pointer}`);
+    }
+  }
+  return current;
+}
+
+function setAtPointer(document: unknown, pointer: string, value: unknown, mode: "add" | "replace"): unknown {
+  const tokens = parsePointer(pointer);
+  if (tokens.length === 0) return value;
+
+  const { parent, token } = parentFor(document, tokens, pointer);
+  if (Array.isArray(parent)) {
+    if (token === "-") {
+      if (mode === "replace") throw new Error(`Cannot replace array append token in ${pointer}`);
+      parent.push(value);
+      return document;
+    }
+    const index = numberToken(token);
+    if (mode === "replace" && index >= parent.length) {
+      throw new Error(`Cannot replace missing array index ${index} in ${pointer}`);
+    }
+    if (mode === "add") parent.splice(index, 0, value);
+    else parent[index] = value;
+    return document;
+  }
+
+  if (!isRecord(parent)) throw new Error(`Cannot set ${pointer}`);
+  if (mode === "replace" && !(String(token) in parent)) {
+    throw new Error(`Cannot replace missing key ${String(token)} in ${pointer}`);
+  }
+  parent[String(token)] = value;
+  return document;
+}
+
+function removeAtPointer(document: unknown, pointer: string): unknown {
+  const tokens = parsePointer(pointer);
+  if (tokens.length === 0) return undefined;
+
+  const { parent, token } = parentFor(document, tokens, pointer);
+  if (Array.isArray(parent)) {
+    if (token === "-") throw new Error(`Cannot remove array append token in ${pointer}`);
+    parent.splice(numberToken(token), 1);
+    return document;
+  }
+
+  if (!isRecord(parent) || !(String(token) in parent)) {
+    throw new Error(`Cannot remove missing key ${String(token)} in ${pointer}`);
+  }
+  delete parent[String(token)];
+  return document;
+}
+
+function parentFor(document: unknown, tokens: PointerToken[], pointer: string): { parent: unknown; token: PointerToken } {
+  let parent = document;
+  for (const token of tokens.slice(0, -1)) {
+    if (Array.isArray(parent)) {
+      if (token === "-") throw new Error(`Cannot traverse array append token in ${pointer}`);
+      parent = parent[numberToken(token)];
+    } else if (isRecord(parent)) {
+      parent = parent[String(token)];
+    } else {
+      throw new Error(`Cannot resolve parent for ${pointer}`);
+    }
+  }
+
+  return { parent, token: tokens[tokens.length - 1]! };
+}
+
+function parsePointer(pointer: string): PointerToken[] {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) throw new Error(`Invalid JSON Pointer ${pointer}`);
+  return pointer
+    .slice(1)
+    .split("/")
+    .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+function numberToken(token: PointerToken): number {
+  if (typeof token === "number") return token;
+  if (token === "-") throw new Error("Expected array index, got append token");
+  const index = Number.parseInt(token, 10);
+  if (!Number.isInteger(index) || String(index) !== token || index < 0) {
+    throw new Error(`Invalid array index ${token}`);
+  }
+  return index;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneJson<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/paths.ts

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SPEC_ROOT, slugify } from "./spec-data";
+
+export function projectPath(...parts: string[]): string {
+  return resolve(process.cwd(), ...parts);
+}
+
+export function specRoot(): string {
+  return projectPath(SPEC_ROOT);
+}
+
+export function changePath(id: string): string {
+  return projectPath(SPEC_ROOT, "changes", `${slugify(id)}.html`);
+}
+
+export function templateSourcePath(): string {
+  return fileURLToPath(new URL("../skills/htmlspec-kit/assets/change-template.html", import.meta.url));
+}
+
+export async function ensureSpecLayout(): Promise<void> {
+  await mkdir(projectPath(SPEC_ROOT, "changes"), { recursive: true });
+  await mkdir(projectPath(SPEC_ROOT, "specs"), { recursive: true });
+  await mkdir(projectPath(SPEC_ROOT, "archive"), { recursive: true });
+  await mkdir(projectPath(SPEC_ROOT, "templates"), { recursive: true });
+}
+
+export async function copyTemplate(force = false): Promise<string> {
+  await ensureSpecLayout();
+  const destination = projectPath(SPEC_ROOT, "templates", "change-template.html");
+  if (!force && existsSync(destination)) return destination;
+
+  await mkdir(dirname(destination), { recursive: true });
+  const template = await readFile(templateSourcePath(), "utf8");
+  await writeFile(destination, template, "utf8");
+  return destination;
+}
+
+export function resolveExistingSpecPath(idOrPath: string): string {
+  const direct = resolve(process.cwd(), idOrPath);
+  if (existsSync(direct)) return direct;
+
+  const normalized = extname(idOrPath) === ".html" ? idOrPath.slice(0, -5) : idOrPath;
+  const id = slugify(normalized);
+  const candidates = [
+    projectPath(SPEC_ROOT, "changes", `${id}.html`),
+    projectPath(SPEC_ROOT, "specs", `${id}.html`),
+    projectPath(SPEC_ROOT, "archive", `${id}.html`),
+    projectPath(SPEC_ROOT, `${id}.html`),
+  ];
+
+  const match = candidates.find((candidate) => existsSync(candidate));
+  if (match) return match;
+
+  throw new Error(`Spec ${idOrPath} not found under ${SPEC_ROOT}/changes, ${SPEC_ROOT}/specs, or ${SPEC_ROOT}/archive`);
+}
+
+export async function readInputContent(options: { from?: string; message?: string }): Promise<string> {
+  if (options.from) {
+    return readFile(resolve(process.cwd(), options.from), "utf8");
+  }
+
+  if (options.message) return options.message;
+
+  if (!process.stdin.isTTY) {
+    return new Response(Bun.stdin.stream()).text();
+  }
+
+  throw new Error("Provide content with --from <file>, --message <html>, or stdin");
+}
+
+export function titleizePath(filePath: string): string {
+  return filePath.startsWith(process.cwd()) ? filePath.slice(process.cwd().length + 1) : filePath;
+}

package/src/spec-data.ts

@@ -0,0 +1,265 @@
+import type {
+  ChangeStatus,
+  Design,
+  HtmlSpecData,
+  SpecSection,
+  TaskGroup,
+  TaskItem,
+  TaskStatus,
+} from "./types";
+
+export const SPEC_ROOT = "spec";
+export const SPEC_SCRIPT_ID = "SPEC";
+export const FORMAT_VERSION = "0.1.0";
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+export function titleFromId(id: string): string {
+  return id
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export function createHtmlSpecData(id: string, title = titleFromId(id)): HtmlSpecData {
+  const at = nowIso();
+
+  return {
+    format: "htmlspec",
+    version: FORMAT_VERSION,
+    id,
+    title,
+    status: "draft",
+    owner: "agent",
+    createdAt: at,
+    updatedAt: at,
+    summaryHtml: "<p>One-paragraph summary of the change and why it matters.</p>",
+    proposal: {
+      whyHtml: "<p>Explain the motivation for this change. What problem does this solve? Why now?</p>",
+      whatChanges: [
+        "Describe new capabilities, modifications, or removals. Mark breaking changes with BREAKING.",
+      ],
+      capabilities: {
+        new: [
+          {
+            name: "capability-name",
+            description: "Brief description of the capability this change introduces.",
+          },
+        ],
+        modified: [],
+      },
+      impact: ["Affected code, APIs, dependencies, or systems."],
+    },
+    spec: createDefaultSpec(),
+    design: createDefaultDesign(),
+    tasks: createDefaultTasks(),
+    history: [{ at, action: "created" }],
+  };
+}
+
+export function createDefaultSpec(): SpecSection {
+  return {
+    overviewHtml: "<p>Create one requirements delta per capability listed in proposal.capabilities. Use SHALL/MUST and testable scenarios.</p>",
+    operations: [
+      {
+        type: "ADDED",
+        requirements: [
+          {
+            id: "REQ-001",
+            title: "Primary behavior",
+            bodyHtml: "<p>The system SHALL provide the user-visible behavior described by this change.</p>",
+            scenarios: [
+              {
+                id: "SCN-001",
+                title: "Happy path",
+                given: "the user is in the expected starting state",
+                when: "the user performs the new action",
+                then: "the system produces the expected result",
+              },
+            ],
+          }
+        ],
+      },
+    ],
+  };
+}
+
+export function createDefaultDesign(): Design {
+  return {
+    contextHtml: "<p>Describe background, current state, constraints, and stakeholders.</p>",
+    goals: ["State what this design achieves."],
+    nonGoals: ["State what is explicitly out of scope."],
+    decisions: [
+      {
+        id: "architecture",
+        title: "Architecture",
+        decisionHtml: "<p>Describe the key modules, data flow, and boundaries.</p>",
+        rationaleHtml: "<p>Explain why this approach is preferred.</p>",
+        alternatives: ["List meaningful alternatives considered."],
+      },
+    ],
+    risksTradeoffs: ["Risk or trade-off -> mitigation."],
+    migrationPlan: ["Deployment, rollback, or migration step if applicable."],
+    openQuestions: ["List unresolved decisions before implementation starts."],
+  };
+}
+
+export function createDefaultTasks(): TaskGroup[] {
+  return [
+    {
+      id: "1",
+      title: "Setup",
+      items: [
+        {
+          id: "1.1",
+          title: "Create or update module structure",
+          status: "todo",
+        },
+        {
+          id: "1.2",
+          title: "Add dependencies or configuration",
+          status: "todo",
+        },
+      ],
+    },
+    {
+      id: "2",
+      title: "Implementation",
+      items: [
+        {
+          id: "2.1",
+          title: "Implement behavior defined by the spec operations",
+          status: "todo",
+        },
+        {
+          id: "2.2",
+          title: "Add tests for each acceptance scenario",
+          status: "todo",
+        },
+      ],
+    },
+  ];
+}
+
+export function touch(data: HtmlSpecData, action: string): HtmlSpecData {
+  data.updatedAt = nowIso();
+  data.history.push({ at: data.updatedAt, action });
+  return data;
+}
+
+export function setChangeStatus(data: HtmlSpecData, status: ChangeStatus): HtmlSpecData {
+  data.status = status;
+  return touch(data, `status:${status}`);
+}
+
+export function findTask(data: HtmlSpecData, taskId: string): { group: TaskGroup; task: TaskItem } {
+  for (const group of data.tasks) {
+    const task = group.items.find((item) => item.id === taskId);
+    if (task) return { group, task };
+  }
+  throw new Error(`Task ${taskId} not found in ${data.id}`);
+}
+
+export function setTaskStatus(data: HtmlSpecData, taskId: string, status: TaskStatus): HtmlSpecData {
+  const { task } = findTask(data, taskId);
+  task.status = status;
+  return touch(data, `task:${taskId}:${status}`);
+}
+
+export function addTask(
+  data: HtmlSpecData,
+  title: string,
+  options: { group?: string; taskId?: string; status?: TaskStatus } = {},
+): HtmlSpecData {
+  const group = getOrCreateTaskGroup(data, options.group ?? "Implementation");
+  const id = options.taskId ?? nextTaskId(group);
+
+  if (group.items.some((item) => item.id === id)) {
+    throw new Error(`Task ${id} already exists in group ${group.id}`);
+  }
+
+  group.items.push({
+    id,
+    title,
+    status: options.status ?? "todo",
+  });
+
+  return touch(data, `task:${id}:added`);
+}
+
+function getOrCreateTaskGroup(data: HtmlSpecData, groupSelector: string): TaskGroup {
+  const existing = data.tasks.find(
+    (group) => group.id === groupSelector || group.title.toLowerCase() === groupSelector.toLowerCase(),
+  );
+  if (existing) return existing;
+
+  const numericIds = data.tasks
+    .map((group) => Number.parseInt(group.id, 10))
+    .filter((id) => Number.isInteger(id));
+  const nextId = String((numericIds.length ? Math.max(...numericIds) : 0) + 1);
+  const group = { id: nextId, title: groupSelector, items: [] };
+  data.tasks.push(group);
+  return group;
+}
+
+function nextTaskId(group: TaskGroup): string {
+  const numericIds = group.items
+    .map((item) => {
+      const suffix = item.id.split(".").at(-1);
+      return suffix ? Number.parseInt(suffix, 10) : Number.NaN;
+    })
+    .filter((id) => Number.isInteger(id));
+  const next = (numericIds.length ? Math.max(...numericIds) : 0) + 1;
+  return `${group.id}.${next}`;
+}
+
+export function validateSpecData(data: HtmlSpecData): string[] {
+  const issues: string[] = [];
+
+  if (data.format !== "htmlspec") issues.push("format must be htmlspec");
+  if (!data.id) issues.push("id is required");
+  if (!data.title) issues.push("title is required");
+  if (!data.spec || !Array.isArray(data.spec.operations)) issues.push("spec.operations must be an array");
+  if (!data.design || !Array.isArray(data.design.decisions)) issues.push("design.decisions must be an array");
+  if (!Array.isArray(data.tasks)) issues.push("tasks must be an array");
+
+  for (const operation of data.spec?.operations ?? []) {
+    if (!["ADDED", "MODIFIED", "REMOVED", "RENAMED"].includes(operation.type)) {
+      issues.push(`invalid spec operation ${operation.type}`);
+    }
+    for (const requirement of operation.requirements ?? []) {
+      if (!requirement.id || !requirement.title) issues.push("each requirement needs id and title");
+      if (!Array.isArray(requirement.scenarios) || requirement.scenarios.length === 0) {
+        issues.push(`requirement ${requirement.id} must have at least one scenario`);
+      }
+    }
+  }
+
+  const taskIds = new Set<string>();
+  for (const group of data.tasks ?? []) {
+    if (!group.id || !group.title) issues.push("each task group needs id and title");
+    for (const task of group.items ?? []) {
+      if (!task.id || !task.title) issues.push("each task needs id and title");
+      if (taskIds.has(task.id)) issues.push(`duplicate task id ${task.id}`);
+      taskIds.add(task.id);
+      if (!["todo", "in-progress", "done"].includes(task.status)) {
+        issues.push(`task ${task.id} has invalid status ${task.status}`);
+      }
+    }
+  }
+
+  return issues;
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+export type TaskStatus = "todo" | "in-progress" | "done";
+export type ChangeStatus = "draft" | "ready" | "in-progress" | "done" | "archived";
+export type DeltaOperation = "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
+
+export interface Capability {
+  name: string;
+  description: string;
+}
+
+export interface Scenario {
+  id: string;
+  title: string;
+  given?: string;
+  when: string;
+  then: string;
+}
+
+export interface Requirement {
+  id: string;
+  title: string;
+  bodyHtml: string;
+  scenarios: Scenario[];
+  reasonHtml?: string;
+  migrationHtml?: string;
+  from?: string;
+  to?: string;
+}
+
+export interface RequirementDelta {
+  type: DeltaOperation;
+  requirements: Requirement[];
+}
+
+export interface SpecSection {
+  overviewHtml: string;
+  operations: RequirementDelta[];
+}
+
+export interface DesignDecision {
+  id: string;
+  title: string;
+  decisionHtml: string;
+  rationaleHtml: string;
+  alternatives: string[];
+}
+
+export interface DesignSection {
+  id: string;
+  title: string;
+  bodyHtml: string;
+}
+
+export interface Design {
+  contextHtml: string;
+  goals: string[];
+  nonGoals: string[];
+  decisions: DesignDecision[];
+  risksTradeoffs: string[];
+  migrationPlan: string[];
+  openQuestions: string[];
+}
+
+export interface Proposal {
+  whyHtml: string;
+  whatChanges: string[];
+  capabilities: {
+    new: Capability[];
+    modified: Capability[];
+  };
+  impact: string[];
+}
+
+export interface TaskItem {
+  id: string;
+  title: string;
+  status: TaskStatus;
+  notes?: string;
+}
+
+export interface TaskGroup {
+  id: string;
+  title: string;
+  items: TaskItem[];
+}
+
+export interface HistoryEntry {
+  at: string;
+  action: string;
+}
+
+export interface HtmlSpecData {
+  format: "htmlspec";
+  version: string;
+  id: string;
+  title: string;
+  status: ChangeStatus;
+  owner: string;
+  createdAt: string;
+  updatedAt: string;
+  summaryHtml: string;
+  proposal: Proposal;
+  spec: SpecSection;
+  design: Design;
+  tasks: TaskGroup[];
+  history: HistoryEntry[];
+}