@n6k.io/build 0.0.1

package/README.md

@@ -0,0 +1,71 @@
+# @n6k.io/build
+
+Static build pipeline for [n6k](https://github.com/n6k-io) apps. Preprocesses
+`.mdx` pages (and passes `.ts`/`.tsx`/`.js`/`.jsx` entries through), bundles them
+with esbuild, and optionally renders static HTML.
+
+## Install
+
+```bash
+bun add @n6k.io/build
+```
+
+The package ships **raw TypeScript source** (no build step) — your bundler
+compiles it. `esbuild`, `react`, and `react-dom` are peer dependencies resolved
+from the consuming app's `node_modules`.
+
+## Usage
+
+As a CLI (the `n6k-build` bin):
+
+```bash
+n6k-build [appDir] [--debug]
+```
+
+`appDir` defaults to the current working directory. Configuration is read from
+`<appDir>/build/n6k.build.json`.
+
+As a library:
+
+```ts
+import { build } from "@n6k.io/build";
+
+await build(process.cwd());
+```
+
+## MDX components
+
+The MDX provider (`useMDXComponents`) is resolved, in order:
+
+1. `mdxComponents` in `n6k.build.json` — a package specifier or path, e.g.
+   `"@n6k.io/ui/lib/mdx-components"`.
+2. `<appDir>/mdx-components.tsx`, if present.
+3. Otherwise none — MDX renders with its built-in default components.
+
+This package has no dependency on `@n6k.io/ui`; apps opt into a component set
+via the `mdxComponents` config field.
+
+## Peer dependencies
+
+`esbuild`, `react`, and `react-dom` are resolved from the consuming app's
+`node_modules`. Optional integrations (`@n6k.io/db`, `@tanstack/react-query`,
+`@storybook/react`, `storybook`, `vite`) are declared as optional peers and only
+needed when you use the matching entry point.
+
+## Development
+
+```bash
+bun install
+bun test         # run the test suite
+bun run typecheck
+bun run fmt      # format with prettier
+bun run ci       # fmt:check + typecheck + test (the CI gate)
+```
+
+CI runs `bun ci` on every push and pull request to `main`. Pushing a `v*` tag
+runs the same gate and then publishes the package to npm
+(`.github/workflows/publish.yml`).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@n6k.io/build",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Static build pipeline (.mdx + ts/tsx/js/jsx → esbuild bundle → HTML) for n6k apps",
+  "homepage": "https://github.com/n6k-io/build#readme",
+  "bugs": {
+    "url": "https://github.com/n6k-io/build/issues"
+  },
+  "repository": "https://github.com/n6k-io/build",
+  "license": "MIT",
+  "author": "",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "bin": {
+    "n6k-build": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./imports": "./src/pipeline/imports.ts",
+    "./workers": "./src/workers/manifest.ts",
+    "./wasm": "./src/wasm/extensions.ts",
+    "./vite": "./src/vite/index.ts",
+    "./storybook": "./src/storybook/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "fmt": "prettier --write --log-level=warn .",
+    "check": "bun run fmt && bun run lint --fix && bun run typecheck",
+    "fmt:check": "prettier --check .",
+    "ci": "bun run fmt:check && bun run lint && bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "handlebars": "^4.7.8",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "remark-frontmatter": "^5.0.0",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@n6k.io/db": "*",
+    "@storybook/react": "^10.4.4",
+    "@tanstack/react-query": "^5.101.0",
+    "esbuild": "^0.27.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "storybook": "^10.4.4",
+    "typescript": "^5",
+    "vite": "^8"
+  },
+  "peerDependenciesMeta": {
+    "@n6k.io/db": {
+      "optional": true
+    },
+    "@storybook/react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "storybook": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@n6k.io/db": "link:@n6k.io/db",
+    "@storybook/react": "^10.4.4",
+    "@tanstack/react-query": "^5.101.0",
+    "@types/bun": "latest",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "esbuild": "^0.27.3",
+    "eslint": "^10.4.1",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-storybook": "^10.4.4",
+    "eslint-plugin-unicorn": "^65.0.1",
+    "prettier": "^3.8.1",
+    "storybook": "^10.4.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.61.0",
+    "vite": "^8"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { initLogger, flushLogger } from "./util/logger";
+import { build, BuildError } from "./pipeline/build";
+
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    debug: { type: "boolean", default: false },
+  },
+  allowPositionals: true,
+  strict: true,
+});
+
+initLogger(values.debug!);
+const uiDir = positionals[0] || process.cwd();
+try {
+  await build(path.resolve(uiDir));
+} catch (err) {
+  if (err instanceof BuildError) {
+    console.error(err.message);
+    await flushLogger();
+    process.exit(err.exitCode);
+  }
+  throw err;
+}
+await flushLogger();
+process.exit(0);

package/src/index.ts

@@ -0,0 +1 @@
+export { build } from "./pipeline/build";

package/src/pipeline/build.ts

@@ -0,0 +1,301 @@
+import * as esbuild from "esbuild";
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import Handlebars from "handlebars";
+import { preprocess, type VirtualModule } from "./preprocess";
+import { discoverLayouts } from "./layouts";
+import { logger } from "../util/logger";
+
+// Signals a build failure with a process exit code. The CLI (the bin) catches
+// this and exits with `exitCode`; callers (tests, programmatic use) get a normal
+// throw instead of the process being killed. `404` is a contract: it tells the
+// server unresolved components were written to build/missing.json.
+export class BuildError extends Error {
+  constructor(
+    message: string,
+    readonly exitCode: number,
+  ) {
+    super(message);
+    this.name = "BuildError";
+  }
+}
+
+// esbuild plugin: serve preprocess's generated modules (client entry, SSR
+// wrapper, compiled MDX) from memory under the `n6k:` namespace — no temp dir.
+function virtualModulesPlugin(
+  modules: Map<string, VirtualModule>,
+  resolveDir: string,
+): esbuild.Plugin {
+  return {
+    name: "n6k-virtual",
+    setup(build) {
+      build.onResolve({ filter: /^n6k:/ }, (args) => ({
+        path: args.path,
+        namespace: "n6k-virtual",
+      }));
+      build.onLoad({ filter: /.*/, namespace: "n6k-virtual" }, (args) => {
+        const mod = modules.get(args.path);
+        if (!mod) return;
+        return { contents: mod.contents, loader: mod.loader, resolveDir };
+      });
+    },
+  };
+}
+// The MDX provider (useMDXComponents) is a content/presentation concern owned
+// by the consuming app, not the build tool. Resolve it from config first, then
+// a conventional appDir/mdx-components.tsx, else leave it unset (plain MDX).
+function discoverMdxComponents(
+  appDir: string,
+  config: Config,
+): string | undefined {
+  if (config.mdxComponents) return config.mdxComponents;
+  const userFile = path.join(appDir, "mdx-components.tsx");
+  if (existsSync(userFile)) return userFile;
+  return undefined;
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const workerSchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  url: z.string(),
+});
+
+const wrapperSchema = z.object({
+  component: z.string(),
+  import: z.string(),
+  props: z.record(z.string(), z.any()).optional(),
+});
+
+const configSchema = z.object({
+  srcDir: z.string().optional(),
+  appDir: z.string().optional(),
+  entryPoints: z.record(z.string(), z.string()).optional(),
+  workers: z.array(workerSchema).optional(),
+  wrappers: z.array(wrapperSchema).optional(),
+  assetPrefix: z.string().optional(),
+  scripts: z.array(z.string()).optional(),
+  headTags: z.array(z.string()).optional(),
+  mdxComponents: z.string().optional(),
+});
+
+type Config = z.infer<typeof configSchema>;
+
+function loadConfig(uiDir: string): Config {
+  const configPath = path.join(uiDir, "build", "n6k.build.json");
+  if (!existsSync(configPath)) return {};
+  const raw = JSON.parse(readFileSync(configPath, "utf8"));
+  return configSchema.parse(raw);
+}
+
+function resolveEntryPoints(config: Config): Record<string, string> {
+  if (!config.entryPoints || Object.keys(config.entryPoints).length === 0) {
+    throw new BuildError(
+      "No entryPoints in n6k.build.json. Run the discover/build step first.",
+      1,
+    );
+  }
+  return config.entryPoints;
+}
+
+export async function build(uiDir: string = process.cwd()) {
+  const buildStart = performance.now();
+  uiDir = path.resolve(uiDir);
+
+  const config = loadConfig(uiDir);
+  logger.debug({ uiDir, config }, "config loaded");
+  const sourceEntries = resolveEntryPoints(config);
+  logger.debug(
+    { entryPoints: Object.keys(sourceEntries) },
+    "entry points resolved",
+  );
+
+  const appDir = config.appDir ? path.resolve(config.appDir) : uiDir;
+  const srcDir = config.srcDir
+    ? path.resolve(config.srcDir)
+    : path.join(uiDir, "src");
+  const componentsDir = path.join(srcDir, "components", "ui");
+
+  const wrappers = config.wrappers || [];
+  const layouts = discoverLayouts(sourceEntries, appDir);
+  const mdxComponentsSource = discoverMdxComponents(appDir, config);
+
+  // Pre-process: .mdx → in-memory virtual modules; ts/tsx/js/jsx pass through.
+  logger.debug("preprocessing entries");
+  const {
+    entries: esbuildEntries,
+    serverEntries,
+    missing,
+    meta,
+    modules,
+  } = await preprocess(sourceEntries, componentsDir, {
+    wrappers,
+    layouts,
+    mdxComponents: mdxComponentsSource,
+  });
+  logger.debug(
+    {
+      entries: Object.keys(esbuildEntries).length,
+      serverEntries: Object.keys(serverEntries).length,
+      missing: missing.length,
+    },
+    "preprocess complete",
+  );
+
+  if (missing.length > 0) {
+    const outPath = path.join(uiDir, "build", "missing.json");
+    writeFileSync(outPath, JSON.stringify(missing, null, 2) + "\n");
+    let report = "\nMissing components:\n";
+    for (const { file, components } of missing) {
+      report += `  ${file}: ${components.join(", ")}\n`;
+    }
+    report += `\nWrote ${outPath}\n`;
+    throw new BuildError(report, 404);
+  }
+
+  // esbuild: .tsx → .js → build/public/
+  const buildDir = path.join(uiDir, "build");
+  const publicDir = path.join(buildDir, "public");
+  const nodeModules = path.join(uiDir, "node_modules");
+
+  logger.debug("esbuild: bundling client entries");
+  const esbuildStart = performance.now();
+  await esbuild.build({
+    entryPoints: esbuildEntries,
+    bundle: true,
+    splitting: true,
+    format: "esm",
+    jsx: "automatic",
+    absWorkingDir: uiDir,
+    tsconfig: path.join(uiDir, "tsconfig.json"),
+    outdir: publicDir,
+    nodePaths: [nodeModules],
+    preserveSymlinks: true,
+    plugins: [virtualModulesPlugin(modules, appDir)],
+    alias: {
+      "@": srcDir,
+      react: path.join(nodeModules, "react"),
+      "react-dom": path.join(nodeModules, "react-dom"),
+    },
+  });
+
+  logger.debug(
+    { ms: Math.round(performance.now() - esbuildStart) },
+    "esbuild: client bundle complete",
+  );
+
+  // Bundle workers as IIFE → build/public/
+  if (config.workers && config.workers.length > 0) {
+    const workerEntries: Record<string, string> = {};
+    for (const w of config.workers) {
+      workerEntries[w.name] = w.path;
+    }
+    logger.debug(
+      { workers: Object.keys(workerEntries) },
+      "esbuild: bundling workers",
+    );
+    const workerStart = performance.now();
+    await esbuild.build({
+      entryPoints: workerEntries,
+      bundle: true,
+      format: "iife",
+      absWorkingDir: uiDir,
+      outdir: publicDir,
+    });
+    logger.debug(
+      { ms: Math.round(performance.now() - workerStart) },
+      "esbuild: workers complete",
+    );
+  }
+
+  // Generate HTML documents (opt-in via assetPrefix)
+  if (config.assetPrefix !== undefined) {
+    // Server build: bundle .app.jsx files for renderToString → build/__server__/
+    const serverOutdir = path.join(buildDir, "__server__");
+    const serverEsbuildEntries: Record<string, string> = {};
+    for (const [slug, entryPath] of Object.entries(serverEntries)) {
+      serverEsbuildEntries[slug] = entryPath;
+    }
+
+    if (Object.keys(serverEsbuildEntries).length > 0) {
+      logger.debug(
+        { entries: Object.keys(serverEsbuildEntries) },
+        "esbuild: bundling server entries",
+      );
+      const serverStart = performance.now();
+      await esbuild.build({
+        entryPoints: serverEsbuildEntries,
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        jsx: "automatic",
+        absWorkingDir: uiDir,
+        outdir: serverOutdir,
+        nodePaths: [nodeModules],
+        external: ["react", "react-dom", "react/jsx-runtime"],
+        preserveSymlinks: true,
+        plugins: [virtualModulesPlugin(modules, appDir)],
+        alias: {
+          "@": srcDir,
+        },
+      });
+      logger.debug(
+        { ms: Math.round(performance.now() - serverStart) },
+        "esbuild: server bundle complete",
+      );
+    }
+
+    const { createElement } = await import(path.join(nodeModules, "react"));
+    const { renderToString } = await import(
+      path.join(nodeModules, "react-dom", "server")
+    );
+
+    const pageTemplatePath = path.resolve(
+      __dirname,
+      "..",
+      "templates",
+      "page.hbs",
+    );
+    const pageTemplate = Handlebars.compile(
+      readFileSync(pageTemplatePath, "utf8"),
+    );
+
+    const prefix = config.assetPrefix.replace(/\/+$/, "");
+    const headTagsStr = (config.headTags || []).join("\n  ");
+    const scriptsStr = (config.scripts || []).join("\n  ");
+
+    logger.debug("generating HTML pages");
+    for (const slug of Object.keys(sourceEntries)) {
+      let content = "";
+      const serverJsPath = path.join(serverOutdir, slug + ".js");
+      if (existsSync(serverJsPath)) {
+        const mod = await import(serverJsPath);
+        content = renderToString(createElement(mod.default));
+      }
+
+      const pageMeta = meta.get(slug) || {};
+      const html = pageTemplate({
+        assetPrefix: prefix,
+        slug,
+        headTags: headTagsStr,
+        scripts: scriptsStr,
+        content,
+        ...pageMeta,
+      });
+
+      const htmlPath = path.join(publicDir, slug + ".html");
+      mkdirSync(path.dirname(htmlPath), { recursive: true });
+      writeFileSync(htmlPath, html);
+      logger.debug({ slug, htmlPath }, "wrote HTML");
+    }
+  }
+
+  logger.debug(
+    { ms: Math.round(performance.now() - buildStart) },
+    "build complete",
+  );
+  esbuild.stop();
+}

package/src/pipeline/html.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Handlebars from "handlebars";
+import { parseMdxFrontmatter, preprocess } from "./preprocess";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function loadPageTemplate() {
+  const templatePath = path.resolve(__dirname, "..", "templates", "page.hbs");
+  return Handlebars.compile(readFileSync(templatePath, "utf8"));
+}
+
+describe("parseMdxFrontmatter", () => {
+  test("parses title and description", () => {
+    const raw =
+      "---\ntitle: Dashboard\ndescription: Overview\n---\n# Content\n";
+    const { meta, body } = parseMdxFrontmatter(raw);
+    expect(meta.title).toBe("Dashboard");
+    expect(meta.description).toBe("Overview");
+    expect(body).toBe("# Content\n");
+  });
+
+  test("returns empty meta for no frontmatter", () => {
+    const raw = "# Just content\n";
+    const { meta, body } = parseMdxFrontmatter(raw);
+    expect(meta).toEqual({});
+    expect(body).toBe("# Just content\n");
+  });
+
+  test("handles empty frontmatter block", () => {
+    const raw = "---\n---\n# Content\n";
+    const { meta, body } = parseMdxFrontmatter(raw);
+    expect(meta).toEqual({});
+    expect(body).toBe("# Content\n");
+  });
+
+  test("handles values with colons", () => {
+    const raw = "---\ntitle: My Page: A Subtitle\n---\n# Content\n";
+    const { meta } = parseMdxFrontmatter(raw);
+    expect(meta.title).toBe("My Page: A Subtitle");
+  });
+});
+
+describe("page.hbs template", () => {
+  const template = loadPageTemplate();
+
+  test("renders basic HTML document", () => {
+    const html = template({ assetPrefix: "/_nextpy", slug: "index" });
+    expect(html).toContain("<html lang");
+    expect(html).toContain('<div id="root">');
+    expect(html).toContain('href="/_nextpy/styles.css"');
+    expect(html).toContain('src="/_nextpy/index.js"');
+  });
+
+  test("renders content inside root div", () => {
+    const html = template({
+      assetPrefix: "/_nextpy",
+      slug: "index",
+      content: "<h1>Hello World</h1>",
+    });
+    expect(html).toContain('<div id="root"><h1>Hello World</h1></div>');
+  });
+
+  test("includes title when provided", () => {
+    const html = template({
+      assetPrefix: "/_nextpy",
+      slug: "dashboard",
+      title: "My Dashboard",
+    });
+    expect(html).toContain("<title>My Dashboard</title>");
+  });
+
+  test("excludes title when not provided", () => {
+    const html = template({ assetPrefix: "/_nextpy", slug: "index" });
+    expect(html).not.toContain("<title>");
+  });
+
+  test("includes description meta when provided", () => {
+    const html = template({
+      assetPrefix: "/_nextpy",
+      slug: "dashboard",
+      description: "Overview of metrics",
+    });
+    expect(html).toContain('name="description"');
+    expect(html).toContain('content="Overview of metrics"');
+  });
+
+  test("excludes description meta when not provided", () => {
+    const html = template({ assetPrefix: "/_nextpy", slug: "index" });
+    expect(html).not.toContain('<meta name="description"');
+  });
+
+  test("includes custom scripts", () => {
+    const html = template({
+      assetPrefix: "/_nextpy",
+      slug: "index",
+      scripts: "<script>console.log('dev')</script>",
+    });
+    expect(html).toContain("<script>console.log('dev')</script>");
+  });
+
+  test("includes custom headTags", () => {
+    const html = template({
+      assetPrefix: "/_nextpy",
+      slug: "index",
+      headTags: '<meta name="theme-color" content="#000">',
+    });
+    expect(html).toContain('<meta name="theme-color" content="#000">');
+  });
+
+  test("normalizes trailing slash on assetPrefix", () => {
+    const prefix = "/_nextpy/".replace(/\/+$/, "");
+    const html = template({ assetPrefix: prefix, slug: "index" });
+    expect(html).toContain('href="/_nextpy/styles.css"');
+    expect(html).not.toContain("/_nextpy//");
+  });
+});
+
+describe("preprocess returns meta for MDX", () => {
+  const tmpBase = path.join(process.cwd(), "scratch", "tmp", "meta-test");
+  const componentsDir = path.join(tmpBase, "components");
+
+  function setup() {
+    rmSync(tmpBase, { recursive: true, force: true });
+    mkdirSync(componentsDir, { recursive: true });
+  }
+
+  function cleanup() {
+    rmSync(tmpBase, { recursive: true, force: true });
+  }
+
+  test("returns meta from MDX frontmatter", async () => {
+    setup();
+    try {
+      const mdxDir = path.join(tmpBase, "pages");
+      mkdirSync(mdxDir, { recursive: true });
+
+      const mdxFile = path.join(mdxDir, "dashboard.mdx");
+      writeFileSync(
+        mdxFile,
+        "---\ntitle: Dashboard\ndescription: Overview\n---\n\n# Dashboard\n",
+      );
+
+      const { meta } = await preprocess({ dashboard: mdxFile }, componentsDir);
+
+      expect(meta.get("dashboard")).toEqual({
+        title: "Dashboard",
+        description: "Overview",
+      });
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("MDX without frontmatter has no meta", async () => {
+    setup();
+    try {
+      const mdxDir = path.join(tmpBase, "pages");
+      mkdirSync(mdxDir, { recursive: true });
+
+      const mdxFile = path.join(mdxDir, "plain.mdx");
+      writeFileSync(mdxFile, "# Just content\n");
+
+      const { meta } = await preprocess({ plain: mdxFile }, componentsDir);
+
+      expect(meta.get("plain")).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+});