@mzebley/mark-down-cli 1.2.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mzebley/mark-down-cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "mark↓ CLI for building snippet manifests",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "files": ["dist"],
   "publishConfig": {
     "access": "public"
   },
@@ -17,7 +18,7 @@
     "dev": "tsup --config tsup.config.ts --watch"
   },
   "dependencies": {
-    "@mzebley/mark-down": "^1.2.1",
+    "@mzebley/mark-down": "^1.2.2",
     "cheerio": "^1.0.0",
     "chokidar": "^3.6.0",
     "commander": "^11.1.0",

package/src/compile-page.ts

@@ -1,116 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { load as loadHtml } from "cheerio";
-import { parseFrontMatter, renderMarkdown, type SnippetMeta } from "@mzebley/mark-down";
-import { logEvent } from "./logger.js";
-
-export interface CompilePageOptions {
-  manifest?: string;
-  outDir?: string;
-  inPlace?: boolean;
-}
-
-const DEFAULT_OUT_DIR = "dist";
-
-export async function compilePage(inputHtml: string, options: CompilePageOptions = {}): Promise<string> {
-  const sourcePath = path.resolve(inputHtml);
-  await assertExists(sourcePath, `Input HTML file not found at '${inputHtml}'.`);
-
-  const manifestPath = await resolveManifestPath(sourcePath, options.manifest);
-  const manifestDir = path.dirname(manifestPath);
-  const manifest = await loadManifest(manifestPath);
-
-  const rawHtml = await fs.readFile(sourcePath, "utf8");
-  const doctypeMatch = rawHtml.match(/^(<!doctype[^>]*>\s*)/i);
-  const doctype = doctypeMatch?.[1] ?? "";
-  const dom = loadHtml(rawHtml, { decodeEntities: false });
-
-  const targets = dom("[data-snippet]").toArray();
-  for (const node of targets) {
-    const element = dom(node);
-    const slug = element.attr("data-snippet");
-    if (!slug) {
-      continue;
-    }
-    const entry = manifest.find((item) => item.slug === slug);
-    if (!entry) {
-      console.warn(`mark↓: no snippet found for "${slug}"`);
-      continue;
-    }
-
-    const snippetPath = path.resolve(manifestDir, entry.path);
-    let raw: string;
-    try {
-      raw = await fs.readFile(snippetPath, "utf8");
-    } catch (error) {
-      console.warn(`mark↓: failed to read snippet at '${entry.path}'`, error);
-      continue;
-    }
-
-    let body = raw;
-    let frontMatterSlug: string | undefined;
-    try {
-      const frontMatter = parseFrontMatter(raw);
-      body = frontMatter.content;
-      frontMatterSlug = frontMatter.slug;
-    } catch (error) {
-      console.warn(`mark↓: failed to parse front matter for '${entry.path}'`, error);
-    }
-
-    const html = renderMarkdown(body);
-    element.html(html);
-
-    if (!element.attr("id")) {
-      element.attr("id", frontMatterSlug ?? `snippet-${slug}`);
-    }
-  }
-
-  const outputDir = options.inPlace ? path.dirname(sourcePath) : path.resolve(options.outDir ?? DEFAULT_OUT_DIR);
-  if (!options.inPlace) {
-    await fs.mkdir(outputDir, { recursive: true });
-  }
-  const outputPath = options.inPlace
-    ? sourcePath
-    : path.join(outputDir, path.basename(sourcePath));
-
-  const outputHtml = `${doctype}${dom.html() ?? ""}`;
-  await fs.writeFile(outputPath, outputHtml);
-
-  logEvent("info", "compile_page.written", { outputPath });
-  return outputPath;
-}
-
-async function resolveManifestPath(inputHtml: string, manifestFlag?: string): Promise<string> {
-  const manifestPath = manifestFlag
-    ? path.resolve(manifestFlag)
-    : path.join(path.dirname(path.resolve(inputHtml)), "snippets-index.json");
-  await assertExists(manifestPath, `Manifest file not found at '${manifestPath}'.`);
-  return manifestPath;
-}
-
-async function loadManifest(manifestPath: string): Promise<SnippetMeta[]> {
-  let raw: string;
-  try {
-    raw = await fs.readFile(manifestPath, "utf8");
-  } catch (error) {
-    throw new Error(`Failed to read manifest at '${manifestPath}': ${String(error)}`);
-  }
-
-  try {
-    const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed)) {
-      throw new Error("Manifest must be a JSON array.");
-    }
-    return parsed as SnippetMeta[];
-  } catch (error) {
-    throw new Error(`Failed to parse manifest at '${manifestPath}': ${String(error)}`);
-  }
-}
-
-async function assertExists(target: string, message: string) {
-  try {
-    await fs.access(target);
-  } catch {
-    throw new Error(message);
-  }
-}

package/src/errors.ts

@@ -1,9 +0,0 @@
-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

@@ -1,77 +0,0 @@
-#!/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";
-import { compilePage } from "./compile-page.js";
-
-const program = new Command();
-program
-  .name("mark-down")
-  .description(`${brand} CLI for building snippet manifests`)
-  .version("1.2.1");
-
-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
-  .command("compile-page")
-  .argument("<inputHtml>", "HTML file containing data-snippet placeholders")
-  .option("--manifest <path>", "path to snippets-index.json")
-  .option("--outDir <path>", "output directory for compiled HTML", "dist")
-  .option("--inPlace", "overwrite the input HTML file instead of writing to outDir")
-  .action(async (inputHtml: string, options: { manifest?: string; outDir?: string; inPlace?: boolean }) => {
-    try {
-      await compilePage(inputHtml, {
-        manifest: options.manifest,
-        outDir: options.outDir,
-        inPlace: options.inPlace
-      });
-    } 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

@@ -1,37 +0,0 @@
-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

@@ -1,155 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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

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

package/tsup.config.ts

@@ -1,15 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-  entry: ["src/index.ts"],
-  format: ["esm", "cjs"],
-  dts: true,
-  sourcemap: true,
-  splitting: false,
-  clean: true,
-  outExtension({ format }) {
-    return {
-      js: format === "esm" ? ".mjs" : ".cjs"
-    };
-  }
-});