vplan 0.1.0

package/core/index.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod'
+
+/**
+ * Single source of truth for the VisualPlan component vocabulary.
+ *
+ * This module is imported by BOTH the browser runtime (for render-time zod
+ * validation) and the Node CLI (for static `check` and the `components`
+ * catalog printer), so it must stay free of any React, recharts, or mermaid
+ * imports. Keep it isomorphic.
+ */
+
+export const STATUS_VALUES = ['planned', 'active', 'done'] as const
+export const CHANGE_VALUES = ['add', 'modify', 'delete', 'move'] as const
+export const CHART_TYPE_VALUES = ['bar', 'line', 'pie'] as const
+export const CALLOUT_TYPE_VALUES = ['note', 'risk', 'decision', 'warn'] as const
+
+export const phaseSchema = z.object({
+  title: z.string().min(1, 'title is required'),
+  status: z.enum(STATUS_VALUES).default('planned'),
+})
+
+export const fileTreeSchema = z.object({
+  files: z
+    .array(
+      z.object({
+        path: z.string().min(1, 'each file needs a path'),
+        change: z.enum(CHANGE_VALUES),
+      }),
+    )
+    .min(1, 'files must list at least one entry'),
+})
+
+export const chartSchema = z.object({
+  type: z.enum(CHART_TYPE_VALUES),
+  title: z.string().optional(),
+  data: z
+    .array(z.object({ label: z.string(), value: z.number() }))
+    .min(1, 'data must have at least one point'),
+})
+
+export const compareSchema = z.object({
+  options: z
+    .array(
+      z.object({
+        name: z.string().min(1, 'each option needs a name'),
+        pros: z.array(z.string()).default([]),
+        cons: z.array(z.string()).default([]),
+        pick: z.boolean().optional(),
+      }),
+    )
+    .min(2, 'compare needs at least two options'),
+})
+
+export const calloutSchema = z.object({
+  type: z.enum(CALLOUT_TYPE_VALUES).default('note'),
+})
+
+export const questionsSchema = z.object({
+  items: z.array(z.string().min(1)).min(1, 'questions needs at least one item'),
+})
+
+export const checklistSchema = z.object({
+  title: z.string().optional(),
+  items: z
+    .array(
+      z.object({
+        text: z.string().min(1, 'each item needs text'),
+        done: z.boolean().default(false),
+      }),
+    )
+    .min(1, 'checklist needs at least one item'),
+})
+
+/** Describes a component for the `components` printer and the static checker. */
+export interface CatalogEntry {
+  name: string
+  summary: string
+  /** Props the CLI can statically validate from MDX source (string-literal enums). */
+  staticEnums: Record<string, readonly string[]>
+  example: string
+}
+
+export const CATALOG: readonly CatalogEntry[] = [
+  {
+    name: 'Phase',
+    summary: 'A collapsible plan stage with a status badge. Wraps markdown.',
+    staticEnums: { status: STATUS_VALUES },
+    example: '<Phase title="Build the API" status="active">\n  1. Define routes\n</Phase>',
+  },
+  {
+    name: 'FileTree',
+    summary:
+      'A nested directory tree of file changes, built from the paths, with add/modify/delete/move markers.',
+    staticEnums: {},
+    example:
+      '<FileTree files={[{ path: "src/api/routes.ts", change: "add" }, { path: "src/api/db.ts", change: "modify" }, { path: "src/legacy.ts", change: "delete" }]} />',
+  },
+  {
+    name: 'Chart',
+    summary: 'A bar/line/pie chart for estimates or metrics.',
+    staticEnums: { type: CHART_TYPE_VALUES },
+    example:
+      '<Chart type="bar" title="Effort (days)" data={[{ label: "API", value: 3 }, { label: "UI", value: 2 }]} />',
+  },
+  {
+    name: 'Compare',
+    summary: 'Side-by-side option cards for weighing approaches.',
+    staticEnums: {},
+    example:
+      '<Compare options={[{ name: "Postgres", pros: ["ACID"], cons: ["ops"], pick: true }, { name: "SQLite", pros: ["simple"], cons: ["scale"] }]} />',
+  },
+  {
+    name: 'Callout',
+    summary: 'A highlighted note/risk/decision/warning block. Wraps markdown.',
+    staticEnums: { type: CALLOUT_TYPE_VALUES },
+    example: '<Callout type="risk">\n  Migration locks the table for ~2s.\n</Callout>',
+  },
+  {
+    name: 'Questions',
+    summary:
+      'Open questions you (Claude) want the reader to weigh in on before building, as a highlighted panel.',
+    staticEnums: {},
+    example:
+      '<Questions items={["Should refresh tokens rotate on every use?", "Is a 15-minute access-token TTL acceptable?"]} />',
+  },
+  {
+    name: 'Checklist',
+    summary: 'Acceptance criteria / definition of done, with done and todo states.',
+    staticEnums: {},
+    example:
+      '<Checklist title="Done when" items={[{ text: "Returns 429 over the limit", done: true }, { text: "Dashboards live" }]} />',
+  },
+  {
+    name: 'mermaid (code fence)',
+    summary:
+      'A flowchart, sequence, state, class, ER, or XY-chart diagram. Write a ```mermaid fenced block. (gantt/pie are not supported by the renderer.)',
+    staticEnums: {},
+    example: '```mermaid\nflowchart LR\n  A[Client] --> B[API] --> C[(DB)]\n```',
+  },
+]

package/dist/index.js

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// package.json
+var package_default = {
+  name: "vplan",
+  version: "0.1.0",
+  description: "Render Claude's plans as visual MDX pages instead of walls of text",
+  author: "Brandon Burrus <brandon@burrus.io>",
+  license: "MIT",
+  type: "module",
+  engines: {
+    node: ">=20.0.0"
+  },
+  bin: {
+    vplan: "./dist/index.js"
+  },
+  files: [
+    "dist",
+    "runtime",
+    "core"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsx src/index.ts",
+    typecheck: "tsc --noEmit",
+    vendor: "node scripts/vendor.mjs",
+    prepack: "node scripts/vendor.mjs && tsup"
+  },
+  dependencies: {
+    "@mdx-js/mdx": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "@mdx-js/rollup": "^3.1.1",
+    "@tabler/icons-react": "^3.44.0",
+    "beautiful-mermaid": "^1.1.3",
+    commander: "^15.0.0",
+    open: "^11.0.0",
+    react: "^19.2.7",
+    "react-dom": "^19.2.7",
+    recharts: "^3.8.1",
+    "rehype-expressive-code": "^0.43.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "remark-parse": "^11.0.0",
+    unified: "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    vite: "^8.0.16",
+    "vite-plugin-singlefile": "^2.3.3",
+    zod: "^4.4.3"
+  },
+  devDependencies: {
+    "@visualplan/core": "workspace:*",
+    "@visualplan/runtime": "workspace:*"
+  }
+};
+
+// src/commands/check.ts
+import { resolve } from "path";
+
+// src/build/check.ts
+import { readFile } from "fs/promises";
+import { compile } from "@mdx-js/mdx";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdxFrontmatter from "remark-mdx-frontmatter";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+
+// ../core/src/index.ts
+import { z } from "zod";
+var STATUS_VALUES = ["planned", "active", "done"];
+var CHANGE_VALUES = ["add", "modify", "delete", "move"];
+var CHART_TYPE_VALUES = ["bar", "line", "pie"];
+var CALLOUT_TYPE_VALUES = ["note", "risk", "decision", "warn"];
+var phaseSchema = z.object({
+  title: z.string().min(1, "title is required"),
+  status: z.enum(STATUS_VALUES).default("planned")
+});
+var fileTreeSchema = z.object({
+  files: z.array(
+    z.object({
+      path: z.string().min(1, "each file needs a path"),
+      change: z.enum(CHANGE_VALUES)
+    })
+  ).min(1, "files must list at least one entry")
+});
+var chartSchema = z.object({
+  type: z.enum(CHART_TYPE_VALUES),
+  title: z.string().optional(),
+  data: z.array(z.object({ label: z.string(), value: z.number() })).min(1, "data must have at least one point")
+});
+var compareSchema = z.object({
+  options: z.array(
+    z.object({
+      name: z.string().min(1, "each option needs a name"),
+      pros: z.array(z.string()).default([]),
+      cons: z.array(z.string()).default([]),
+      pick: z.boolean().optional()
+    })
+  ).min(2, "compare needs at least two options")
+});
+var calloutSchema = z.object({
+  type: z.enum(CALLOUT_TYPE_VALUES).default("note")
+});
+var questionsSchema = z.object({
+  items: z.array(z.string().min(1)).min(1, "questions needs at least one item")
+});
+var checklistSchema = z.object({
+  title: z.string().optional(),
+  items: z.array(
+    z.object({
+      text: z.string().min(1, "each item needs text"),
+      done: z.boolean().default(false)
+    })
+  ).min(1, "checklist needs at least one item")
+});
+var CATALOG = [
+  {
+    name: "Phase",
+    summary: "A collapsible plan stage with a status badge. Wraps markdown.",
+    staticEnums: { status: STATUS_VALUES },
+    example: '<Phase title="Build the API" status="active">\n  1. Define routes\n</Phase>'
+  },
+  {
+    name: "FileTree",
+    summary: "A nested directory tree of file changes, built from the paths, with add/modify/delete/move markers.",
+    staticEnums: {},
+    example: '<FileTree files={[{ path: "src/api/routes.ts", change: "add" }, { path: "src/api/db.ts", change: "modify" }, { path: "src/legacy.ts", change: "delete" }]} />'
+  },
+  {
+    name: "Chart",
+    summary: "A bar/line/pie chart for estimates or metrics.",
+    staticEnums: { type: CHART_TYPE_VALUES },
+    example: '<Chart type="bar" title="Effort (days)" data={[{ label: "API", value: 3 }, { label: "UI", value: 2 }]} />'
+  },
+  {
+    name: "Compare",
+    summary: "Side-by-side option cards for weighing approaches.",
+    staticEnums: {},
+    example: '<Compare options={[{ name: "Postgres", pros: ["ACID"], cons: ["ops"], pick: true }, { name: "SQLite", pros: ["simple"], cons: ["scale"] }]} />'
+  },
+  {
+    name: "Callout",
+    summary: "A highlighted note/risk/decision/warning block. Wraps markdown.",
+    staticEnums: { type: CALLOUT_TYPE_VALUES },
+    example: '<Callout type="risk">\n  Migration locks the table for ~2s.\n</Callout>'
+  },
+  {
+    name: "Questions",
+    summary: "Open questions you (Claude) want the reader to weigh in on before building, as a highlighted panel.",
+    staticEnums: {},
+    example: '<Questions items={["Should refresh tokens rotate on every use?", "Is a 15-minute access-token TTL acceptable?"]} />'
+  },
+  {
+    name: "Checklist",
+    summary: "Acceptance criteria / definition of done, with done and todo states.",
+    staticEnums: {},
+    example: '<Checklist title="Done when" items={[{ text: "Returns 429 over the limit", done: true }, { text: "Dashboards live" }]} />'
+  },
+  {
+    name: "mermaid (code fence)",
+    summary: "A flowchart, sequence, state, class, ER, or XY-chart diagram. Write a ```mermaid fenced block. (gantt/pie are not supported by the renderer.)",
+    staticEnums: {},
+    example: "```mermaid\nflowchart LR\n  A[Client] --> B[API] --> C[(DB)]\n```"
+  }
+];
+
+// src/build/check.ts
+var COMPONENT_NAMES = CATALOG.filter((entry) => /^[A-Z][A-Za-z0-9]*$/.test(entry.name)).map(
+  (entry) => entry.name
+);
+var ENUMS_BY_COMPONENT = new Map(CATALOG.map((entry) => [entry.name, entry.staticEnums]));
+async function checkPlan(mdxPath) {
+  const source = await readFile(mdxPath, "utf8");
+  const issues = [];
+  try {
+    await compile(source, {
+      remarkPlugins: [
+        remarkFrontmatter,
+        [remarkMdxFrontmatter, { name: "frontmatter" }],
+        remarkGfm
+      ]
+    });
+  } catch (error) {
+    const vfileError = error;
+    return [
+      {
+        line: vfileError.line ?? 1,
+        column: vfileError.column ?? 1,
+        message: vfileError.reason ?? vfileError.message ?? "MDX failed to compile"
+      }
+    ];
+  }
+  const tree = unified().use(remarkParse).use(remarkFrontmatter).use(remarkMdx).parse(source);
+  visit(tree, (node) => {
+    const element = node;
+    if (element.type !== "mdxJsxFlowElement" && element.type !== "mdxJsxTextElement") return;
+    const name = element.name;
+    if (!name) return;
+    const at = element.position?.start ?? { line: 1, column: 1 };
+    if (!COMPONENT_NAMES.includes(name)) {
+      issues.push({
+        line: at.line,
+        column: at.column,
+        message: `Unknown component <${name}>. Valid components: ${COMPONENT_NAMES.join(", ")}.`
+      });
+      return;
+    }
+    const enums = ENUMS_BY_COMPONENT.get(name) ?? {};
+    for (const [prop, allowed] of Object.entries(enums)) {
+      const attribute = element.attributes?.find(
+        (candidate) => candidate.type === "mdxJsxAttribute" && candidate.name === prop
+      );
+      if (attribute && typeof attribute.value === "string" && !allowed.includes(attribute.value)) {
+        issues.push({
+          line: at.line,
+          column: at.column,
+          message: `<${name}> prop ${prop}="${attribute.value}" is invalid. Valid: ${allowed.join(", ")}.`
+        });
+      }
+    }
+  });
+  return issues;
+}
+
+// src/commands/check.ts
+function printIssues(file, issues) {
+  for (const issue of issues) {
+    process.stderr.write(`${file}:${issue.line}:${issue.column}  ${issue.message}
+`);
+  }
+}
+async function runCheck(file) {
+  const issues = await checkPlan(resolve(file));
+  if (issues.length === 0) {
+    process.stdout.write(`${file} is valid
+`);
+    return;
+  }
+  printIssues(file, issues);
+  process.stdout.write(`
+${issues.length} issue(s) found
+`);
+  process.exitCode = 1;
+}
+
+// src/commands/components.ts
+function runComponents() {
+  const lines = [
+    "VisualPlan components \u2014 use these directly in a plan .mdx (no imports):",
+    ""
+  ];
+  for (const entry of CATALOG) {
+    lines.push(`${entry.name}`);
+    lines.push(`  ${entry.summary}`);
+    const enums = Object.entries(entry.staticEnums);
+    for (const [prop, values] of enums) {
+      lines.push(`  ${prop}: ${values.join(" | ")}`);
+    }
+    lines.push("  example:");
+    for (const exampleLine of entry.example.split("\n")) {
+      lines.push(`    ${exampleLine}`);
+    }
+    lines.push("");
+  }
+  lines.push("Start the plan with a `# Title` heading. Do not use YAML frontmatter.");
+  process.stdout.write(`${lines.join("\n")}
+`);
+}
+
+// src/commands/render.ts
+import { basename, dirname as dirname2, extname, join as join2, resolve as resolve3 } from "path";
+import open from "open";
+
+// src/build/compile.ts
+import { cp, mkdtemp, rm } from "fs/promises";
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import { tmpdir } from "os";
+import { dirname, join, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+import mdx from "@mdx-js/rollup";
+import rehypeExpressiveCode from "rehype-expressive-code";
+import remarkFrontmatter2 from "remark-frontmatter";
+import remarkGfm2 from "remark-gfm";
+import remarkMdxFrontmatter2 from "remark-mdx-frontmatter";
+import { build, createServer } from "vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+// src/build/remark-mermaid.ts
+import { visit as visit2 } from "unist-util-visit";
+function remarkMermaid() {
+  return (tree) => {
+    visit2(
+      tree,
+      "code",
+      (node, index, parent) => {
+        if (node.lang !== "mermaid" || !parent || index === void 0) return;
+        parent.children[index] = {
+          type: "mdxJsxFlowElement",
+          name: "Mermaid",
+          attributes: [{ type: "mdxJsxAttribute", name: "chart", value: node.value }],
+          children: []
+        };
+      }
+    );
+  };
+}
+
+// src/build/compile.ts
+var expressiveCodeOptions = {
+  themes: ["github-dark", "github-light"],
+  useDarkModeMediaQuery: true,
+  // The copy-button script does not execute reliably in our client-rendered SPA;
+  // frames (titles) are CSS-only, so keep those and drop the interactive button.
+  frames: { showCopyToClipboardButton: false },
+  // Match the flat ink design: our borders/radius/surfaces/fonts, no shadow, no
+  // colored tab accent. Values are CSS vars so the frame chrome tracks light/dark too.
+  styleOverrides: {
+    borderRadius: "10px",
+    borderColor: "var(--vp-border)",
+    codeBackground: "var(--vp-surface)",
+    codeFontFamily: "var(--vp-mono)",
+    codeFontSize: "0.8rem",
+    codeLineHeight: "1.6",
+    codePaddingBlock: "0.9rem",
+    codePaddingInline: "1rem",
+    uiFontFamily: "var(--vp-font)",
+    uiFontSize: "0.78rem",
+    frames: {
+      frameBoxShadowCssValue: "none",
+      // A flat filename header on the same surface as the code, separated by one
+      // border. No editor-tab metaphor, no colored indicator line.
+      editorBackground: "var(--vp-surface)",
+      editorTabBarBackground: "var(--vp-surface)",
+      editorTabBarBorderBottomColor: "var(--vp-border)",
+      editorActiveTabBackground: "var(--vp-surface)",
+      editorActiveTabForeground: "var(--vp-muted)",
+      editorActiveTabBorderColor: "transparent",
+      editorActiveTabIndicatorTopColor: "transparent",
+      editorActiveTabIndicatorBottomColor: "transparent",
+      editorTabsMarginInlineStart: "0",
+      terminalBackground: "var(--vp-surface)",
+      terminalTitlebarBackground: "var(--vp-surface)",
+      terminalTitlebarForeground: "var(--vp-muted)",
+      terminalTitlebarBorderBottomColor: "var(--vp-border)"
+    }
+  }
+};
+var require2 = createRequire(import.meta.url);
+function findRuntimePaths() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 6; depth++) {
+    const runtimeDir2 = join(dir, "runtime");
+    const coreEntry = join(dir, "core", "index.ts");
+    if (existsSync(join(runtimeDir2, "index.html")) && existsSync(coreEntry)) {
+      return { runtimeDir: runtimeDir2, coreEntry };
+    }
+    dir = dirname(dir);
+  }
+  const runtimeDir = dirname(require2.resolve("@visualplan/runtime/package.json"));
+  const coreDir = dirname(require2.resolve("@visualplan/core/package.json"));
+  return { runtimeDir, coreEntry: join(coreDir, "src", "index.ts") };
+}
+function mdxPlugin() {
+  return {
+    enforce: "pre",
+    ...mdx({
+      providerImportSource: "@mdx-js/react",
+      remarkPlugins: [
+        remarkFrontmatter2,
+        [remarkMdxFrontmatter2, { name: "frontmatter" }],
+        remarkGfm2,
+        // Must run before rehype-expressive-code so mermaid never reaches the highlighter.
+        remarkMermaid
+      ],
+      rehypePlugins: [[rehypeExpressiveCode, expressiveCodeOptions]]
+    })
+  };
+}
+function baseConfig(paths, mdxPath) {
+  return {
+    root: paths.runtimeDir,
+    configFile: false,
+    logLevel: "silent",
+    resolve: { alias: { "virtual:plan": mdxPath, "@visualplan/core": paths.coreEntry } },
+    esbuild: { jsx: "automatic", jsxImportSource: "react" },
+    plugins: [mdxPlugin()],
+    // The runtime, core, and the user's plan span sibling dirs (and a hoisted
+    // node_modules) in the monorepo, so the dev server cannot use a single allow
+    // root. This is a local tool rendering the user's own file, so fs is unrestricted.
+    server: { fs: { strict: false }, open: false }
+  };
+}
+async function renderToFile(mdxPath, outPath) {
+  const paths = findRuntimePaths();
+  const absMdx = resolve2(mdxPath);
+  const outDir = await mkdtemp(join(tmpdir(), "visualplan-build-"));
+  try {
+    const config = baseConfig(paths, absMdx);
+    await build({
+      ...config,
+      plugins: [...config.plugins ?? [], viteSingleFile()],
+      build: {
+        outDir,
+        emptyOutDir: true,
+        rollupOptions: { input: join(paths.runtimeDir, "index.html") }
+      }
+    });
+    await cp(join(outDir, "index.html"), resolve2(outPath));
+  } finally {
+    await rm(outDir, { recursive: true, force: true });
+  }
+}
+async function startDevServer(mdxPath) {
+  const paths = findRuntimePaths();
+  const absMdx = resolve2(mdxPath);
+  const server = await createServer(baseConfig(paths, absMdx));
+  await server.listen();
+  const url = server.resolvedUrls?.local[0] ?? `http://localhost:${server.config.server.port ?? 5173}`;
+  return {
+    url,
+    close: () => server.close()
+  };
+}
+
+// src/commands/render.ts
+function defaultOutPath(absMdx) {
+  const stem = basename(absMdx, extname(absMdx));
+  return join2(dirname2(absMdx), `${stem}.plan.html`);
+}
+async function runRender(file, options) {
+  const absMdx = resolve3(file);
+  const issues = await checkPlan(absMdx);
+  if (issues.length > 0) {
+    printIssues(file, issues);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.watch) {
+    const server = await startDevServer(absMdx);
+    process.stdout.write(
+      `VisualPlan watching ${file}
+  ${server.url}
+  (edit the file to hot-reload; Ctrl+C to stop)
+`
+    );
+    if (options.open !== false) await open(server.url);
+    return;
+  }
+  const out = options.out ? resolve3(options.out) : defaultOutPath(absMdx);
+  await renderToFile(absMdx, out);
+  process.stdout.write(`Rendered ${out}
+`);
+  if (options.open !== false) await open(out);
+}
+
+// src/index.ts
+var program = new Command("vplan").description("Render Claude plans as visual MDX pages instead of walls of text").version(package_default.version);
+program.command("render", { isDefault: true }).description("Compile a plan .mdx to a self-contained HTML page (default command)").argument("<file>", "the plan .mdx file to render").option("--watch", "start a hot-reloading dev server instead of writing a file").option("--out <path>", "output HTML path (defaults to <file>.plan.html)").option("--no-open", "do not open the result in a browser").action((file, options) => runRender(file, options));
+program.command("check").description("Validate a plan .mdx (compile + component checks) without rendering").argument("<file>", "the plan .mdx file to validate").action((file) => runCheck(file));
+program.command("components").description("Print the available plan components and their props").action(() => runComponents());
+program.parseAsync(process.argv).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map