@markii/pack-build 0.0.0-stage → 0.17.0-next.2

package/dist/pack-export.js

@@ -0,0 +1,335 @@
+/**
+ * The internal compose-and-write path pack packaging builds on (VS Code is
+ * the AUTHORING host and owns pack packaging; Obsidian only ever CONSUMES a
+ * pack another host produced). Compiles a pack with the existing
+ * `./pack-build.ts` machinery, through its normal host-owned cache, exactly
+ * like an ordinary preview build; only its OUTPUT is copied. Then writes a
+ * clean, distributable folder at a CALLER-CHOSEN destination: `pack.json`
+ * (copied verbatim from the pack's own folder), `webview.js`,
+ * `webview.css` when the build emitted one, and every `*.lua` file the
+ * pack's own `scripts/` directory holds.
+ *
+ * The pack's SOURCE folder is NEVER written to. Two callers compose
+ * through this module: `apps/vscode/src/packs/build-bundled-packs.ts`
+ * writes a pack's build output into the extension's own `dist/packs` at
+ * build time, and `./pack-export-archive.ts` reuses its `PackExportBuilder`
+ * and `PackExportFs` types to build the ONE shape the "Markii: Export
+ * Pack" command itself produces, a single `.mkp` archive.
+ *
+ * Filesystem access is injected (`PackExportFs`), matching every other
+ * module in this directory, so this module is testable with in-memory
+ * fakes and carries no host-specific save-dialog/notification behavior of
+ * its own; `confirmOverwrite` is the one piece of user interaction, and it
+ * is injected too.
+ */
+import * as path from 'node:path';
+import { PREBUILT_SCRIPT_FILENAME, PREBUILT_STYLESHEET_FILENAME, PREBUILT_TERMINAL_SCRIPT_FILENAME, emptyWebviewScript, } from '@markii/host';
+const MANIFEST_FILENAME = 'pack.json';
+const SCRIPTS_DIRNAME = 'scripts';
+/**
+ * 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 function resolveExportTarget(root, ...segments) {
+    if (segments.length === 0)
+        return undefined;
+    for (const segment of segments) {
+        if (segment.length === 0)
+            return undefined;
+        if (segment === '.' || segment === '..')
+            return undefined;
+        if (segment.includes('/') || segment.includes('\\'))
+            return undefined;
+        if (path.isAbsolute(segment))
+            return undefined;
+    }
+    const resolvedRoot = path.resolve(root);
+    const target = path.resolve(resolvedRoot, ...segments);
+    if (target !== resolvedRoot && !target.startsWith(resolvedRoot + path.sep)) {
+        return undefined;
+    }
+    return target;
+}
+function describeThrown(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** `manifest.name` unless empty/whitespace, in which case a placeholder that still reads sensibly in a failure message. */
+function packNameOf(pack) {
+    return pack.manifest.name;
+}
+/**
+ * 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 async function exportPack(options) {
+    const { pack, cacheDir, destinationDir, exportName, build, buildTerminal, fs, confirmOverwrite, } = options;
+    const packName = packNameOf(pack);
+    const destinationFolder = resolveExportTarget(destinationDir, exportName);
+    if (destinationFolder === undefined) {
+        return {
+            kind: 'failed',
+            packName,
+            reason: `"${exportName}" is not a valid export folder name`,
+        };
+    }
+    const manifestTarget = resolveExportTarget(destinationFolder, MANIFEST_FILENAME);
+    const scriptTarget = resolveExportTarget(destinationFolder, PREBUILT_SCRIPT_FILENAME);
+    const stylesheetTarget = resolveExportTarget(destinationFolder, PREBUILT_STYLESHEET_FILENAME);
+    const terminalTarget = resolveExportTarget(destinationFolder, PREBUILT_TERMINAL_SCRIPT_FILENAME);
+    const scriptsDirTarget = resolveExportTarget(destinationFolder, SCRIPTS_DIRNAME);
+    if (manifestTarget === undefined ||
+        scriptTarget === undefined ||
+        stylesheetTarget === undefined ||
+        terminalTarget === undefined ||
+        scriptsDirTarget === undefined) {
+        return {
+            kind: 'failed',
+            packName,
+            reason: `could not resolve a safe write location inside "${destinationFolder}"`,
+        };
+    }
+    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: a host-specific build-failure reason arrives through here,
+        // and its single home is that app's own diagnostics module — never
+        // reworded on this path.
+        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 {
+            stylesheetText = undefined;
+        }
+        // A read failure here is treated as "no stylesheet" rather than failing
+        // the whole export — the script alone is still a usable pack.
+    }
+    // The pack's own scripts/ directory, copied through verbatim. Absent or
+    // unreadable simply yields no script files, matching every other
+    // filesystem-adjacent module in this directory's "quiet skip" posture for
+    // an individually unreadable entry.
+    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) {
+        const target = resolveExportTarget(scriptsDirTarget, filename);
+        if (target === undefined)
+            continue; // an unsafe entry name is skipped, not fatal
+        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({ target, text });
+    }
+    let destinationExists;
+    try {
+        destinationExists = await fs.exists(destinationFolder);
+    }
+    catch (err) {
+        return { kind: 'failed', packName, reason: describeThrown(err) };
+    }
+    const existingPaths = [];
+    if (destinationExists) {
+        const candidates = [
+            manifestTarget,
+            scriptTarget,
+            ...(terminalText !== undefined ? [terminalTarget] : []),
+            ...(stylesheetText !== undefined ? [stylesheetTarget] : []),
+            ...luaFiles.map((file) => file.target),
+        ];
+        try {
+            for (const candidate of candidates) {
+                if (await fs.exists(candidate)) {
+                    existingPaths.push(candidate);
+                }
+            }
+            // A stale webview.css this export would remove (see below) also
+            // counts as "a file this export would replace".
+            if (stylesheetText === undefined && (await fs.exists(stylesheetTarget))) {
+                existingPaths.push(stylesheetTarget);
+            }
+            if (terminalText === undefined && (await fs.exists(terminalTarget))) {
+                existingPaths.push(terminalTarget);
+            }
+        }
+        catch (err) {
+            return { kind: 'failed', packName, reason: describeThrown(err) };
+        }
+    }
+    if (existingPaths.length > 0) {
+        let proceed;
+        try {
+            proceed = await confirmOverwrite({ packName, existingPaths });
+        }
+        catch (err) {
+            return { kind: 'failed', packName, reason: describeThrown(err) };
+        }
+        if (!proceed) {
+            return { kind: 'cancelled', packName };
+        }
+    }
+    try {
+        await fs.makeDirectory(destinationFolder);
+        await fs.writeFile(manifestTarget, manifestText);
+        await fs.writeFile(scriptTarget, scriptText);
+        if (terminalText !== undefined) {
+            await fs.writeFile(terminalTarget, terminalText);
+        }
+        else if (await fs.exists(terminalTarget)) {
+            // A stale terminal.js from an earlier export would otherwise keep
+            // rendering views this build no longer has.
+            await fs.deleteFile(terminalTarget);
+        }
+        let stylesheetBytes;
+        let removedStylesheetPath;
+        if (stylesheetText !== undefined) {
+            await fs.writeFile(stylesheetTarget, stylesheetText);
+            stylesheetBytes = Buffer.byteLength(stylesheetText, 'utf8');
+        }
+        else if (await fs.exists(stylesheetTarget)) {
+            // A stale webview.css from an earlier export would otherwise keep
+            // styling the pack even though this build produced none.
+            await fs.deleteFile(stylesheetTarget);
+            removedStylesheetPath = stylesheetTarget;
+        }
+        if (luaFiles.length > 0) {
+            await fs.makeDirectory(scriptsDirTarget);
+            for (const file of luaFiles) {
+                await fs.writeFile(file.target, file.text);
+            }
+        }
+        return {
+            kind: 'written',
+            packName,
+            destinationFolder,
+            manifestPath: manifestTarget,
+            manifestBytes: Buffer.byteLength(manifestText, 'utf8'),
+            scriptPath: scriptTarget,
+            scriptBytes: Buffer.byteLength(scriptText, 'utf8'),
+            ...(terminalText !== undefined
+                ? {
+                    terminalScriptPath: terminalTarget,
+                    terminalScriptBytes: Buffer.byteLength(terminalText, 'utf8'),
+                }
+                : {}),
+            ...(stylesheetText !== undefined
+                ? { stylesheetPath: stylesheetTarget, stylesheetBytes }
+                : {}),
+            ...(removedStylesheetPath !== undefined ? { removedStylesheetPath } : {}),
+            scriptFilesCopied: luaFiles.length,
+            warnings: outcome.kind === 'built' ? outcome.warnings : [],
+        };
+    }
+    catch (err) {
+        return { kind: 'failed', packName, reason: describeThrown(err) };
+    }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@markii/pack-build",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.17.0-next.2",
+  "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",
+    "mk.md",
+    "markii",
+    "pack",
+    "esbuild"
+  ],
+  "license": "MIT",
+  "author": "sadigaxund",
+  "homepage": "https://github.com/markii-org/markii#readme",
+  "bugs": "https://github.com/markii-org/markii/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markii-org/markii.git",
+    "directory": "packages/markii-pack-build"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint .",
+    "build:dist": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@markii/host": "^0.17.0-next.2",
+    "@markii/pack": "^0.17.0-next.2",
+    "esbuild-wasm": "^0.28.2",
+    "fflate": "^0.8.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}