@markii/pack-build 0.17.0-next.3 → 0.17.0-next.5

package/README.md

@@ -7,4 +7,77 @@ esbuild's WebAssembly build, writes the prebuilt form, or produces a
 toolchain, for authoring hosts and pack build scripts; an app that only
 installs prebuilt packs does not need it. Node only.
 
+## Entry points
+
+- `buildPackRegistrationScript(pack, cacheDir, options?)` compiles the
+  pack's React sources into one registration script, `webview.js`, and an
+  optional stylesheet. It caches the result under `cacheDir`, which must
+  be a folder you own and never the pack's own folder.
+- `buildPackTerminalScript(pack, cacheDir, options?)` does the same for
+  the pack's `ansi` sources and produces `terminal.js`. It reports
+  `skipped` when no component names an `ansi` source.
+- `exportPackArchive({ pack, cacheDir, build, buildTerminal?, fs })`
+  builds through those functions and returns the bytes of a
+  `<name>-<version>.mkp` archive. It writes nothing itself.
+- `exportPack` writes the prebuilt form into a destination folder instead
+  of an archive.
+- `lintPackCss` returns the class-prefix and color warnings for a
+  stylesheet.
+
+Every build function returns an outcome and never throws. The outcome is
+`built`, `failed` with a reason, or `skipped`.
+
+## The pack source
+
+Each function takes a pack as `discoverPacks` from `@markii/host`
+returns it. A discovered pack carries its `folder`, its parsed
+`manifest`, the `manifestText`, the absolute `componentPaths` of its
+React sources, `componentPathsByEngine` for other engines, and its
+`scriptsDir` for shared Lua. `discoverPacks(folders, readFile,
+listDirectory)` takes the folders to scan and two read functions.
+`createNodePackDiscoveryIo()` from `@markii/host/node` supplies both.
+
+## Example
+
+This script discovers the packs in a folder and writes one `.mkp` archive
+for each.
+
+```ts
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { discoverPacks } from '@markii/host';
+import { createNodePackDiscoveryIo } from '@markii/host/node';
+import {
+  buildPackRegistrationScript,
+  buildPackTerminalScript,
+  exportPackArchive,
+} from '@markii/pack-build';
+
+const cacheDir = join(process.cwd(), '.pack-cache');
+await mkdir(cacheDir, { recursive: true });
+
+const io = createNodePackDiscoveryIo();
+const { packs, skipped } = await discoverPacks(
+  ['./packs'],
+  io.readFile,
+  io.listDirectory,
+);
+for (const folder of skipped) console.warn(folder);
+
+for (const pack of packs) {
+  const result = await exportPackArchive({
+    pack,
+    cacheDir,
+    build: buildPackRegistrationScript,
+    buildTerminal: buildPackTerminalScript,
+    fs: {
+      readFile: (path) => readFile(path, 'utf8').catch(() => undefined),
+      listDirectory: (path) => readdir(path).catch(() => []),
+    },
+  });
+  if (result.kind === 'failed') throw new Error(result.reason);
+  await writeFile(result.fileName, result.bytes);
+}
+```
+
 See `docs/packs.md` in the repository for the pack contract.

package/dist/pack-build.d.ts

@@ -12,6 +12,8 @@ export interface PackBuildSource {
     /** The pack's own folder on disk — `resolveDir` for the synthetic entry `entrySource` compiles. */
     readonly folder: string;
     readonly manifest: PackManifest;
+    /** The text of the pack's own `pack.json`, embedded unchanged in the compiled script. Absent means the parsed manifest is serialized instead, which can lose fields the parser normalizes. */
+    readonly manifestText?: string;
     /** Local component name -> absolute path to its declared source file (`manifest.components[name]`, resolved against `folder`). */
     readonly componentPaths: Readonly<Record<string, string>>;
     /** Engine id -> (local component name -> absolute source path). A terminal build reads its `ansi` slice here; `componentPaths` stays the `react` slice. Absent means the pack names no sources for any other engine. */

package/dist/pack-build.js

@@ -151,7 +151,7 @@ import { existsSync } from 'node:fs';
 import { packComponents } from '@markii/pack';
 import { lintPackCss } from './pack-css-lint.js';
 /** Bumped whenever this module's OUTPUT for the same pack sources would change (a shim/plugin tweak, an esbuild option change) — folded into the cache key (`computeCacheKey`) so a stale cached script from a previous version of this builder is never reused after an upgrade. Bumped again for the `inject`-based JSX shim (replacing `banner`): a pack built before this version leaves `__markiiJSX` as a global on `window`, so every pack must rebuild once to pick up the fix. */
-const BUILDER_VERSION = 5;
+const BUILDER_VERSION = 6;
 /**
  * `esbuild-wasm`'s browser entry unconditionally reaches for the `self`
  * global while assembling its Go/WebAssembly runtime bridge — confirmed
@@ -509,18 +509,26 @@ function resolveFailure(text) {
  * rejection is an explicit `errors` result, never `undefined` — so
  * esbuild's own filesystem-less default resolver is never reached.
  */
-function virtualSourcePlugin(packName, fileContents, jailRealRoot, virtualOnlyPaths) {
+function virtualSourcePlugin(packName, packFolder, fileContents, jailRealRoot, virtualOnlyPaths) {
+    // esbuild names each module in its output by the path a plugin returns,
+    // so a module is handed back under its pack-relative key (never its
+    // absolute build-machine path) and mapped to the real file only here.
+    const keyFor = (absolutePath) => path.relative(packFolder, absolutePath).split(path.sep).join('/');
+    const absoluteFor = (key) => path.resolve(packFolder, key);
     return {
         name: 'markii-pack-source',
         setup(build) {
             build.onResolve({ filter: /.*/ }, async (args) => {
+                const importer = args.namespace === VIRTUAL_SOURCE_NAMESPACE
+                    ? absoluteFor(args.importer)
+                    : args.importer;
                 let base;
                 if (path.isAbsolute(args.path)) {
                     base = args.path;
                 }
                 else if (args.path.startsWith('./') ||
                     args.path.startsWith('../')) {
-                    base = path.resolve(path.dirname(args.importer), args.path);
+                    base = path.resolve(path.dirname(importer), args.path);
                 }
                 else {
                     return resolveFailure(`pack "${packName}": cannot resolve "${args.path}" — a pack import must be a relative path within the pack, or "react"/"react-dom"; other bare package specifiers are not supported (packs are self-contained).`);
@@ -529,13 +537,16 @@ function virtualSourcePlugin(packName, fileContents, jailRealRoot, virtualOnlyPa
                     ? base
                     : await resolveImportCandidate(base);
                 if (resolved === undefined) {
-                    return resolveFailure(`pack "${packName}": could not resolve "${args.path}" imported from "${args.importer}"`);
+                    return resolveFailure(`pack "${packName}": could not resolve "${args.path}" imported from "${importer}"`);
                 }
                 if (virtualOnlyPaths.has(resolved)) {
                     // Never exists on disk (the JSX shim) — realpath would throw
                     // ENOENT. Its content was written by this builder, not read
                     // from the pack, so the jail check has nothing to verify.
-                    return { path: resolved, namespace: VIRTUAL_SOURCE_NAMESPACE };
+                    return {
+                        path: keyFor(resolved),
+                        namespace: VIRTUAL_SOURCE_NAMESPACE,
+                    };
                 }
                 let real;
                 try {
@@ -558,13 +569,17 @@ function virtualSourcePlugin(packName, fileContents, jailRealRoot, virtualOnlyPa
                     }
                     fileContents.set(resolved, text);
                 }
-                return { path: resolved, namespace: VIRTUAL_SOURCE_NAMESPACE };
+                return {
+                    path: keyFor(resolved),
+                    namespace: VIRTUAL_SOURCE_NAMESPACE,
+                };
             });
             build.onLoad({ filter: /.*/, namespace: VIRTUAL_SOURCE_NAMESPACE }, (args) => {
+                const absolutePath = absoluteFor(args.path);
                 return {
-                    contents: fileContents.get(args.path) ?? '',
-                    loader: loaderForPath(args.path),
-                    resolveDir: path.dirname(args.path),
+                    contents: fileContents.get(absolutePath) ?? '',
+                    loader: loaderForPath(absolutePath),
+                    resolveDir: path.dirname(absolutePath),
                 };
             });
         },
@@ -610,6 +625,10 @@ const JSX_SHIM_SOURCE = [
 const WEBVIEW_ENGINE = 'react';
 /** The engine id whose sources the terminal build compiles (`@markii/ansi`'s `ANSI_ENGINE_ID`). */
 const TERMINAL_ENGINE = 'ansi';
+/** The manifest text a compiled script registers: the pack's own file text when the caller kept it, else the parsed manifest re-serialized. */
+function manifestSourceText(pack) {
+    return pack.manifestText ?? JSON.stringify(pack.manifest);
+}
 /** One component's declared local name and the absolute path to its source, in `manifest.components` declaration order. Reads the manifest through `@markii/pack`'s `packComponents()` (the one accessor that normalizes both the string shorthand and the object form) rather than walking `pack.manifest.components` directly. */
 function orderedComponents(pack, engine = WEBVIEW_ENGINE) {
     const paths = engine === WEBVIEW_ENGINE
@@ -643,7 +662,7 @@ function entrySource(pack, components) {
     const picks = components
         .map((c, i) => `  ${JSON.stringify(c.localName)}: __markiiPick(__markiiMod${i}),`)
         .join('\n');
-    const manifestJsonLiteral = JSON.stringify(JSON.stringify(pack.manifest));
+    const manifestJsonLiteral = JSON.stringify(manifestSourceText(pack));
     // Which local names the manifest declares `kind: "inline"` for, baked
     // into the artifact so a standalone consumer of the registration
     // convention sees a truthful `inline` flag (loadPack re-derives it from
@@ -711,7 +730,7 @@ function terminalEntrySource(pack, components) {
     const picks = components
         .map((c, i) => `  ${JSON.stringify(c.localName)}: __markiiPick(__markiiMod${i}),`)
         .join('\n');
-    const manifestJsonLiteral = JSON.stringify(JSON.stringify(pack.manifest));
+    const manifestJsonLiteral = JSON.stringify(manifestSourceText(pack));
     const inlineNames = packComponents(pack.manifest)
         .filter((listing) => listing.kind === 'inline')
         .map((listing) => listing.localName);
@@ -799,7 +818,7 @@ function staticCssImportPaths(source, sourceDir) {
 export function computeCacheKey(pack, componentSources, cssSources = new Map()) {
     const hash = createHash('sha256');
     hash.update(`builder:${BUILDER_VERSION}\n`);
-    hash.update(`manifest:${JSON.stringify(pack.manifest)}\n`);
+    hash.update(`manifest:${manifestSourceText(pack)}\n`);
     const entries = [...componentSources.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
     for (const [sourcePath, source] of entries) {
         hash.update(`component:${sourcePath}\n`);
@@ -1154,7 +1173,7 @@ async function buildPackScript(pack, cacheDir, options, kind) {
                 terminal
                     ? lazyGlobalModulePlugin(TERMINAL_LAZY_GLOBAL_MODULES, 'globalThis')
                     : lazyGlobalModulePlugin(),
-                virtualSourcePlugin(pack.manifest.name, fileContents, jailRealRoot, virtualOnlyPaths),
+                virtualSourcePlugin(pack.manifest.name, pack.folder, fileContents, jailRealRoot, virtualOnlyPaths),
             ],
             logLevel: 'silent',
         });

package/dist/pack-export-archive.js

@@ -24,7 +24,7 @@
 import * as path from 'node:path';
 import { zipSync } from 'fflate';
 import { packArchiveFileName } from '@markii/pack';
-import { PREBUILT_TERMINAL_SCRIPT_FILENAME, emptyWebviewScript, } from '@markii/host';
+import { PREBUILT_TERMINAL_SCRIPT_FILENAME, emptyWebviewScript, } from '@markii/host/internal';
 const MANIFEST_FILENAME = 'pack.json';
 const SCRIPT_FILENAME = 'webview.js';
 const STYLESHEET_FILENAME = 'webview.css';

package/dist/pack-export.js

@@ -23,7 +23,7 @@
  * is injected too.
  */
 import * as path from 'node:path';
-import { PREBUILT_SCRIPT_FILENAME, PREBUILT_STYLESHEET_FILENAME, PREBUILT_TERMINAL_SCRIPT_FILENAME, emptyWebviewScript, } from '@markii/host';
+import { PREBUILT_SCRIPT_FILENAME, PREBUILT_STYLESHEET_FILENAME, PREBUILT_TERMINAL_SCRIPT_FILENAME, emptyWebviewScript, } from '@markii/host/internal';
 const MANIFEST_FILENAME = 'pack.json';
 const SCRIPTS_DIRNAME = 'scripts';
 /**
@@ -174,7 +174,7 @@ export async function exportPack(options) {
                 reason: `pack "${packName}" was not built`,
             };
         }
-        scriptText = emptyWebviewScript(JSON.stringify(pack.manifest));
+        scriptText = emptyWebviewScript(manifestText);
     }
     else {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/pack-build",
-  "version": "0.17.0-next.3",
+  "version": "0.17.0-next.5",
   "description": "Pack compilation for Markii authoring hosts: compiles a pack's component sources (and imported CSS) with esbuild-wasm's in-process path, and writes the prebuilt form or a .mkp archive. Node only.",
   "keywords": [
     "markdown",
@@ -29,6 +29,9 @@
       "default": "./dist/index.js"
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "test": "vitest run",
     "build": "tsc --noEmit -p tsconfig.json",
@@ -36,8 +39,8 @@
     "build:dist": "rm -rf dist && tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@markii/host": "^0.17.0-next.3",
-    "@markii/pack": "^0.17.0-next.3",
+    "@markii/host": "^0.17.0-next.5",
+    "@markii/pack": "^0.17.0-next.5",
     "esbuild-wasm": "^0.28.2",
     "fflate": "^0.8.3"
   },