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

package/dist/pack-css-lint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Plain string analysis over ONE pack's emitted CSS (`./pack-build.ts`'s
+ * output, either freshly built or read back from the cache) — two
+ * authoring rules, both WARNINGS only, per the pack CSS design
+ * (docs/packs.md, the "packs style themselves" slice): a warning never
+ * fails a build, never throws, and never blocks a pack's stylesheet from
+ * loading (AGENTS.md's "clean is not silent": a problem gets a full
+ * diagnostic somewhere findable — the "Markii" output channel via
+ * `./pack-diagnostics.ts` — never a build failure or missing styling).
+ *
+ * No CSS parser dependency (AGENTS.md's dependency rule: only what's listed
+ * under Stack) — both rules are small, deliberately permissive string scans
+ * over the EMITTED (already-bundled-by-esbuild) CSS text, not the author's
+ * original source. `vscode`-free and pure so it is exhaustively testable
+ * without esbuild or a webview.
+ */
+/**
+ * Rule A: warn when a declaration's value carries a raw color literal
+ * (hex/`rgb()`/`rgba()`/`hsl()`/`hsla()`) instead of one of `doc.css`'s
+ * `--mk-*` palette tokens — the exact bug this feature exists to prevent
+ * (hardcoded light colors, unreadable once a host's dark theme remaps the
+ * tokens). Scans the whole emitted CSS text; each match reports the pack
+ * name and the offending `property: value;` declaration. A literal serving
+ * as a `var()` fallback is exempt: see `stripVarFallbacks`.
+ */
+export declare function lintPackCssColors(packName: string, css: string): readonly string[];
+/**
+ * Rule B: warn when a pack CSS selector leads with a class token that does
+ * not carry the pack's `.mk-<packname>_` prefix — the class-uniqueness
+ * mirror of the directive-namespace rule `@markii/pack`'s
+ * `detectNamespaceCollisions` already enforces at install time (two packs
+ * can never share a namespace, so two packs correctly prefixing their
+ * classes can never collide either). Keyframe inner selectors (`0%`,
+ * `from`, `to`) are exempt — see `extractStyleRules`'s `inKeyframes`.
+ */
+export declare function lintPackCssPrefix(packName: string, css: string): readonly string[];
+/** Both rules, in order (colors first, then prefix), as one flat warning list — what `./pack-build.ts` attaches to a `'built'` outcome and `./pack-context.ts`/`./pack-diagnostics.ts` surface to the "Markii" output channel. Warnings only: never thrown, never a build failure. */
+export declare function lintPackCss(packName: string, css: string): readonly string[];

package/dist/pack-css-lint.js

@@ -0,0 +1,231 @@
+/**
+ * Plain string analysis over ONE pack's emitted CSS (`./pack-build.ts`'s
+ * output, either freshly built or read back from the cache) — two
+ * authoring rules, both WARNINGS only, per the pack CSS design
+ * (docs/packs.md, the "packs style themselves" slice): a warning never
+ * fails a build, never throws, and never blocks a pack's stylesheet from
+ * loading (AGENTS.md's "clean is not silent": a problem gets a full
+ * diagnostic somewhere findable — the "Markii" output channel via
+ * `./pack-diagnostics.ts` — never a build failure or missing styling).
+ *
+ * No CSS parser dependency (AGENTS.md's dependency rule: only what's listed
+ * under Stack) — both rules are small, deliberately permissive string scans
+ * over the EMITTED (already-bundled-by-esbuild) CSS text, not the author's
+ * original source. `vscode`-free and pure so it is exhaustively testable
+ * without esbuild or a webview.
+ */
+/**
+ * Single-pass, stack-based extraction of every non-at-rule block in `css`:
+ * whenever a `{` is reached, the buffered text since the last brace is the
+ * block's "prelude". A prelude starting with `@` is a container (`@media`,
+ * `@supports`, `@keyframes`, `@font-face`, …) whose own prelude is never
+ * itself a rule; anything else — at ANY nesting depth, including inside an
+ * `@media`/`@supports` container — is a real style rule. This naturally
+ * handles one level of media-query nesting (the common case) and reports
+ * each such nested rule's OWN selector, not the wrapping `@media (...)`
+ * text. `@keyframes` inner blocks (`0%`, `from`, `to`) are still collected
+ * as "rules" by this same logic — `inKeyframes` is what lets callers skip
+ * the prefix check for exactly those.
+ */
+function extractStyleRules(css) {
+    const rules = [];
+    const stack = [];
+    let buffer = '';
+    let enclosingAtRule;
+    for (let i = 0; i < css.length; i++) {
+        const ch = css[i];
+        if (ch === '{') {
+            const prelude = buffer.trim();
+            buffer = '';
+            const isAtRule = prelude.startsWith('@');
+            stack.push({ prelude, isAtRule, contentStart: i + 1, enclosingAtRule });
+            if (isAtRule)
+                enclosingAtRule = prelude;
+            continue;
+        }
+        if (ch === '}') {
+            const frame = stack.pop();
+            buffer = '';
+            if (!frame)
+                continue;
+            if (!frame.isAtRule) {
+                rules.push({
+                    selector: frame.prelude,
+                    declarations: css.slice(frame.contentStart, i),
+                    inKeyframes: /@(-[a-z]+-)?keyframes\b/i.test(frame.enclosingAtRule ?? ''),
+                });
+            }
+            enclosingAtRule = frame.enclosingAtRule;
+            continue;
+        }
+        buffer += ch;
+    }
+    return rules;
+}
+/**
+ * Strips CSS block comments (`slash-star ... star-slash`). esbuild's CSS
+ * bundler always emits at least one — a source-path banner comment per
+ * bundled file, see `./pack-build.ts`'s doc comment — so both rules below
+ * must not mistake a banner comment's leading text for part of the next
+ * real selector/declaration. Non-greedy so multiple separate comments in
+ * the same file are each stripped individually, rather than everything
+ * between the FIRST comment's start and the LAST comment's end collapsing
+ * into one match.
+ */
+function stripCssComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+/** Matches a `property: value;` declaration anywhere in the CSS text, independent of brace nesting/selector shape — good enough for the deliberately permissive scan Rule A performs. */
+const DECLARATION_RE = /([a-zA-Z-]+)\s*:\s*([^;{}]+);/g;
+/** A hex color, or an `rgb()`/`rgba()`/`hsl()`/`hsla()` function call. `transparent`, `currentColor`, and `inherit` never match this — they are keywords, not literals, so they need no explicit allowlist. */
+const COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\([^)]*\)/;
+/**
+ * A literal used as a `var()` FALLBACK is not the bug this rule hunts:
+ * `var(--mk-border, #e4e4e7)` still follows the palette wherever the palette
+ * exists, and the fallback is what keeps a pack readable against an older
+ * `doc.css` that predates the token. `docs/integration.md` recommends
+ * exactly this shape for host theme layers, so flagging it in pack CSS would
+ * contradict the guidance. Strip the fallback arguments before scanning, and
+ * what remains is genuinely hardcoded color.
+ *
+ * Deliberately simple: this removes everything from the comma to the closing
+ * paren of a `var(`, which is the only form a fallback takes. A nested
+ * `var()` inside a fallback is not worth parsing for a warning-only rule.
+ */
+function stripVarFallbacks(value) {
+    let out = '';
+    let index = 0;
+    while (index < value.length) {
+        const start = value.indexOf('var(', index);
+        if (start === -1) {
+            out += value.slice(index);
+            break;
+        }
+        out += value.slice(index, start);
+        // Scan for this `var(`'s matching close paren, tracking depth so a
+        // fallback that is itself a function call is handled. A naive
+        // `[^()]*` pattern stops at the first inner `(` and leaves the
+        // literal exposed, which produced a false positive on the real
+        // `var(--mk-shadow-sm, rgba(0, 0, 0, 0.05))`.
+        let depth = 0;
+        let cursor = start + 3;
+        let firstComma = -1;
+        for (; cursor < value.length; cursor += 1) {
+            const char = value[cursor];
+            if (char === '(')
+                depth += 1;
+            else if (char === ')') {
+                depth -= 1;
+                if (depth === 0)
+                    break;
+            }
+            else if (char === ',' && depth === 1 && firstComma === -1) {
+                firstComma = cursor;
+            }
+        }
+        if (cursor >= value.length) {
+            // Unbalanced; leave the remainder untouched rather than guessing.
+            out += value.slice(start);
+            break;
+        }
+        const nameEnd = firstComma === -1 ? cursor : firstComma;
+        out += `var(${value.slice(start + 4, nameEnd).trim()})`;
+        index = cursor + 1;
+    }
+    return out;
+}
+/**
+ * The offending `property: value;` text as it appears in a warning line:
+ * collapsed to one line (a multi-line value like a formatted
+ * `linear-gradient(...)` would otherwise splinter the diagnostic across
+ * several console lines) and truncated past `MAX_DECLARATION_EXCERPT`
+ * characters — the excerpt exists to locate the declaration, not to
+ * reproduce it.
+ */
+const MAX_DECLARATION_EXCERPT = 100;
+function declarationExcerpt(property, value) {
+    const oneLine = `${property.trim()}: ${value.trim()};`.replace(/\s+/g, ' ');
+    if (oneLine.length <= MAX_DECLARATION_EXCERPT)
+        return oneLine;
+    return `${oneLine.slice(0, MAX_DECLARATION_EXCERPT - 1)}\u2026`;
+}
+/**
+ * Rule A: warn when a declaration's value carries a raw color literal
+ * (hex/`rgb()`/`rgba()`/`hsl()`/`hsla()`) instead of one of `doc.css`'s
+ * `--mk-*` palette tokens — the exact bug this feature exists to prevent
+ * (hardcoded light colors, unreadable once a host's dark theme remaps the
+ * tokens). Scans the whole emitted CSS text; each match reports the pack
+ * name and the offending `property: value;` declaration. A literal serving
+ * as a `var()` fallback is exempt: see `stripVarFallbacks`.
+ */
+export function lintPackCssColors(packName, css) {
+    const warnings = [];
+    const text = stripCssComments(css);
+    DECLARATION_RE.lastIndex = 0;
+    let match;
+    while ((match = DECLARATION_RE.exec(text)) !== null) {
+        const property = match[1] ?? '';
+        const value = match[2] ?? '';
+        if (!COLOR_LITERAL_RE.test(stripVarFallbacks(value)))
+            continue;
+        warnings.push(`pack "${packName}" CSS uses a raw color literal in "${declarationExcerpt(property, value)}" — use an --mk-* palette token (see docs/integration.md's theming section) instead of a hardcoded color, or it will be unreadable once a host's dark theme remaps the palette.`);
+    }
+    return warnings;
+}
+/**
+ * The required class prefix for `packName`'s selectors — mirrors the
+ * directive-namespace join (`docs/packs.md`: pack name + component name,
+ * joined with `_`), so a pack that avoids namespace collisions in its
+ * directives avoids them in its classes too. Because a pack name (a
+ * `SEGMENT_RE`-validated lowercase-kebab segment) can never itself contain
+ * an underscore, the underscore here always marks exactly the same
+ * boundary the directive-name join does — so, just like two packs'
+ * composed directive names can never collide, two packs' class namespaces
+ * can never overlap either.
+ */
+function requiredPrefix(packName) {
+    return `.mk-${packName}_`;
+}
+/**
+ * True when every comma-separated part of `selector` either starts with
+ * the pack's required prefix, or is not a class selector at all (a bare
+ * element/attribute/pseudo selector with no `.` at all — e.g. `*`, `:root`,
+ * `[data-x]` — carries no namespace risk, so it is not warned on; only a
+ * selector that DOES lead with a class token is held to the prefix).
+ */
+function selectorPartsMissingPrefix(selector, packName) {
+    const prefix = requiredPrefix(packName);
+    return selector
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .filter((part) => part.startsWith('.'))
+        .filter((part) => !part.startsWith(prefix));
+}
+/**
+ * Rule B: warn when a pack CSS selector leads with a class token that does
+ * not carry the pack's `.mk-<packname>_` prefix — the class-uniqueness
+ * mirror of the directive-namespace rule `@markii/pack`'s
+ * `detectNamespaceCollisions` already enforces at install time (two packs
+ * can never share a namespace, so two packs correctly prefixing their
+ * classes can never collide either). Keyframe inner selectors (`0%`,
+ * `from`, `to`) are exempt — see `extractStyleRules`'s `inKeyframes`.
+ */
+export function lintPackCssPrefix(packName, css) {
+    const warnings = [];
+    for (const rule of extractStyleRules(stripCssComments(css))) {
+        if (rule.inKeyframes)
+            continue;
+        for (const part of selectorPartsMissingPrefix(rule.selector, packName)) {
+            warnings.push(`pack "${packName}" CSS selector "${part}" does not start with the pack's required prefix "${requiredPrefix(packName)}" — pack class selectors must be prefixed so two packs' styles can never collide.`);
+        }
+    }
+    return warnings;
+}
+/** Both rules, in order (colors first, then prefix), as one flat warning list — what `./pack-build.ts` attaches to a `'built'` outcome and `./pack-context.ts`/`./pack-diagnostics.ts` surface to the "Markii" output channel. Warnings only: never thrown, never a build failure. */
+export function lintPackCss(packName, css) {
+    return [
+        ...lintPackCssColors(packName, css),
+        ...lintPackCssPrefix(packName, css),
+    ];
+}

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

@@ -0,0 +1,45 @@
+import type { DiscoveredPack } from '@markii/host';
+import type { PackExportBuilder, PackExportFs } from './pack-export.js';
+export type PackExportArchiveOutcome = {
+    readonly kind: 'built';
+    readonly packName: string;
+    /** `<name>-<version>.mkp`, or `<name>.mkp` with no declared version; see `@markii/pack`'s `packArchiveFileName`. */
+    readonly fileName: string;
+    readonly bytes: Uint8Array;
+    readonly scriptBytes: number;
+    /** Set when the archive carries a `terminal.js`. */
+    readonly terminalScriptBytes?: number;
+    readonly stylesheetBytes?: number;
+    /** How many `*.lua` files from the pack's `scripts/` directory were included. 0 when it has none. */
+    readonly scriptFilesCopied: number;
+    /** The build's pack-CSS lint warnings, passed through unchanged. */
+    readonly warnings: readonly string[];
+} | {
+    readonly kind: 'failed';
+    readonly packName: string;
+    readonly reason: string;
+};
+export interface ExportPackArchiveOptions {
+    readonly pack: DiscoveredPack;
+    /** The host-owned build cache directory: the build still runs through the normal cache, only its output is zipped. */
+    readonly cacheDir: string;
+    readonly build: PackExportBuilder;
+    /**
+     * Builds the pack's terminal script (`buildPackTerminalScript` through the
+     * host's cache). When given and the pack names `ansi` sources, the archive
+     * carries the result as `terminal.js`. A host that compiles only for its
+     * own preview omits it; the archive then holds React views only.
+     */
+    readonly buildTerminal?: PackExportBuilder;
+    /** Only the read half of `PackExportFs`: an archive export never writes anywhere on its own. */
+    readonly fs: Pick<PackExportFs, 'readFile' | 'listDirectory'>;
+}
+/**
+ * NEVER throws: every failure (an unreadable `pack.json`, a build failure,
+ * an unreadable built script) comes back as `{ kind: 'failed', reason }`,
+ * matching `exportPack`'s contract. There is no overwrite confirmation
+ * here, unlike `exportPack`: nothing is written to any path by this
+ * function, so "does the destination already have a file" is entirely the
+ * caller's concern once it knows where the user wants the `.mkp` saved.
+ */
+export declare function exportPackArchive(options: ExportPackArchiveOptions): Promise<PackExportArchiveOutcome>;

package/dist/pack-export-archive.js

@@ -0,0 +1,198 @@
+/**
+ * Builds the one output shape "Markii: Export Pack" produces (GitHub issue
+ * #16): compiles a pack through the same build cache `./pack-export.ts`
+ * uses and zips its distributable form (`pack.json`, `webview.js`,
+ * `webview.css` when built, `scripts/*.lua`) into a single `.mkp` file's
+ * bytes, named per `@markii/pack`'s `packArchiveFileName`. VS Code is the
+ * authoring host and owns pack packaging; this module composes through
+ * `./pack-export.ts`'s `PackExportBuilder` and `PackExportFs` types rather
+ * than duplicating the compile step.
+ *
+ * Uses `fflate`'s `zipSync`, already a runtime dependency of this package
+ * (`packages/markii-host/package.json`; `@markii/bundle`'s own zip reader
+ * is built on the same library), so this adds no new dependency. The
+ * result is a PLAIN zip at the archive root, not a `@markii/bundle`
+ * bundle: a `.mkp` carries no `manifest.json`/bundle semantics of its own,
+ * just the flat layout `@markii/pack`'s `openPackArchive` reads back.
+ *
+ * The pack's own source folder is never written to, exactly like
+ * `exportPack`. This function never writes anywhere at all: it only reads
+ * (the pack's own `pack.json`, the build output, the `scripts/` folder)
+ * and returns bytes; a caller's `vscode`-specific wiring decides where the
+ * user wants the `.mkp` saved and whether to confirm an overwrite there.
+ */
+import * as path from 'node:path';
+import { zipSync } from 'fflate';
+import { packArchiveFileName } from '@markii/pack';
+import { PREBUILT_TERMINAL_SCRIPT_FILENAME, emptyWebviewScript, } from '@markii/host';
+const MANIFEST_FILENAME = 'pack.json';
+const SCRIPT_FILENAME = 'webview.js';
+const STYLESHEET_FILENAME = 'webview.css';
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function packNameOf(pack) {
+    return pack.manifest.name;
+}
+/**
+ * NEVER throws: every failure (an unreadable `pack.json`, a build failure,
+ * an unreadable built script) comes back as `{ kind: 'failed', reason }`,
+ * matching `exportPack`'s contract. There is no overwrite confirmation
+ * here, unlike `exportPack`: nothing is written to any path by this
+ * function, so "does the destination already have a file" is entirely the
+ * caller's concern once it knows where the user wants the `.mkp` saved.
+ */
+export async function exportPackArchive(options) {
+    const { pack, cacheDir, build, buildTerminal, fs } = options;
+    const packName = packNameOf(pack);
+    let manifestText;
+    try {
+        manifestText = await fs.readFile(path.join(pack.folder, MANIFEST_FILENAME));
+    }
+    catch (err) {
+        return { kind: 'failed', packName, reason: describeThrown(err) };
+    }
+    if (manifestText === undefined) {
+        return {
+            kind: 'failed',
+            packName,
+            reason: `pack.json for pack "${packName}" could not be read`,
+        };
+    }
+    let outcome;
+    try {
+        outcome = await build(pack, cacheDir);
+    }
+    catch (err) {
+        return { kind: 'failed', packName, reason: describeThrown(err) };
+    }
+    if (outcome.kind === 'failed') {
+        // Verbatim: the reason's one home is the caller's own diagnostics
+        // module, matching `exportPack`'s identical posture.
+        return { kind: 'failed', packName, reason: outcome.reason };
+    }
+    let terminalText;
+    const hasTerminalSources = Object.keys(pack.componentPathsByEngine?.['ansi'] ?? {}).length > 0;
+    if (buildTerminal !== undefined && hasTerminalSources) {
+        let terminalOutcome;
+        try {
+            terminalOutcome = await buildTerminal(pack, cacheDir);
+        }
+        catch (err) {
+            return { kind: 'failed', packName, reason: describeThrown(err) };
+        }
+        if (terminalOutcome.kind === 'failed') {
+            return {
+                kind: 'failed',
+                packName,
+                reason: `terminal build: ${terminalOutcome.reason}`,
+            };
+        }
+        if (terminalOutcome.kind === 'built') {
+            try {
+                terminalText = await fs.readFile(terminalOutcome.scriptPath);
+            }
+            catch {
+                terminalText = undefined;
+            }
+            if (terminalText === undefined) {
+                return {
+                    kind: 'failed',
+                    packName,
+                    reason: `built terminal script for pack "${packName}" could not be read back`,
+                };
+            }
+        }
+    }
+    let scriptText;
+    if (outcome.kind === 'skipped') {
+        if (terminalText === undefined) {
+            return {
+                kind: 'failed',
+                packName,
+                reason: `pack "${packName}" was not built`,
+            };
+        }
+        scriptText = emptyWebviewScript(JSON.stringify(pack.manifest));
+    }
+    else {
+        try {
+            scriptText = await fs.readFile(outcome.scriptPath);
+        }
+        catch (err) {
+            return { kind: 'failed', packName, reason: describeThrown(err) };
+        }
+        if (scriptText === undefined) {
+            return {
+                kind: 'failed',
+                packName,
+                reason: `built script for pack "${packName}" could not be read back`,
+            };
+        }
+    }
+    let stylesheetText;
+    if (outcome.kind === 'built' && outcome.stylesheetPath !== undefined) {
+        try {
+            stylesheetText = await fs.readFile(outcome.stylesheetPath);
+        }
+        catch {
+            // A read failure here is treated as "no stylesheet" rather than
+            // failing the whole export, matching `exportPack`.
+            stylesheetText = undefined;
+        }
+    }
+    let scriptEntries = [];
+    try {
+        scriptEntries = await fs.listDirectory(pack.scriptsDir);
+    }
+    catch {
+        scriptEntries = [];
+    }
+    const luaFilenames = scriptEntries.filter((name) => name.endsWith('.lua'));
+    const luaFiles = [];
+    for (const filename of luaFilenames) {
+        let text;
+        try {
+            text = await fs.readFile(path.join(pack.scriptsDir, filename));
+        }
+        catch {
+            text = undefined;
+        }
+        if (text === undefined)
+            continue; // unreadable individual file: quietly skipped
+        luaFiles.push({ name: filename, text });
+    }
+    const encoder = new TextEncoder();
+    const zipInput = {
+        [MANIFEST_FILENAME]: encoder.encode(manifestText),
+        [SCRIPT_FILENAME]: encoder.encode(scriptText),
+    };
+    const scriptBytes = zipInput[SCRIPT_FILENAME].byteLength;
+    let terminalScriptBytes;
+    if (terminalText !== undefined) {
+        const encoded = encoder.encode(terminalText);
+        zipInput[PREBUILT_TERMINAL_SCRIPT_FILENAME] = encoded;
+        terminalScriptBytes = encoded.byteLength;
+    }
+    let stylesheetBytes;
+    if (stylesheetText !== undefined) {
+        const encoded = encoder.encode(stylesheetText);
+        zipInput[STYLESHEET_FILENAME] = encoded;
+        stylesheetBytes = encoded.byteLength;
+    }
+    for (const file of luaFiles) {
+        zipInput[`scripts/${file.name}`] = encoder.encode(file.text);
+    }
+    const bytes = zipSync(zipInput);
+    return {
+        kind: 'built',
+        packName,
+        fileName: packArchiveFileName(pack.manifest),
+        bytes,
+        scriptBytes,
+        ...(terminalScriptBytes !== undefined ? { terminalScriptBytes } : {}),
+        ...(stylesheetBytes !== undefined ? { stylesheetBytes } : {}),
+        scriptFilesCopied: luaFiles.length,
+        warnings: outcome.kind === 'built' ? outcome.warnings : [],
+    };
+}

package/dist/pack-export.d.ts

@@ -0,0 +1,94 @@
+import type { DiscoveredPack } from '@markii/host';
+import type { PackBuildOutcome } from './pack-build.js';
+/**
+ * The filesystem seam, injected so this module is testable with in-memory
+ * fakes. `exists`/`readFile`/`listDirectory` never throw (an unreadable or
+ * missing path resolves the "absent" value); `writeFile`/`deleteFile`/
+ * `makeDirectory` may reject, and `exportPack` wraps every call to them
+ * itself, turning a rejection into a `'failed'` outcome rather than
+ * throwing.
+ */
+export interface PackExportFs {
+    readonly exists: (absolutePath: string) => Promise<boolean>;
+    readonly readFile: (absolutePath: string) => Promise<string | undefined>;
+    readonly writeFile: (absolutePath: string, text: string) => Promise<void>;
+    readonly deleteFile: (absolutePath: string) => Promise<void>;
+    /** Creates a directory (and any missing parents), or resolves if it already exists. May reject on a genuine I/O failure. */
+    readonly makeDirectory: (absolutePath: string) => Promise<void>;
+    /** Lists the plain file names directly inside a directory (no recursion), or `[]` when the directory does not exist / cannot be read. Never rejects. */
+    readonly listDirectory: (absolutePath: string) => Promise<readonly string[]>;
+}
+/** Asked once before overwriting artifacts that already exist in the destination folder. Resolves true to proceed. */
+export type ConfirmPackOverwrite = (request: {
+    readonly packName: string;
+    readonly existingPaths: readonly string[];
+}) => Promise<boolean>;
+export type PackExportBuilder = (pack: DiscoveredPack, cacheDir: string) => Promise<PackBuildOutcome>;
+export interface ExportPackOptions {
+    readonly pack: DiscoveredPack;
+    /** The host-owned build cache directory, unchanged: the build still runs through the normal cache, only its OUTPUT is copied into the export folder. */
+    readonly cacheDir: string;
+    /** The PARENT directory the user chose to export into. */
+    readonly destinationDir: string;
+    /** The folder name to create inside `destinationDir` — a host defaults this to the pack's own name, but it is user-editable, so it is validated exactly like every other path segment (see `resolveExportTarget`). */
+    readonly exportName: string;
+    readonly build: PackExportBuilder;
+    /** Builds the terminal script; when given and the pack names `ansi` sources, `terminal.js` is written beside `webview.js`. */
+    readonly buildTerminal?: PackExportBuilder;
+    readonly fs: PackExportFs;
+    readonly confirmOverwrite: ConfirmPackOverwrite;
+}
+export type PackExportOutcome = {
+    readonly kind: 'written';
+    readonly packName: string;
+    /** Absolute path to the exported folder (`destinationDir`/`exportName`). */
+    readonly destinationFolder: string;
+    readonly manifestPath: string;
+    readonly manifestBytes: number;
+    readonly scriptPath: string;
+    readonly scriptBytes: number;
+    readonly terminalScriptPath?: string;
+    readonly terminalScriptBytes?: number;
+    readonly stylesheetPath?: string;
+    readonly stylesheetBytes?: number;
+    /** Set when a stale webview.css from an earlier export was removed because this build emitted no stylesheet. */
+    readonly removedStylesheetPath?: string;
+    /** How many `*.lua` files were copied from the pack's `scripts/` directory. 0 when the pack has no `scripts/` directory or it holds no `.lua` files. */
+    readonly scriptFilesCopied: number;
+    /** The build's pack-CSS lint warnings, passed through unchanged. */
+    readonly warnings: readonly string[];
+} | {
+    readonly kind: 'cancelled';
+    readonly packName: string;
+} | {
+    readonly kind: 'failed';
+    readonly packName: string;
+    readonly reason: string;
+};
+/**
+ * Path jail. Joins `segments` onto `root`, or `undefined` when any segment
+ * is not a plain path segment (empty, `.`, `..`, containing `/` or `\`, or
+ * absolute) or the resolved join would land outside `root`. This is the
+ * ONLY function `exportPack` uses to compute a write target: nothing is
+ * ever written to a path this function did not itself derive. The
+ * caller-supplied `exportName` goes through this exact same validation as
+ * every other segment — an `exportName` carrying a separator, `..`, or an
+ * absolute path is refused here, before anything is written.
+ */
+export declare function resolveExportTarget(root: string, ...segments: readonly string[]): string | undefined;
+/**
+ * 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.
+ *
+ * Order of operations: resolve the destination folder and every write
+ * target inside it (path-jailed against `destinationDir`, including the
+ * user-supplied `exportName` itself); run the build through the normal
+ * cache; read `pack.json` and the built script (and stylesheet, when the
+ * build produced one) back as text; list the pack's `scripts/` directory
+ * for `.lua` files; ask `confirmOverwrite` once, only if the destination
+ * folder already holds files this export would replace; then create the
+ * destination folder and write everything.
+ */
+export declare function exportPack(options: ExportPackOptions): Promise<PackExportOutcome>;