@markii/pack-build 0.17.0-next.4 → 0.17.0-next.6

package/README.md

@@ -7,4 +7,63 @@ 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
+
+- `buildPackArchive(packFolder, options?)` takes a folder that holds one
+  pack and returns the bytes of its `.mkp` archive. It discovers the pack,
+  compiles its React views and, when the pack has terminal views, its
+  terminal script, and zips the result. The optional `cacheDir` is a folder
+  you own for the compiled scripts. It defaults to a folder under the
+  system's temporary directory and is never the pack's own folder.
+- `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`.
+- `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.
+
+Every build function returns an outcome and never throws. The outcome is
+`built`, `failed` with a reason, or `skipped`. `buildPackArchive` returns
+`built` or `failed`.
+
+The two script builders return paths into the cache. Those paths are valid
+until the next build replaces them, so read a script before you build
+again. `buildPackArchive` does this for you and returns bytes.
+
+## The pack source
+
+The lower-level functions take a pack as `discoverPacks` from
+`@markii/host/internal` 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. A build script that only wants an archive
+does not need any of this: it calls `buildPackArchive` with the folder.
+
+## Example
+
+This script writes one `.mkp` archive for each pack folder under
+`./packs`.
+
+```ts
+import { readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildPackArchive } from '@markii/pack-build';
+
+const root = './packs';
+const cacheDir = join(process.cwd(), '.pack-cache');
+
+for (const entry of await readdir(root, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const result = await buildPackArchive(join(root, entry.name), { cacheDir });
+  if (result.kind === 'failed') throw new Error(result.reason);
+  for (const warning of result.warnings) console.warn(warning);
+  await writeFile(result.fileName, result.bytes);
+}
+```
+
 See `docs/packs.md` in the repository for the pack contract.

package/dist/build-pack-archive.d.ts

@@ -0,0 +1,34 @@
+export interface BuildPackArchiveOptions {
+    /**
+     * A folder this caller owns, where compiled scripts are cached. It is
+     * never the pack's own folder. Defaults to `markii-pack-build` under the
+     * operating system's temporary folder.
+     */
+    readonly cacheDir?: string;
+}
+export type BuildPackArchiveOutcome = {
+    readonly kind: 'built';
+    /** The `.mkp` archive's bytes. */
+    readonly bytes: Uint8Array;
+    /** `<name>-<version>.mkp`, or `<name>.mkp` when the manifest declares no version. */
+    readonly fileName: string;
+    /** The build's pack-CSS lint warnings. Empty when there are none. */
+    readonly warnings: readonly string[];
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+/**
+ * Builds the `.mkp` archive for the one pack in `packFolder`. The folder
+ * either holds a `pack.json` itself or holds exactly one child folder that
+ * does. Zero packs, several packs and an invalid pack are all `failed`,
+ * with the reason discovery gave. Never throws, and never writes into
+ * `packFolder`: the build is cached under `options.cacheDir`.
+ *
+ * The compiled scripts live in that cache until the next build.
+ * `buildPackRegistrationScript` and `buildPackTerminalScript` return paths
+ * into it, and those paths are valid only until the next build replaces
+ * them. This function reads them back before it returns, so its result
+ * holds bytes, not paths.
+ */
+export declare function buildPackArchive(packFolder: string, options?: BuildPackArchiveOptions): Promise<BuildPackArchiveOutcome>;

package/dist/build-pack-archive.js

@@ -0,0 +1,98 @@
+/**
+ * `buildPackArchive`: one call from a pack folder to the bytes of its
+ * `.mkp` archive. It discovers the pack in the folder, compiles its React
+ * views and, when the pack has terminal views, its terminal script, and
+ * zips the result. A build script needs this and nothing else from
+ * `@markii/host`.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import * as path from 'node:path';
+import { discoverPacks } from '@markii/host/internal';
+import { buildPackRegistrationScript, buildPackTerminalScript, } from './pack-build.js';
+import { exportPackArchive } from './pack-export-archive.js';
+async function readText(absolutePath) {
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function listEntries(absoluteDir) {
+    try {
+        const entries = await readdir(absoluteDir, { withFileTypes: true });
+        return entries.map((entry) => ({
+            name: entry.name,
+            isDirectory: entry.isDirectory(),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function describeThrown(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Builds the `.mkp` archive for the one pack in `packFolder`. The folder
+ * either holds a `pack.json` itself or holds exactly one child folder that
+ * does. Zero packs, several packs and an invalid pack are all `failed`,
+ * with the reason discovery gave. Never throws, and never writes into
+ * `packFolder`: the build is cached under `options.cacheDir`.
+ *
+ * The compiled scripts live in that cache until the next build.
+ * `buildPackRegistrationScript` and `buildPackTerminalScript` return paths
+ * into it, and those paths are valid only until the next build replaces
+ * them. This function reads them back before it returns, so its result
+ * holds bytes, not paths.
+ */
+export async function buildPackArchive(packFolder, options = {}) {
+    try {
+        const cacheDir = options.cacheDir ?? path.join(tmpdir(), 'markii-pack-build');
+        const discovered = await discoverPacks([packFolder], readText, listEntries);
+        if (discovered.packs.length === 0) {
+            const reasons = discovered.skipped.map((entry) => entry.reason);
+            return {
+                kind: 'failed',
+                reason: reasons.length > 0
+                    ? `no pack could be built from "${packFolder}": ${reasons.join('; ')}`
+                    : `no pack was found in "${packFolder}"`,
+            };
+        }
+        if (discovered.packs.length > 1) {
+            return {
+                kind: 'failed',
+                reason: `"${packFolder}" holds ${String(discovered.packs.length)} packs, and a build takes one`,
+            };
+        }
+        const pack = discovered.packs[0];
+        const built = await exportPackArchive({
+            pack,
+            cacheDir,
+            build: buildPackRegistrationScript,
+            buildTerminal: buildPackTerminalScript,
+            fs: { readFile: readText, listDirectory: listFileNames },
+        });
+        if (built.kind === 'failed') {
+            return { kind: 'failed', reason: built.reason };
+        }
+        return {
+            kind: 'built',
+            bytes: built.bytes,
+            fileName: built.fileName,
+            warnings: built.warnings,
+        };
+    }
+    catch (error) {
+        return { kind: 'failed', reason: describeThrown(error) };
+    }
+}
+async function listFileNames(absoluteDir) {
+    try {
+        return await readdir(absoluteDir);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export type { PackBuildOptions, PackBuildOutcome, PackBuildSource, PackFileReader, } from './pack-build.js';
-export { buildPackRegistrationScript, buildPackTerminalScript, computeCacheKey, } from './pack-build.js';
-export { lintPackCss, lintPackCssColors, lintPackCssPrefix, } from './pack-css-lint.js';
+export { buildPackRegistrationScript, buildPackTerminalScript, } from './pack-build.js';
+export type { BuildPackArchiveOptions, BuildPackArchiveOutcome, } from './build-pack-archive.js';
+export { buildPackArchive } from './build-pack-archive.js';
 export type { ConfirmPackOverwrite, ExportPackOptions, PackExportBuilder, PackExportFs, PackExportOutcome, } from './pack-export.js';
-export { exportPack, resolveExportTarget } from './pack-export.js';
+export { exportPack } from './pack-export.js';
 export type { ExportPackArchiveOptions, PackExportArchiveOutcome, } from './pack-export-archive.js';
 export { exportPackArchive } from './pack-export-archive.js';

package/dist/index.js

@@ -2,7 +2,7 @@
 // prebuilt form. Node only (esbuild-wasm, node:fs, node:crypto). The
 // neutral half of the prebuilt-pack convention (file names, shadowing
 // detection) stays in @markii/host, which this package imports.
-export { buildPackRegistrationScript, buildPackTerminalScript, computeCacheKey, } from './pack-build.js';
-export { lintPackCss, lintPackCssColors, lintPackCssPrefix, } from './pack-css-lint.js';
-export { exportPack, resolveExportTarget } from './pack-export.js';
+export { buildPackRegistrationScript, buildPackTerminalScript, } from './pack-build.js';
+export { buildPackArchive } from './build-pack-archive.js';
+export { exportPack } from './pack-export.js';
 export { exportPackArchive } from './pack-export-archive.js';

package/dist/pack-build.d.ts

@@ -21,8 +21,6 @@ export interface PackBuildSource {
 }
 /** Reads a file's UTF-8 text, or resolves `undefined` if it does not exist / cannot be read. Never rejects for an ordinary "not found" — injected so this module needs no real filesystem to test. Structurally identical to `apps/vscode`'s own `PackFileReader` (`./discover.ts`), deliberately not shared by import: a host's discovery module and this builder are independent seams. */
 export type PackFileReader = (absolutePath: string) => Promise<string | undefined>;
-/** esbuild-wasm's browser (in-process WebAssembly) `build` function signature — imported as a TYPE only, so this line never causes `esbuild-wasm` itself to be pulled into whatever bundles this module (see `loadEsbuildWasm`'s doc comment for why the VALUE side must never be a static import). */
-type EsbuildBuildFn = typeof import('esbuild-wasm/lib/browser.js').build;
 /**
  * The PRE-build cache key for one pack: a SHA-256 of `BUILDER_VERSION`, the
  * manifest (stable-stringified: `Object.keys` order for a plain
@@ -78,8 +76,6 @@ export interface PackBuildOptions {
     readonly esbuildWasmBinaryPath?: string;
     /** Reads one component source file's UTF-8 text, or `undefined` if unreadable — defaults to real `node:fs`. Injected so a build-failure ("missing component source") path is testable without touching disk. */
     readonly readComponentSource?: PackFileReader;
-    /** Replaces esbuild-wasm's `build` function outright — for tests that want to assert cache behavior (or a build failure) without paying for a real esbuild-wasm invocation, and for the ANY-real-invocation counting a cache-hit test needs. Bypasses `loadEsbuildWasm`/the module-path options entirely when given. */
-    readonly build?: EsbuildBuildFn;
 }
 /**
  * Builds (or reuses a cached build of) one pack's webview registration
@@ -112,4 +108,3 @@ export declare function buildPackRegistrationScript(pack: PackBuildSource, cache
  * import in a terminal source is compiled away and ignored. Never throws.
  */
 export declare function buildPackTerminalScript(pack: PackBuildSource, cacheDir: string, options?: PackBuildOptions): Promise<PackBuildOutcome>;
-export {};

package/dist/pack-export-archive.js

@@ -183,7 +183,10 @@ export async function exportPackArchive(options) {
     for (const file of luaFiles) {
         zipInput[`scripts/${file.name}`] = encoder.encode(file.text);
     }
-    const bytes = zipSync(zipInput);
+    // A fixed modification time, so the same pack zips to the same bytes at
+    // any hour and on any machine. The date is built from local components,
+    // so the stored DOS time reads 1980-01-01 00:00 in every time zone.
+    const bytes = zipSync(zipInput, { mtime: new Date(1980, 0, 1, 0, 0, 0) });
     return {
         kind: 'built',
         packName,

package/dist/pack-export.d.ts

@@ -58,7 +58,7 @@ export type PackExportOutcome = {
     /** The build's pack-CSS lint warnings, passed through unchanged. */
     readonly warnings: readonly string[];
 } | {
-    readonly kind: 'cancelled';
+    readonly kind: 'declined';
     readonly packName: string;
 } | {
     readonly kind: 'failed';
@@ -80,7 +80,7 @@ export declare function resolveExportTarget(root: string, ...segments: readonly
  * NEVER throws: every failure (an unsafe `exportName`, a build failure, an
  * unreadable build output or `pack.json`, a write that fails) comes back as
  * `{ kind: 'failed', reason }`. A declined overwrite comes back as
- * `{ kind: 'cancelled' }` with nothing written.
+ * `{ kind: 'declined' }` with nothing written.
  *
  * Order of operations: resolve the destination folder and every write
  * target inside it (path-jailed against `destinationDir`, including the

package/dist/pack-export.js

@@ -67,7 +67,7 @@ function packNameOf(pack) {
  * NEVER throws: every failure (an unsafe `exportName`, a build failure, an
  * unreadable build output or `pack.json`, a write that fails) comes back as
  * `{ kind: 'failed', reason }`. A declined overwrite comes back as
- * `{ kind: 'cancelled' }` with nothing written.
+ * `{ kind: 'declined' }` with nothing written.
  *
  * Order of operations: resolve the destination folder and every write
  * target inside it (path-jailed against `destinationDir`, including the
@@ -274,7 +274,7 @@ export async function exportPack(options) {
             return { kind: 'failed', packName, reason: describeThrown(err) };
         }
         if (!proceed) {
-            return { kind: 'cancelled', packName };
+            return { kind: 'declined', packName };
         }
     }
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/pack-build",
-  "version": "0.17.0-next.4",
+  "version": "0.17.0-next.6",
   "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",
@@ -39,8 +39,8 @@
     "build:dist": "rm -rf dist && tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@markii/host": "^0.17.0-next.4",
-    "@markii/pack": "^0.17.0-next.4",
+    "@markii/host": "^0.17.0-next.6",
+    "@markii/pack": "^0.17.0-next.6",
     "esbuild-wasm": "^0.28.2",
     "fflate": "^0.8.3"
   },