@mzebley/mark-down-cli 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# mark↓ CLI
+*(published as `@mzebley/mark-down-cli`)*
+
+`mark-down` is the command-line companion to the mark↓ runtime. It scans Markdown snippets, parses YAML front matter, and emits a sorted `snippets-index.json` manifest consumed by [the core client](../core/README.md). For a full project overview, see the [monorepo README](../../README.md).
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+3. [Commands](#commands)
+4. [Configuration options](#configuration-options)
+5. [Watching for changes](#watching-for-changes)
+6. [Exit codes](#exit-codes)
+7. [Troubleshooting](#troubleshooting)
+8. [Roadmap](#roadmap)
+9. [Related packages](#related-packages)
+
+## Installation
+
+Install globally to expose the `mark-down` binary:
+
+```bash
+npm install -g @mzebley/mark-down-cli
+```
+
+or run it on demand via `npx` without a global install:
+
+```bash
+npx @mzebley/mark-down-cli build content/snippets
+```
+
+## Usage
+
+```bash
+mark-down build <sourceDir> [options]
+```
+
+The CLI walks the directory tree, gathers front matter, and writes `snippets-index.json` alongside your Markdown files by default.
+
+## Commands
+
+### `mark-down build <sourceDir>`
+
+- Discovers `*.md` files under `sourceDir` (defaults to `content/snippets`).
+- Parses YAML with the `yaml` package, normalizes slugs, flags duplicates, and removes drafts (`draft: true`).
+- Writes `snippets-index.json` to the source directory by default (use `--outDir` to override).
+- Supports relative or absolute paths.
+
+### `mark-down watch <sourceDir>`
+
+- Uses `chokidar` to watch for file changes.
+- Debounces rebuilds to avoid thrashing during writes.
+- Logs progress with the familiar `[mark↓]` prefix.
+- Accepts the same options as `build`.
+
+## Configuration options
+
+The CLI stays intentionally small so it can be composed inside any toolchain. Currently supported flags:
+
+- `-o, --output <path>` – write the manifest to a custom file instead of `<sourceDir>/snippets-index.json`.
+
+Add flags directly after the command (`mark-down build content/snippets -o public/snippets-index.json`). Package scripts can capture these options as well.
+
+## Watching for changes
+
+Use watch mode when authoring content:
+
+```bash
+mark-down watch content/snippets --outDir public/snippets
+```
+
+The CLI will rebuild whenever files are created, changed, or removed.
+
+## Exit codes
+
+- `0` – success.
+- `1` – generic failure (I/O issues, parse errors, etc.).
+- `2` – duplicate slugs detected. Fix conflicts, then rerun.
+
+CI pipelines can fail fast by treating non-zero exit codes as errors.
+
+## Troubleshooting
+
+- **No snippets found** – confirm the path is correct and that files end with `.md`. The CLI always uses the recursive `**/*.md` pattern.
+- **Duplicate slugs** – check the log output; offending files are listed. Override slugs in front matter or reorganize filenames.
+- **ESM/TypeScript projects** – invoke via `npx` or add an npm script: `"snippets:build": "mark-down build content/snippets"`.
+
+## Roadmap
+
+- **Additional flags** – support opt-in draft inclusion, custom glob patterns, and alternative output formats.
+- **Manifest plugins** – allow teams to run transforms (MDX, remark, syntax highlighting) before JSON is written.
+- **Watch dashboard** – provide a TUI/HTML preview server so content teams can inspect snippets while writing.
+- **Parallel builds** – shard large repositories across worker pools for faster CI times.
+
+Open an issue if one of these would unlock your workflow.
+
+## Related packages
+
+- [Core runtime](../core/README.md) – consume generated manifests at runtime.
+- [Angular adapter](../angular/README.md) – use snippets inside Angular apps.
+- [React adapter](../react/README.md) – integrate with React, Next.js, or Remix.
+- [Example app](../../examples/basic/README.md) – see the CLI in action.

package/dist/index.cjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_commander = require("commander");
+
+// src/manifest.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_fast_glob = __toESM(require("fast-glob"), 1);
+var import_gray_matter = __toESM(require("gray-matter"), 1);
+var import_yaml = __toESM(require("yaml"), 1);
+var import_mark_down = require("@mzebley/mark-down");
+
+// src/errors.ts
+var DuplicateSlugError = class extends Error {
+  constructor(duplicates) {
+    super(`Duplicate slugs detected: ${duplicates.join(", ")}`);
+    this.name = "DuplicateSlugError";
+    this.duplicates = duplicates;
+  }
+};
+
+// src/manifest.ts
+var MATTER_OPTIONS = {
+  engines: {
+    yaml: (source) => import_yaml.default.parse(source) ?? {}
+  }
+};
+async function buildManifestFile(options) {
+  const manifest = await buildManifest(options.sourceDir);
+  const target = options.outputPath ?? import_node_path.default.join(options.sourceDir, "snippets-index.json");
+  await import_promises.default.writeFile(target, JSON.stringify(manifest, null, 2));
+  return { manifest, outputPath: target };
+}
+async function buildManifest(sourceDir) {
+  const cwd = import_node_path.default.resolve(sourceDir);
+  const files = await (0, import_fast_glob.default)(["**/*.md"], { cwd, absolute: true });
+  const manifest = [];
+  for (const absolutePath of files) {
+    const relativePath = import_node_path.default.relative(cwd, absolutePath);
+    const normalizedPath = toPosix(relativePath);
+    const content = await import_promises.default.readFile(absolutePath, "utf8");
+    const parsed = (0, import_gray_matter.default)(content, MATTER_OPTIONS);
+    const snippet = createSnippet(normalizedPath, parsed.data ?? {});
+    if (snippet.draft) {
+      continue;
+    }
+    manifest.push(snippet);
+  }
+  ensureUniqueSlugs(manifest);
+  manifest.sort((a, b) => {
+    const orderA = typeof a.order === "number" ? a.order : Number.POSITIVE_INFINITY;
+    const orderB = typeof b.order === "number" ? b.order : Number.POSITIVE_INFINITY;
+    if (orderA !== orderB) {
+      return orderA - orderB;
+    }
+    const titleA = a.title?.toLowerCase() ?? "";
+    const titleB = b.title?.toLowerCase() ?? "";
+    return titleA.localeCompare(titleB);
+  });
+  return manifest;
+}
+function createSnippet(relativePath, frontMatter) {
+  const group = deriveGroup(relativePath);
+  const slugSource = typeof frontMatter.slug === "string" && frontMatter.slug.trim().length ? frontMatter.slug : relativePath.replace(/\.md$/i, "");
+  const slug = (0, import_mark_down.normalizeSlug)(slugSource);
+  const { title, order, type, tags, draft } = normalizeKnownFields(frontMatter);
+  const extra = collectExtra(frontMatter);
+  return {
+    slug,
+    title,
+    order,
+    type,
+    tags,
+    draft,
+    path: relativePath,
+    group,
+    extra
+  };
+}
+function normalizeKnownFields(data) {
+  return {
+    title: typeof data.title === "string" ? data.title : void 0,
+    order: typeof data.order === "number" ? data.order : data.order === null ? null : void 0,
+    type: typeof data.type === "string" ? data.type : void 0,
+    tags: normalizeTags(data.tags),
+    draft: data.draft === true ? true : void 0
+  };
+}
+function collectExtra(data) {
+  const extra = {};
+  const reserved = /* @__PURE__ */ new Set(["slug", "title", "order", "type", "tags", "draft"]);
+  for (const [key, value] of Object.entries(data)) {
+    if (reserved.has(key)) {
+      continue;
+    }
+    extra[key] = value;
+  }
+  return Object.keys(extra).length ? extra : void 0;
+}
+function normalizeTags(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry));
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  }
+  return void 0;
+}
+function deriveGroup(relativePath) {
+  const dirname = toPosix(import_node_path.default.dirname(relativePath));
+  if (dirname === "." || !dirname.length) {
+    return "root";
+  }
+  return dirname;
+}
+function toPosix(value) {
+  return value.split(import_node_path.default.sep).join("/");
+}
+function ensureUniqueSlugs(manifest) {
+  const seen = /* @__PURE__ */ new Map();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const snippet of manifest) {
+    if (seen.has(snippet.slug)) {
+      duplicates.add(snippet.slug);
+    } else {
+      seen.set(snippet.slug, snippet.path);
+    }
+  }
+  if (duplicates.size) {
+    throw new DuplicateSlugError([...duplicates.values()]);
+  }
+}
+
+// src/watch.ts
+var import_node_path2 = __toESM(require("path"), 1);
+var import_chokidar = __toESM(require("chokidar"), 1);
+
+// src/logger.ts
+var brand = "mark\u2193";
+function logEvent(level, event, fields = {}) {
+  const entry = {
+    brand,
+    level,
+    event,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...fields
+  };
+  const output = `${JSON.stringify(entry)}
+`;
+  const stream = level === "error" ? process.stderr : process.stdout;
+  stream.write(output);
+}
+
+// src/watch.ts
+async function watch(sourceDir, outputPath) {
+  const cwd = import_node_path2.default.resolve(sourceDir);
+  logEvent("info", "watch.start", {
+    directory: cwd,
+    outputPath: outputPath ?? import_node_path2.default.join(cwd, "snippets-index.json")
+  });
+  await rebuild(cwd, outputPath);
+  const watcher = import_chokidar.default.watch(["**/*.md"], {
+    cwd,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 200,
+      pollInterval: 50
+    }
+  });
+  const schedule = debounce(async () => {
+    await rebuild(cwd, outputPath);
+  }, 150);
+  watcher.on("all", (event, filePath) => {
+    logEvent("info", "watch.change", { event, file: filePath });
+    schedule();
+  });
+}
+async function rebuild(sourceDir, outputPath) {
+  try {
+    const result = await buildManifestFile({ sourceDir, outputPath });
+    logEvent("info", "manifest.updated", {
+      outputPath: result.outputPath,
+      snippetCount: result.manifest.length
+    });
+    return result;
+  } catch (error) {
+    const err = error;
+    logEvent("error", "manifest.update_failed", {
+      message: err.message,
+      stack: err.stack
+    });
+  }
+}
+function debounce(fn, delay) {
+  let timer = null;
+  return (...args) => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      void fn(...args);
+    }, delay);
+  };
+}
+
+// src/index.ts
+var program = new import_commander.Command();
+program.name("mark-down").description(`${brand} CLI for building snippet manifests`).version("0.1.0");
+program.command("build").argument("[sourceDir]", "directory containing snippets", "content/snippets").option("-o, --output <path>", "where to write snippets-index.json").action(async (sourceDir, options) => {
+  try {
+    const result = await buildManifestFile({ sourceDir, outputPath: options.output });
+    logEvent("info", "manifest.written", {
+      outputPath: result.outputPath,
+      snippetCount: result.manifest.length
+    });
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("watch").argument("[sourceDir]", "directory containing snippets", "content/snippets").option("-o, --output <path>", "where to write snippets-index.json").action(async (sourceDir, options) => {
+  try {
+    await watch(sourceDir, options.output);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.parseAsync(process.argv).catch(handleError);
+function handleError(error) {
+  const err = error;
+  if (err instanceof DuplicateSlugError) {
+    logEvent("error", "manifest.duplicate_slug", {
+      message: err.message,
+      slugs: err.duplicates
+    });
+    process.exit(2);
+  }
+  logEvent("error", "cli.error", {
+    message: err.message,
+    stack: err.stack
+  });
+  process.exit(1);
+}

package/dist/index.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/manifest.ts
+import fs from "fs/promises";
+import path from "path";
+import fg from "fast-glob";
+import matter from "gray-matter";
+import YAML from "yaml";
+import { normalizeSlug } from "@mzebley/mark-down";
+
+// src/errors.ts
+var DuplicateSlugError = class extends Error {
+  constructor(duplicates) {
+    super(`Duplicate slugs detected: ${duplicates.join(", ")}`);
+    this.name = "DuplicateSlugError";
+    this.duplicates = duplicates;
+  }
+};
+
+// src/manifest.ts
+var MATTER_OPTIONS = {
+  engines: {
+    yaml: (source) => YAML.parse(source) ?? {}
+  }
+};
+async function buildManifestFile(options) {
+  const manifest = await buildManifest(options.sourceDir);
+  const target = options.outputPath ?? path.join(options.sourceDir, "snippets-index.json");
+  await fs.writeFile(target, JSON.stringify(manifest, null, 2));
+  return { manifest, outputPath: target };
+}
+async function buildManifest(sourceDir) {
+  const cwd = path.resolve(sourceDir);
+  const files = await fg(["**/*.md"], { cwd, absolute: true });
+  const manifest = [];
+  for (const absolutePath of files) {
+    const relativePath = path.relative(cwd, absolutePath);
+    const normalizedPath = toPosix(relativePath);
+    const content = await fs.readFile(absolutePath, "utf8");
+    const parsed = matter(content, MATTER_OPTIONS);
+    const snippet = createSnippet(normalizedPath, parsed.data ?? {});
+    if (snippet.draft) {
+      continue;
+    }
+    manifest.push(snippet);
+  }
+  ensureUniqueSlugs(manifest);
+  manifest.sort((a, b) => {
+    const orderA = typeof a.order === "number" ? a.order : Number.POSITIVE_INFINITY;
+    const orderB = typeof b.order === "number" ? b.order : Number.POSITIVE_INFINITY;
+    if (orderA !== orderB) {
+      return orderA - orderB;
+    }
+    const titleA = a.title?.toLowerCase() ?? "";
+    const titleB = b.title?.toLowerCase() ?? "";
+    return titleA.localeCompare(titleB);
+  });
+  return manifest;
+}
+function createSnippet(relativePath, frontMatter) {
+  const group = deriveGroup(relativePath);
+  const slugSource = typeof frontMatter.slug === "string" && frontMatter.slug.trim().length ? frontMatter.slug : relativePath.replace(/\.md$/i, "");
+  const slug = normalizeSlug(slugSource);
+  const { title, order, type, tags, draft } = normalizeKnownFields(frontMatter);
+  const extra = collectExtra(frontMatter);
+  return {
+    slug,
+    title,
+    order,
+    type,
+    tags,
+    draft,
+    path: relativePath,
+    group,
+    extra
+  };
+}
+function normalizeKnownFields(data) {
+  return {
+    title: typeof data.title === "string" ? data.title : void 0,
+    order: typeof data.order === "number" ? data.order : data.order === null ? null : void 0,
+    type: typeof data.type === "string" ? data.type : void 0,
+    tags: normalizeTags(data.tags),
+    draft: data.draft === true ? true : void 0
+  };
+}
+function collectExtra(data) {
+  const extra = {};
+  const reserved = /* @__PURE__ */ new Set(["slug", "title", "order", "type", "tags", "draft"]);
+  for (const [key, value] of Object.entries(data)) {
+    if (reserved.has(key)) {
+      continue;
+    }
+    extra[key] = value;
+  }
+  return Object.keys(extra).length ? extra : void 0;
+}
+function normalizeTags(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry));
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  }
+  return void 0;
+}
+function deriveGroup(relativePath) {
+  const dirname = toPosix(path.dirname(relativePath));
+  if (dirname === "." || !dirname.length) {
+    return "root";
+  }
+  return dirname;
+}
+function toPosix(value) {
+  return value.split(path.sep).join("/");
+}
+function ensureUniqueSlugs(manifest) {
+  const seen = /* @__PURE__ */ new Map();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const snippet of manifest) {
+    if (seen.has(snippet.slug)) {
+      duplicates.add(snippet.slug);
+    } else {
+      seen.set(snippet.slug, snippet.path);
+    }
+  }
+  if (duplicates.size) {
+    throw new DuplicateSlugError([...duplicates.values()]);
+  }
+}
+
+// src/watch.ts
+import path2 from "path";
+import chokidar from "chokidar";
+
+// src/logger.ts
+var brand = "mark\u2193";
+function logEvent(level, event, fields = {}) {
+  const entry = {
+    brand,
+    level,
+    event,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    ...fields
+  };
+  const output = `${JSON.stringify(entry)}
+`;
+  const stream = level === "error" ? process.stderr : process.stdout;
+  stream.write(output);
+}
+
+// src/watch.ts
+async function watch(sourceDir, outputPath) {
+  const cwd = path2.resolve(sourceDir);
+  logEvent("info", "watch.start", {
+    directory: cwd,
+    outputPath: outputPath ?? path2.join(cwd, "snippets-index.json")
+  });
+  await rebuild(cwd, outputPath);
+  const watcher = chokidar.watch(["**/*.md"], {
+    cwd,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 200,
+      pollInterval: 50
+    }
+  });
+  const schedule = debounce(async () => {
+    await rebuild(cwd, outputPath);
+  }, 150);
+  watcher.on("all", (event, filePath) => {
+    logEvent("info", "watch.change", { event, file: filePath });
+    schedule();
+  });
+}
+async function rebuild(sourceDir, outputPath) {
+  try {
+    const result = await buildManifestFile({ sourceDir, outputPath });
+    logEvent("info", "manifest.updated", {
+      outputPath: result.outputPath,
+      snippetCount: result.manifest.length
+    });
+    return result;
+  } catch (error) {
+    const err = error;
+    logEvent("error", "manifest.update_failed", {
+      message: err.message,
+      stack: err.stack
+    });
+  }
+}
+function debounce(fn, delay) {
+  let timer = null;
+  return (...args) => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      void fn(...args);
+    }, delay);
+  };
+}
+
+// src/index.ts
+var program = new Command();
+program.name("mark-down").description(`${brand} CLI for building snippet manifests`).version("0.1.0");
+program.command("build").argument("[sourceDir]", "directory containing snippets", "content/snippets").option("-o, --output <path>", "where to write snippets-index.json").action(async (sourceDir, options) => {
+  try {
+    const result = await buildManifestFile({ sourceDir, outputPath: options.output });
+    logEvent("info", "manifest.written", {
+      outputPath: result.outputPath,
+      snippetCount: result.manifest.length
+    });
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("watch").argument("[sourceDir]", "directory containing snippets", "content/snippets").option("-o, --output <path>", "where to write snippets-index.json").action(async (sourceDir, options) => {
+  try {
+    await watch(sourceDir, options.output);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.parseAsync(process.argv).catch(handleError);
+function handleError(error) {
+  const err = error;
+  if (err instanceof DuplicateSlugError) {
+    logEvent("error", "manifest.duplicate_slug", {
+      message: err.message,
+      slugs: err.duplicates
+    });
+    process.exit(2);
+  }
+  logEvent("error", "cli.error", {
+    message: err.message,
+    stack: err.stack
+  });
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mzebley/mark-down-cli",
+  "version": "1.0.0",
+  "description": "mark↓ CLI for building snippet manifests",
+  "type": "module",
+  "bin": {
+    "mark-down": "dist/index.cjs"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --watch"
+  },
+  "dependencies": {
+    "@mzebley/mark-down": "file:../core",
+    "chokidar": "^3.6.0",
+    "commander": "^11.1.0",
+    "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.4.1"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,9 @@
+export class DuplicateSlugError extends Error {
+  readonly duplicates: string[];
+
+  constructor(duplicates: string[]) {
+    super(`Duplicate slugs detected: ${duplicates.join(", ")}`);
+    this.name = "DuplicateSlugError";
+    this.duplicates = duplicates;
+  }
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { buildManifestFile } from "./manifest.js";
+import { watch as watchSnippets } from "./watch.js";
+import { brand, logEvent } from "./logger.js";
+import { DuplicateSlugError } from "./errors.js";
+
+const program = new Command();
+program
+  .name("mark-down")
+  .description(`${brand} CLI for building snippet manifests`)
+  .version("0.1.0");
+
+program
+  .command("build")
+  .argument("[sourceDir]", "directory containing snippets", "content/snippets")
+  .option("-o, --output <path>", "where to write snippets-index.json")
+  .action(async (sourceDir: string, options: { output?: string }) => {
+    try {
+      const result = await buildManifestFile({ sourceDir, outputPath: options.output });
+      logEvent("info", "manifest.written", {
+        outputPath: result.outputPath,
+        snippetCount: result.manifest.length
+      });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+
+program
+  .command("watch")
+  .argument("[sourceDir]", "directory containing snippets", "content/snippets")
+  .option("-o, --output <path>", "where to write snippets-index.json")
+  .action(async (sourceDir: string, options: { output?: string }) => {
+    try {
+      await watchSnippets(sourceDir, options.output);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+
+program.parseAsync(process.argv).catch(handleError);
+
+function handleError(error: unknown) {
+  const err = error as Error;
+  if (err instanceof DuplicateSlugError) {
+    logEvent("error", "manifest.duplicate_slug", {
+      message: err.message,
+      slugs: err.duplicates
+    });
+    process.exit(2);
+  }
+  logEvent("error", "cli.error", {
+    message: err.message,
+    stack: err.stack
+  });
+  process.exit(1);
+}

package/src/logger.ts

@@ -0,0 +1,37 @@
+export const brand = "mark↓";
+
+export type LogLevel = "info" | "warn" | "error";
+
+export interface LogFields {
+  message?: string;
+  [key: string]: unknown;
+}
+
+export function logEvent(level: LogLevel, event: string, fields: LogFields = {}) {
+  const entry = {
+    brand,
+    level,
+    event,
+    timestamp: new Date().toISOString(),
+    ...fields
+  };
+  const output = `${JSON.stringify(entry)}\n`;
+  const stream = level === "error" ? process.stderr : process.stdout;
+  stream.write(output);
+}
+
+export function log(message: string, fields?: LogFields) {
+  if (fields) {
+    logEvent("info", message, fields);
+    return;
+  }
+  logEvent("info", "message", { message });
+}
+
+export function logError(message: string, fields?: LogFields) {
+  if (fields) {
+    logEvent("error", message, fields);
+    return;
+  }
+  logEvent("error", "message", { message });
+}

package/src/manifest.ts

@@ -0,0 +1,155 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import matter from "gray-matter";
+import YAML from "yaml";
+import { normalizeSlug, type SnippetMeta } from "@mzebley/mark-down";
+import { DuplicateSlugError } from "./errors.js";
+
+const MATTER_OPTIONS = {
+  engines: {
+    yaml: (source: string) => YAML.parse(source) ?? {}
+  }
+};
+
+export interface BuildOptions {
+  sourceDir: string;
+  outputPath?: string;
+}
+
+export interface BuildResult {
+  manifest: SnippetMeta[];
+  outputPath: string;
+}
+
+export async function buildManifestFile(options: BuildOptions): Promise<BuildResult> {
+  const manifest = await buildManifest(options.sourceDir);
+  const target = options.outputPath ?? path.join(options.sourceDir, "snippets-index.json");
+  await fs.writeFile(target, JSON.stringify(manifest, null, 2));
+  return { manifest, outputPath: target };
+}
+
+export async function buildManifest(sourceDir: string): Promise<SnippetMeta[]> {
+  const cwd = path.resolve(sourceDir);
+  const files = await fg(["**/*.md"], { cwd, absolute: true });
+  const manifest: SnippetMeta[] = [];
+
+  for (const absolutePath of files) {
+    const relativePath = path.relative(cwd, absolutePath);
+    const normalizedPath = toPosix(relativePath);
+    const content = await fs.readFile(absolutePath, "utf8");
+    const parsed = matter(content, MATTER_OPTIONS);
+    const snippet = createSnippet(normalizedPath, parsed.data ?? {});
+    if (snippet.draft) {
+      continue;
+    }
+    manifest.push(snippet);
+  }
+
+  ensureUniqueSlugs(manifest);
+
+  manifest.sort((a, b) => {
+    const orderA = typeof a.order === "number" ? a.order : Number.POSITIVE_INFINITY;
+    const orderB = typeof b.order === "number" ? b.order : Number.POSITIVE_INFINITY;
+    if (orderA !== orderB) {
+      return orderA - orderB;
+    }
+    const titleA = a.title?.toLowerCase() ?? "";
+    const titleB = b.title?.toLowerCase() ?? "";
+    return titleA.localeCompare(titleB);
+  });
+
+  return manifest;
+}
+
+export function createSnippet(relativePath: string, frontMatter: Record<string, unknown>): SnippetMeta {
+  const group = deriveGroup(relativePath);
+  const slugSource = typeof frontMatter.slug === "string" && frontMatter.slug.trim().length
+    ? frontMatter.slug
+    : relativePath.replace(/\.md$/i, "");
+  const slug = normalizeSlug(slugSource);
+
+  const { title, order, type, tags, draft } = normalizeKnownFields(frontMatter);
+  const extra = collectExtra(frontMatter);
+
+  return {
+    slug,
+    title,
+    order,
+    type,
+    tags,
+    draft,
+    path: relativePath,
+    group,
+    extra
+  };
+}
+
+function normalizeKnownFields(data: Record<string, unknown>) {
+  return {
+    title: typeof data.title === "string" ? data.title : undefined,
+    order: typeof data.order === "number"
+      ? data.order
+      : data.order === null
+        ? null
+        : undefined,
+    type: typeof data.type === "string" ? data.type : undefined,
+    tags: normalizeTags(data.tags),
+    draft: data.draft === true ? true : undefined
+  };
+}
+
+function collectExtra(data: Record<string, unknown>): Record<string, unknown> | undefined {
+  const extra: Record<string, unknown> = {};
+  const reserved = new Set(["slug", "title", "order", "type", "tags", "draft"]);
+  for (const [key, value] of Object.entries(data)) {
+    if (reserved.has(key)) {
+      continue;
+    }
+    extra[key] = value;
+  }
+  return Object.keys(extra).length ? extra : undefined;
+}
+
+function normalizeTags(value: unknown): string[] | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry));
+  }
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return undefined;
+}
+
+function deriveGroup(relativePath: string): string {
+  const dirname = toPosix(path.dirname(relativePath));
+  if (dirname === "." || !dirname.length) {
+    return "root";
+  }
+  return dirname;
+}
+
+function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+function ensureUniqueSlugs(manifest: SnippetMeta[]) {
+  const seen = new Map<string, string>();
+  const duplicates = new Set<string>();
+  for (const snippet of manifest) {
+    if (seen.has(snippet.slug)) {
+      duplicates.add(snippet.slug);
+    } else {
+      seen.set(snippet.slug, snippet.path);
+    }
+  }
+  if (duplicates.size) {
+    throw new DuplicateSlugError([...duplicates.values()]);
+  }
+}

package/src/watch.ts

@@ -0,0 +1,64 @@
+import path from "node:path";
+import chokidar from "chokidar";
+import { buildManifestFile, type BuildResult } from "./manifest.js";
+import { logEvent } from "./logger.js";
+
+export async function watch(sourceDir: string, outputPath?: string) {
+  const cwd = path.resolve(sourceDir);
+  logEvent("info", "watch.start", {
+    directory: cwd,
+    outputPath: outputPath ?? path.join(cwd, "snippets-index.json")
+  });
+  await rebuild(cwd, outputPath);
+
+  const watcher = chokidar.watch(["**/*.md"], {
+    cwd,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 200,
+      pollInterval: 50
+    }
+  });
+
+  const schedule = debounce(async () => {
+    await rebuild(cwd, outputPath);
+  }, 150);
+
+  watcher.on("all", (event, filePath) => {
+    logEvent("info", "watch.change", { event, file: filePath });
+    schedule();
+  });
+}
+
+async function rebuild(sourceDir: string, outputPath?: string): Promise<BuildResult | void> {
+  try {
+    const result = await buildManifestFile({ sourceDir, outputPath });
+    logEvent("info", "manifest.updated", {
+      outputPath: result.outputPath,
+      snippetCount: result.manifest.length
+    });
+    return result;
+  } catch (error) {
+    const err = error as Error;
+    logEvent("error", "manifest.update_failed", {
+      message: err.message,
+      stack: err.stack
+    });
+  }
+}
+
+function debounce<T extends (...args: unknown[]) => Promise<unknown> | void>(
+  fn: T,
+  delay: number
+) {
+  let timer: NodeJS.Timeout | null = null;
+  return (...args: Parameters<T>) => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      void fn(...args);
+    }, delay);
+  };
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "ES2020",
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"]
+}