@markii/pack-build 0.0.1 → 0.17.0-next.2

package/README.md

@@ -1,4 +1,10 @@
 # @markii/pack-build
 
-Placeholder that reserves the name. The first real release is published from
-https://github.com/markii-org/markii.
+Builds [Markii](https://github.com/markii-org/markii) component packs:
+compiles a pack's component sources (and the CSS they import) with
+esbuild's WebAssembly build, writes the prebuilt form, or produces a
+`.mkp` archive. It is the one Markii package that carries a build
+toolchain, for authoring hosts and pack build scripts; an app that only
+installs prebuilt packs does not need it. Node only.
+
+See `docs/packs.md` in the repository for the pack contract.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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 type { ConfirmPackOverwrite, ExportPackOptions, PackExportBuilder, PackExportFs, PackExportOutcome, } from './pack-export.js';
+export { exportPack, resolveExportTarget } from './pack-export.js';
+export type { ExportPackArchiveOptions, PackExportArchiveOutcome, } from './pack-export-archive.js';
+export { exportPackArchive } from './pack-export-archive.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+// @markii/pack-build: compiling a pack's sources and exporting the
+// 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 { exportPackArchive } from './pack-export-archive.js';

package/dist/pack-build.d.ts

@@ -0,0 +1,113 @@
+import type { PackManifest } from '@markii/pack';
+/**
+ * Everything `buildPackRegistrationScript` needs to know about one pack —
+ * a host-neutral SUBSET of `apps/vscode`'s `DiscoveredPack` (and whatever
+ * an Obsidian host's own discovery module produces): a discovery module's
+ * richer, host-specific result (which also carries e.g. a `webview.js`
+ * convention path, a `scripts/` directory) is passed here directly and
+ * satisfies this shape structurally — no import needed either way, and no
+ * host-specific field this module has no business knowing about.
+ */
+export interface PackBuildSource {
+    /** The pack's own folder on disk — `resolveDir` for the synthetic entry `entrySource` compiles. */
+    readonly folder: string;
+    readonly manifest: PackManifest;
+    /** 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. */
+    readonly componentPathsByEngine?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+/** 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
+ * `Record<string,string>` from `parsePackManifest`'s own construction is
+ * already insertion order, and there is exactly one manifest shape), every
+ * declared component's absolute path plus its own source bytes, and every
+ * CSS file the component sources statically import (`cssSources`, keyed the
+ * same way) — so touching any one component file, any CSS file it imports,
+ * adding/removing a component, or shipping a new builder version each
+ * independently invalidates the cache FILE NAME. Entries are sorted by path
+ * first so the digest does not depend on either map's insertion order.
+ *
+ * This key alone cannot know about a file only a transitive import
+ * discovers (this file's top doc comment: the sidecar cache is what
+ * catches that). It still decides the cache file's NAME because it is
+ * cheap, deterministic, and known before any build attempt — an edit to a
+ * declared component or its statically-visible CSS gets a fresh name
+ * immediately, and a genuinely stale entry under an unchanged name is
+ * still caught by the sidecar hash check before it is ever reused.
+ */
+export declare function computeCacheKey(pack: PackBuildSource, componentSources: ReadonlyMap<string, string>, cssSources?: ReadonlyMap<string, string>): string;
+/** What `buildPackRegistrationScript` reports. `'built'` and `'failed'` are real outcomes of an attempted build; `'skipped'` means no attempt was made at all (the default, no-op builder a host may use when no cache directory is configured) — kept distinct from `'failed'` so a caller never records a spurious "build failed" reason for a pack that simply had no build attempted. */
+export type PackBuildOutcome = {
+    readonly kind: 'built';
+    readonly scriptPath: string;
+    /**
+     * Absolute path to this build's emitted stylesheet, a SIBLING of
+     * `scriptPath` in the same cache directory with the same
+     * content-hash base name — present only when at least one built
+     * component imported CSS (`import './x.css'`); a pack with no CSS
+     * imports produces `undefined` here and no `.css` file is ever
+     * written, matching its behavior before this feature existed.
+     */
+    readonly stylesheetPath?: string;
+    /**
+     * Rule A/B warnings (`./pack-css-lint.ts`) against `stylesheetPath`'s
+     * emitted content — empty when there is no stylesheet, or the
+     * stylesheet has no findings. Warnings only: never a build failure,
+     * never thrown; a host's own diagnostics surface (`apps/vscode`'s
+     * `pack-diagnostics.ts`) surfaces these.
+     */
+    readonly warnings: readonly string[];
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+} | {
+    readonly kind: 'skipped';
+};
+export interface PackBuildOptions {
+    /** Absolute path to a real, unbundled `esbuild-wasm/lib/browser.js` — forwarded to `loadEsbuildWasm`. */
+    readonly esbuildBrowserModulePath?: string;
+    /** Absolute path to the `esbuild.wasm` binary this builder compiles once via `WebAssembly.compile` — forwarded to `loadEsbuildWasm`. */
+    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
+ * script. NEVER throws: every failure mode (a missing component source, a
+ * broken `.tsx`, an esbuild-wasm error) comes back as
+ * `{ kind: 'failed', reason }` — a host records that reason next to the
+ * pack and simply excludes it from its own webview/renderer registry, the
+ * same quiet degradation as every other pack failure (AGENTS.md's
+ * cleanliness rule: never a compiler error dump as page content).
+ *
+ * `cacheDir` is a HOST-OWNED directory — never the pack's own folder, per
+ * AGENTS.md's cleanliness rule that the user's file tree stays clean. A
+ * cache hit (the built script for this exact pack content already exists
+ * under `cacheDir`) skips esbuild-wasm entirely: esbuild-wasm
+ * initialization is not free (see this file's top doc comment for measured
+ * figures), and a warm preview open must not pay that cost on every panel
+ * (re)creation.
+ */
+export declare function buildPackRegistrationScript(pack: PackBuildSource, cacheDir: string, options?: PackBuildOptions): Promise<PackBuildOutcome>;
+/**
+ * Builds (or reuses a cached build of) one pack's TERMINAL script
+ * (`terminal.js`): the `ansi` sources of every component that names one,
+ * compiled through the same esbuild-wasm in-process path, as one
+ * self-contained ESM module (no imports: the loader evaluates it from a
+ * `data:` URL). `react` and `ink` imports and JSX read the instances the
+ * CLI publishes on `globalThis` (`__markiiReactInk`, `__markiiInk`), only
+ * inside render-time functions. The output ends by calling
+ * `globalThis.__markiiRegisterTerminalPack(manifestJson, components)`.
+ * Returns `'skipped'` when no component names an `ansi` source. A CSS
+ * 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 {};