@suzumiyaaoba/mdxr 0.1.0

package/src/catalog.ts

@@ -0,0 +1,287 @@
+import type { ComponentMap } from "./define.js";
+import { isRecord } from "./guards.js";
+import { builtinComponents } from "./ui/index.js";
+
+export interface PropInfo {
+  type: string;
+  required: boolean;
+  default?: unknown;
+}
+
+export interface CatalogEntry {
+  name: string;
+  source: "builtin" | "project";
+  description?: string;
+  props: Record<string, PropInfo>;
+}
+
+/** Structural view of a valibot schema — enough for catalog introspection. */
+const describeSchema = (schema: unknown): string => {
+  if (!isRecord(schema)) {
+    return "unknown";
+  }
+  if (schema.type === "array") {
+    return `${describeSchema(schema.item)}[]`;
+  }
+  if (schema.type === "literal") {
+    return JSON.stringify(schema.literal);
+  }
+  if (schema.type === "picklist" && Array.isArray(schema.options)) {
+    return schema.options.map((o: unknown) => JSON.stringify(o)).join(" | ");
+  }
+  if (schema.type === "union" && Array.isArray(schema.options)) {
+    return schema.options.map(describeSchema).join(" | ");
+  }
+  // `v.pipe(v.string(), v.toUpperCase(), v.picklist(M))` keeps `type:
+  // "string"` — the base type — and stores the actions in `.pipe`. The
+  // constrained member (picklist/union/literal) reads better than "string";
+  // transforms like trim/case don't describe accepted values.
+  if (Array.isArray(schema.pipe)) {
+    const pipe: unknown[] = schema.pipe;
+    const constrained = pipe.find(
+      (s) =>
+        isRecord(s) &&
+        (s.type === "picklist" || s.type === "union" || s.type === "literal")
+    );
+    if (constrained !== undefined) {
+      return describeSchema(constrained);
+    }
+  }
+  return typeof schema.type === "string" ? schema.type : "unknown";
+};
+
+// Wrapper schema types that mark a prop as non-required and may carry a
+// `default` (valibot's optional/nullish/nullable).
+const WRAPPER_TYPES = new Set(["nullable", "nullish", "optional"]);
+
+const unwrapProp = (
+  raw: unknown
+): { def: unknown; required: boolean; s: Record<string, unknown> } => {
+  let s: Record<string, unknown> = isRecord(raw) ? raw : {};
+  let required = true;
+  let def: unknown;
+  while (typeof s.type === "string" && WRAPPER_TYPES.has(s.type)) {
+    required = false;
+    // First (outermost) default wins: `v.optional(v.nullable(x, "a"), "b")`
+    // yields "b" for an absent prop — the inner default never applies.
+    def ??= s.default;
+    s = isRecord(s.wrapped) ? s.wrapped : {};
+  }
+  return { def, required, s };
+};
+
+const propsOf = (schema: unknown): Record<string, PropInfo> => {
+  if (!isRecord(schema) || !isRecord(schema.entries)) {
+    return {};
+  }
+  const out: Record<string, PropInfo> = {};
+  for (const [key, raw] of Object.entries(schema.entries)) {
+    const { def, required, s } = unwrapProp(raw);
+    // defineProperty, not assignment: a prop literally named "__proto__"
+    // would otherwise replace `out`'s prototype instead of being recorded.
+    Object.defineProperty(out, key, {
+      configurable: true,
+      enumerable: true,
+      value: {
+        required,
+        type: describeSchema(s),
+        ...(def === undefined ? {} : { default: def }),
+      },
+      writable: true,
+    });
+  }
+  return out;
+};
+
+const entryOf = (
+  name: string,
+  comp: ComponentMap[string],
+  source: CatalogEntry["source"]
+): CatalogEntry => ({
+  description: comp.__mdxr?.description,
+  name,
+  props: propsOf(comp.__mdxr?.schema),
+  source,
+});
+
+export const catalogEntries = (project: ComponentMap = {}): CatalogEntry[] => {
+  const entries: CatalogEntry[] = [];
+  for (const [name, comp] of Object.entries(builtinComponents)) {
+    // The `pre` override is a convention, not a JSX component.
+    if (!/^[A-Z]/u.test(name)) {
+      continue;
+    }
+    // A project override wins the slot wholesale: describe its schema, not
+    // the builtin's — the catalog documents what the document actually gets.
+    // hasOwn, not `in`: prototype names ("toString", "constructor") must not
+    // count as overrides via the prototype chain.
+    const overridden = Object.hasOwn(project, name);
+    const shown = overridden ? (project[name] ?? comp) : comp;
+    entries.push(entryOf(name, shown, overridden ? "project" : "builtin"));
+  }
+  for (const [name, comp] of Object.entries(project)) {
+    if (!Object.hasOwn(builtinComponents, name)) {
+      entries.push(entryOf(name, comp, "project"));
+    }
+  }
+  return entries;
+};
+
+/** Conventions the agent can use without JSX (kept in sync with remark plugins). */
+export const CONVENTIONS = [
+  {
+    result: "Callout (with kind)",
+    syntax:
+      ":::note | :::tip | :::warning | :::danger | :::decision | :::goal | :::nongoal | :::question | :::answer",
+  },
+  { result: "Phase", syntax: ':::phase{title="..." status="doing"}' },
+  { result: "Steps container", syntax: ":::steps" },
+  {
+    result: "Flow (numbered call/execution chain)",
+    syntax: ':::flow{title="..."}',
+  },
+  {
+    result: "Findings container / Finding block",
+    syntax: ':::findings · :::finding{confidence="inferred" title="..."}',
+  },
+  { result: "Files container (related files)", syntax: ":::files" },
+  { result: "Deps container (dependency edges)", syntax: ":::deps" },
+  { result: "Tests container (test report)", syntax: ":::tests" },
+  { result: "Endpoints container (API routes)", syntax: ":::endpoints" },
+  { result: "Board container (kanban)", syntax: ":::board" },
+  {
+    result: "Graph container (static node/edge SVG, dagre layout)",
+    syntax: ':::graph{title="..." direction="right"}',
+  },
+  { result: "Waterfall container (timing bars)", syntax: ":::waterfall" },
+  {
+    result: "Gantt container (date-based schedule)",
+    syntax: ':::gantt{title="..."}',
+  },
+  { result: "Matrix container (comparison grid)", syntax: ":::matrix" },
+  { result: "Timeline", syntax: ':::timeline{title="..."}' },
+  {
+    result: "Review container (code review report)",
+    syntax: ':::review{title="..." verdict="changes"}',
+  },
+  {
+    result: "Checks container (CI/verification status)",
+    syntax: ":::checks",
+  },
+  {
+    result: "Audit container (vulnerability inventory)",
+    syntax: ':::audit{tool="npm audit"}',
+  },
+  {
+    result: "Bumps container (dependency upgrades)",
+    syntax: ":::bumps",
+  },
+  {
+    result: "Packages container (dependency inventory)",
+    syntax: ":::packages",
+  },
+  {
+    result: "Gauges container (percent-bar rows: coverage, scores)",
+    syntax: ":::gauges",
+  },
+  {
+    result: "Benchmarks container (before/after comparisons)",
+    syntax: ':::benchmarks{better="lower"}',
+  },
+  {
+    result: "Schema container (DB table definitions)",
+    syntax: ":::schema",
+  },
+  {
+    result: "EnvVars container (environment variable docs)",
+    syntax: ":::envvars",
+  },
+  {
+    result: "StatusPage container (service health rollup)",
+    syntax: ":::statuspage",
+  },
+  {
+    result: "Uptime container (status-page day bars)",
+    syntax: ':::uptime{pct="99.9"}',
+  },
+  {
+    result: "Release container (changelog block)",
+    syntax: ':::release{version="v1.0.0"}',
+  },
+  {
+    result: "Pathway container (version/env stepper)",
+    syntax: ':::pathway{title="..."}',
+  },
+  {
+    result: "Incident header (postmortem card)",
+    syntax: ':::incident{title="..." severity="high"}',
+  },
+  {
+    result: "Verdict banner (approve/pass/warn/fail conclusion)",
+    syntax: ':::verdict{status="approve"}',
+  },
+  {
+    result: "chart containers (quantitative visualizations)",
+    syntax:
+      ":::barchart · :::linechart · :::piechart · :::scatter · :::radar · :::funnel · :::quadrant · :::bridge · :::treemap · :::sankey · :::venn",
+  },
+  { result: "table of contents (auto from headings)", syntax: ":::toc" },
+  { result: "Callout (GitHub alert)", syntax: "> [!NOTE] / [!WARNING] / ..." },
+  { result: "diagram (mermaid via CDN)", syntax: "```mermaid fenced block" },
+  {
+    result: "unified-diff cards (per-file headers, hunk line numbers)",
+    syntax: "```diff or ```patch fenced block",
+  },
+  { result: "math (KaTeX via CDN)", syntax: "$…$ inline / $$…$$ block" },
+  {
+    result: "code block (syntax-highlighted) with filename header",
+    syntax: '```lang title="file.ts"',
+  },
+  {
+    result: "FileRef chip (editor link when the file exists)",
+    syntax: "`src/x.ts` inline code naming a real file",
+  },
+  {
+    result: "code line highlights / line numbers",
+    syntax: "```ts {1,3-5} · ```ts ln · /word/ in meta",
+  },
+  {
+    result: "in-code markers (stripped from output)",
+    syntax:
+      "// [!code hl] · [!code ++] · [!code --] · [!code warning] · [!code error] · [!code focus] · [!code word:x]",
+  },
+  {
+    result: "embed a real file as a code block",
+    syntax: '<CodeFile path="src/x.ts" lines="40-52" />',
+  },
+  {
+    result: "styled markdown",
+    syntax: "GFM tables, task lists, strikethrough, footnotes",
+  },
+  {
+    result: "Iconify icon (inline SVG, lucide + vscode-icons bundled)",
+    syntax: '<Icon name="lucide:rocket"> or class="icon-[lucide--rocket]"',
+  },
+];
+
+export const formatCatalog = (entries: CatalogEntry[]): string => {
+  const lines: string[] = ["Components:", ""];
+  for (const e of entries) {
+    const props = Object.entries(e.props)
+      .map(([k, p]) => `${k}${p.required ? "" : "?"}: ${p.type}`)
+      .join(", ");
+    lines.push(`  <${e.name}${props === "" ? "" : ` ${props}`}>`);
+    if (e.description !== undefined) {
+      lines.push(`      ${e.description}`);
+    }
+    if (e.source === "project") {
+      lines.push("      (project-defined)");
+    }
+    lines.push("");
+  }
+  lines.push("Conventions:");
+  for (const c of CONVENTIONS) {
+    lines.push(`  ${c.syntax}  →  ${c.result}`);
+  }
+  return lines.join("\n");
+};

package/src/cli.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { cac } from "cac";
+
+import { catalogEntries, formatCatalog, CONVENTIONS } from "./catalog.js";
+import { loadConfig } from "./config.js";
+import { formatError, parseErrorFormat } from "./format-error.js";
+import { installSkill } from "./init.js";
+import { loadUserComponents, render, renderFile } from "./render.js";
+import { serve, serveSource } from "./serve.js";
+import { builtinComponents } from "./ui/index.js";
+
+const readStdin = async (): Promise<string> => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin as AsyncIterable<Buffer>) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+};
+
+const requireStdinSource = (): void => {
+  if (process.stdin.isTTY) {
+    throw new Error("no input: pass an .mdx file or pipe MDX source via stdin");
+  }
+};
+
+const fail = (err: unknown, json: boolean): never => {
+  if (json) {
+    console.log(JSON.stringify({ error: formatError(err), ok: false }));
+  } else {
+    console.error(`mdxr: error: ${formatError(err)}`);
+  }
+  process.exit(1);
+};
+
+const cli = cac("mdxr");
+
+cli
+  .command("render [file]", "Render an .mdx document to a standalone HTML file")
+  .option(
+    "-o, --out <path>",
+    "Output path (default: <file>.html; stdout for stdin input or '-')"
+  )
+  .option("--format <format>", "Error output: text | json")
+  .option(
+    "--no-hydrate",
+    "Emit static HTML without the client hydration bundle"
+  )
+  .action(
+    async (
+      file: string | undefined,
+      opts: { out?: string; format?: string; hydrate?: boolean }
+    ) => {
+      const json = opts.format === "json";
+      try {
+        parseErrorFormat(opts.format);
+        const fromStdin = file === undefined || file === "-";
+        if (fromStdin) {
+          requireStdinSource();
+        }
+
+        const html = fromStdin
+          ? await render(await readStdin(), {
+              dir: process.cwd(),
+              filePath: "<stdin>",
+              hydrate: opts.hydrate,
+            })
+          : await renderFile(file, { hydrate: opts.hydrate });
+
+        const out =
+          opts.out === "-"
+            ? undefined
+            : (opts.out ??
+              (fromStdin
+                ? undefined
+                : `${file.replace(/\.(?:mdx|md)$/u, "")}.html`));
+
+        if (out === undefined) {
+          // No status line: stdout carries the HTML itself. Downstream
+          // pipes (e.g. `| head`) may close early — EPIPE is not an error.
+          process.stdout.on("error", (err: NodeJS.ErrnoException) => {
+            if (err.code === "EPIPE") {
+              process.exit(0);
+            }
+            throw err;
+          });
+          process.stdout.write(html);
+          return;
+        }
+        await writeFile(path.resolve(out), html);
+        if (json) {
+          console.log(JSON.stringify({ ok: true, out }));
+        } else {
+          console.log(`mdxr: wrote ${out}`);
+        }
+      } catch (error) {
+        fail(error, json);
+      }
+    }
+  );
+
+cli
+  .command("serve [file]", "Preview a document in the browser with live reload")
+  .option("-p, --port <port>", "Port", { default: 3737 })
+  .action(async (file: string | undefined, opts: { port: number | string }) => {
+    try {
+      // mri leaves a non-numeric flag as a string; http.listen would treat
+      // that as a pipe path instead of a port.
+      const port = Number(opts.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error(`invalid --port: ${opts.port}`);
+      }
+      if (file === undefined || file === "-") {
+        requireStdinSource();
+        await serveSource(await readStdin(), port, {
+          dir: process.cwd(),
+          filePath: "<stdin>",
+        });
+        return;
+      }
+      await serve(file, port);
+    } catch (error) {
+      fail(error, false);
+    }
+  });
+
+cli
+  .command("catalog", "List available components (built-in + project-defined)")
+  .option("--json", "Print machine-readable JSON")
+  .option("--dir <dir>", "Project directory to read mdxr.config.ts from")
+  .action(async (opts: { json?: boolean; dir?: string }) => {
+    try {
+      const dir = path.resolve(opts.dir ?? process.cwd());
+      const config = await loadConfig(dir);
+      const user = await loadUserComponents(config);
+      const entries = catalogEntries(user.components);
+      if (opts.json === true) {
+        console.log(
+          JSON.stringify(
+            {
+              builtins: Object.keys(builtinComponents),
+              components: entries,
+              conventions: CONVENTIONS,
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(formatCatalog(entries));
+      }
+    } catch (error) {
+      fail(error, false);
+    }
+  });
+
+cli
+  .command("init", "Install the mdxr agent skill into this project")
+  .option("--tool <tool>", "agents | claude | devin | all", {
+    default: "agents",
+  })
+  .option("--global", "Install into your home directory instead of the project")
+  .option("--force", "Overwrite an existing skill")
+  .action(async (opts: { tool: string; global?: boolean; force?: boolean }) => {
+    try {
+      const paths = await installSkill(opts);
+      for (const p of paths) {
+        console.log(`mdxr: installed skill → ${p}`);
+      }
+    } catch (error) {
+      fail(error, false);
+    }
+  });
+
+cli.help();
+cli.parse();