@webflow/cloud-app 0.1.0-beta.10

package/dist/pipeline.js

@@ -0,0 +1,293 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyAssets = copyAssets;
+exports.buildApp = buildApp;
+/**
+ * The build pipeline — the orchestration extracted from cosmic.ts::cosmicBuild,
+ * minus everything host-specific (source fetch, telemetry spans, upload, queue,
+ * DB). It operates on an **ephemeral workspace**: the project is copied to a
+ * temp dir, all mutation + the build happen there, and the worker-ready output
+ * is collected into `outputDir` — the user's source tree is never touched.
+ *
+ * Steps: isolate → detect → validate/install → wrangler synthesis →
+ * prepareConfig → createWebflowJson → npm install → build → postBuild →
+ * wrangler dry-run → collect output.
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const ports_1 = require("./ports");
+const package_json_1 = require("./config/package-json");
+const assert_adapter_nested_under_mount_1 = require("./frameworks/astro/adapter-patches/assert-adapter-nested-under-mount");
+const webflow_json_1 = require("./config/webflow-json");
+const registry_1 = require("./frameworks/registry");
+const errors_1 = require("./frameworks/errors");
+const utils_1 = require("./utils");
+const wrangler_1 = require("./wrangler");
+const compat_date_1 = require("./compat-date");
+const create_webflow_json_1 = require("./create-webflow-json");
+const static_base_href_1 = require("./static-base-href");
+/** Top-level entries never copied into the build workspace. */
+const ISOLATE_EXCLUDE = new Set(['node_modules', '.git']);
+/**
+ * Copy the user's project into a fresh workspace, skipping node_modules/.git
+ * (deps are reinstalled in the workspace). Leaves the source tree pristine.
+ */
+function isolateWorkspace(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.cpSync(src, dest, {
+        recursive: true,
+        filter: (from) => !ISOLATE_EXCLUDE.has(path.basename(from)),
+    });
+}
+/**
+ * URL prefix under which static assets are served. Prefers an explicit
+ * `cloud.assets_path_prefix` in webflow.json, else the mount path, else '/'.
+ */
+function assetPathPrefix(webflowJson, mountPath) {
+    return webflowJson?.cloud?.assets_path_prefix || mountPath || '/';
+}
+/** Copy framework build assets into `out/assets<prefix>`, mount-path aware. */
+function copyAssets(ctx, frameworkName, output, cwd, out, webflowJson) {
+    const { log, mountPath = '/' } = ctx;
+    const mirrorsUrlLayout = output.staticAssetsMirrorUrlLayout === true;
+    if (mirrorsUrlLayout) {
+        // Astro 6/7: the HTML references deployUrl + mountPath, so any other prefix would break the
+        // asset URLs. The copy goes to the assets root and the adapter's own nesting carries the mount.
+        const configured = webflowJson?.cloud?.assets_path_prefix;
+        const trim = (p) => p.replace(/^\/+|\/+$/g, '');
+        if (configured && trim(configured) !== trim(mountPath)) {
+            log.warn(`assets_path_prefix "${configured}" is ignored for ${frameworkName}: static assets are ` +
+                `copied as built and served under the mount path "${mountPath}"`);
+        }
+    }
+    const prefix = mirrorsUrlLayout ? '/' : assetPathPrefix(webflowJson, mountPath);
+    fs.mkdirSync(path.join(out, `assets${prefix}`), { recursive: true });
+    let assetsPath = output.staticAssetsPath;
+    if (!assetsPath) {
+        log.info('no assets to copy (framework does not define a static assets path)');
+        return;
+    }
+    // Mount-path-aware source resolution for Next.js / Astro. The destination below re-appends the
+    // mount (`assets<prefix>`) for everything except the Astro 6/7 verbatim copy, so the source must
+    // end up nested under the mount exactly once.
+    if (frameworkName === 'nextjs' || frameworkName === 'astro') {
+        let cleanMountPath = mountPath;
+        while (cleanMountPath && cleanMountPath[0] === '/')
+            cleanMountPath = cleanMountPath.slice(1);
+        while (cleanMountPath && cleanMountPath.slice(-1) === '/')
+            cleanMountPath = cleanMountPath.slice(0, -1);
+        if (cleanMountPath && cleanMountPath.length > 0) {
+            if (mirrorsUrlLayout) {
+                // Astro 6/7: a fixed @astrojs/cloudflare adapter (base = mountPath) already nests the
+                // client tree under `<assetsPath>/<mount>/`, so copy `assetsPath` verbatim. Fail loudly
+                // on the flat layout a buggy adapter emits rather than publish it at the wrong URLs.
+                (0, assert_adapter_nested_under_mount_1.assertAdapterNestedUnderMount)(cwd, assetsPath, cleanMountPath);
+            }
+            else {
+                // Astro 5 / Next.js: the build nests assets under the mount-path subdirectory.
+                assetsPath = path.join(assetsPath, cleanMountPath);
+            }
+        }
+        log.debug(`computed asset path ${assetsPath} for ${frameworkName} (mount path ${mountPath})`);
+    }
+    const stat = fs.statSync(path.join(cwd, assetsPath), { throwIfNoEntry: false });
+    if (!stat || !stat.isDirectory()) {
+        log.info(`no assets to copy (${path.join(cwd, assetsPath)} not a directory)`);
+        return;
+    }
+    const count = (0, utils_1.recursiveCopy)(log, path.join(cwd, assetsPath), path.join(out, `assets${prefix}`), {
+        exclude: output.staticAssetsExclude?.[0],
+    });
+    log.info(`copied ${count} asset${count === 1 ? '' : 's'}`);
+    // Static apps ship hand-written HTML with relative asset URLs. Served under a
+    // mount path those resolve against the request URL (/mount → /styles.css, a
+    // 404) instead of the asset location. Inject a document-relative <base> so
+    // relative URLs resolve correctly at any depth. Framework apps bake the mount
+    // into their own URLs, so this is static-only. (No-op at the root mount.)
+    if (frameworkName === 'static') {
+        const changed = (0, static_base_href_1.injectBaseHrefIntoTree)(log, path.join(out, `assets${prefix}`), prefix);
+        if (changed > 0) {
+            log.info(`injected <base> into ${changed} HTML file${changed === 1 ? '' : 's'}`);
+        }
+    }
+}
+/**
+ * Assemble the deploy-ready output directory: static assets, the
+ * contract-validated webflow.json, and the `clouduser.wrangler.json` bridge +
+ * D1 migrations the deployer consumes. The worker bundle was already written
+ * here by `wrangler deploy --dry-run --outdir`.
+ */
+function collectOutput(ctx, frameworkName, output, cwd, out) {
+    const { log } = ctx;
+    const webflowJson = (0, webflow_json_1.loadWebflowJson)(log, cwd);
+    copyAssets(ctx, frameworkName, output, cwd, out, webflowJson);
+    if (webflowJson) {
+        fs.writeFileSync(path.join(out, 'webflow.json'), JSON.stringify(webflowJson));
+    }
+    // The date the build settled on, for the deploy to apply (see compat-date.ts).
+    if (fs.statSync(path.join(cwd, compat_date_1.COMPAT_DATE_RECORD_FILE), { throwIfNoEntry: false })) {
+        fs.copyFileSync(path.join(cwd, compat_date_1.COMPAT_DATE_RECORD_FILE), path.join(out, compat_date_1.COMPAT_DATE_RECORD_FILE));
+    }
+    // Ship clouduser.wrangler.json (user bindings + migrations) for the deployer.
+    // The framework-written wrangler.json is intentionally NOT shipped — the
+    // deployer regenerates it.
+    if (fs.statSync(path.join(cwd, 'clouduser.wrangler.json'), { throwIfNoEntry: false })) {
+        fs.copyFileSync(path.join(cwd, 'clouduser.wrangler.json'), path.join(out, 'clouduser.wrangler.json'));
+        const count = (0, utils_1.recursiveCopy)(log, path.join(cwd, 'clouduser', 'migrations'), path.join(out, 'migrations'));
+        log.info(`copied ${count} migration${count === 1 ? '' : 's'} to output`);
+    }
+}
+/**
+ * Build a project into a Webflow Cloud bundle. See module docs for the step
+ * sequence. Returns the detected framework, deployment type, bundled entry
+ * path, the emitted webflow.json, and the populated `outputDir`.
+ */
+async function buildApp(options) {
+    const { projectDir, outputDir } = options;
+    const log = options.ports.logger;
+    const runCommand = options.ports.runCommand;
+    const telemetry = options.ports.telemetry ?? ports_1.noopTelemetry;
+    const fsPort = options.ports.fs ?? ports_1.nodeFileSystem;
+    const mountPath = options.mountPath ?? '/';
+    const deployUrl = options.deployUrl ?? '';
+    // 1. Isolate into an ephemeral workspace so the source tree stays pristine.
+    const workspaceDir = options.workspaceDir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'webflow-app-build-'));
+    log.info(`isolating project into ephemeral workspace: ${workspaceDir}`);
+    isolateWorkspace(projectDir, workspaceDir);
+    // 2. Load package.json + (optional) webflow.json from the workspace.
+    const packageJson = (0, package_json_1.loadPackageJson)(workspaceDir);
+    if (!packageJson) {
+        throw new errors_1.FrameworkDetectionError(`could not find package.json in ${projectDir}`, {
+            remediation: 'Run a build from a project directory that contains a package.json.',
+        });
+    }
+    const webflowJson = (0, webflow_json_1.loadWebflowJson)(log, workspaceDir);
+    if (webflowJson?.cloud?.framework) {
+        (0, registry_1.validateFrameworkName)(webflowJson.cloud.framework);
+        log.info(`Framework specified in webflow.json: ${webflowJson.cloud.framework}`);
+    }
+    // Env made available to template substitution and the build command.
+    const userEnv = {
+        ...options.env,
+        COSMIC_MOUNT_PATH: mountPath,
+        COSMIC_DEPLOY_URL: deployUrl,
+    };
+    // 3. Detect the framework and build it up.
+    const ctx = {
+        cwd: workspaceDir,
+        log,
+        runCommand,
+        telemetry,
+        fs: fsPort,
+        packageJson,
+        userEnv,
+        mountPath,
+        deployUrl,
+    };
+    const builder = (0, registry_1.detectAndCreateBuilder)(ctx, webflowJson);
+    const frameworkName = builder.info.name;
+    log.info(`Building with ${builder.info.displayName}`);
+    const span = telemetry.startSpan('buildApp', { framework: frameworkName });
+    try {
+        // 4. Validate + install framework deps.
+        const nodeReq = builder.getNodeVersionRequirement();
+        if (nodeReq) {
+            (0, utils_1.validateNodeVersion)(log, nodeReq, builder.info.displayName);
+        }
+        await builder.validate();
+        await builder.installDependencies();
+        // 5. Wrangler synthesis (sole writer of wrangler.json), then framework config.
+        (0, wrangler_1.handleWranglerJson)(log, builder, workspaceDir, {
+            compatDatePolicy: options.compatDatePolicy,
+        });
+        await builder.prepareConfig();
+        // 6. Emit the contract-validated webflow.json (producer self-check inside).
+        (0, create_webflow_json_1.createWebflowJson)(log, workspaceDir, frameworkName, builder);
+        // 7. Fresh dependency install.
+        const verb = fs.existsSync(path.join(workspaceDir, 'package-lock.json'))
+            ? 'clean-install'
+            : 'install';
+        log.info(`running npm ${verb}...`);
+        await (0, utils_1.npm)({ log, runCommand, cwd: workspaceDir, args: [verb, '--include=dev'] });
+        // 8. Run the framework build (bypasses the user's package.json build script).
+        // A null build command means a no-framework static app. buildApp does not
+        // yet implement the assets-only path (asset-root relocation, no worker), so
+        // reject it here rather than silently mis-building — hosts that support
+        // static (cosmic-builder) drive the builders directly.
+        const buildCommand = builder.getBuildCommand();
+        if (buildCommand === null) {
+            throw new errors_1.FrameworkDetectionError('No-framework static apps are not yet supported by buildApp.', { remediation: 'Use a host that implements the static assets-only path.' });
+        }
+        log.info(`building using ${buildCommand}...`);
+        await (0, utils_1.npm)({
+            log,
+            runCommand,
+            cwd: workspaceDir,
+            env: userEnv,
+            args: ['exec', '-c', buildCommand],
+        }).catch((e) => {
+            throw new Error(`${frameworkName} build failed`, { cause: e });
+        });
+        await builder.postBuild();
+        // 9. Bundle the worker entry + verify bindings via wrangler dry-run.
+        fs.mkdirSync(outputDir, { recursive: true });
+        log.info('creating wrangler dry-run...');
+        await (0, utils_1.npm)({
+            log,
+            runCommand,
+            cwd: workspaceDir,
+            args: ['exec', '--', 'wrangler', 'deploy', '--dry-run', `--outdir=${outputDir}`],
+        });
+        // 10. Collect assets + webflow.json + clouduser bridge into the output dir.
+        const output = builder.getOutputDeployMetadata();
+        collectOutput(ctx, frameworkName, output, workspaceDir, outputDir);
+        const finalWebflowJson = JSON.parse(fs.readFileSync(path.join(outputDir, 'webflow.json'), 'utf8'));
+        span.end();
+        return {
+            framework: frameworkName,
+            deploymentType: output.deploymentType,
+            entrypointPath: output.dryRunEntryPath ?? './index.js',
+            webflowJson: finalWebflowJson,
+            outputDir,
+        };
+    }
+    catch (e) {
+        span.end(e);
+        throw e;
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/ports/command-runner.d.ts

@@ -0,0 +1,59 @@
+export interface RunCommandOptions {
+    /** Working directory for the command (defaults to the host process cwd). */
+    cwd?: string;
+    /**
+     * Environment variables. When set, replaces the inherited environment at the
+     * spawn boundary — the host owns environment policy. Callers that want the
+     * host environment preserved (registry auth, proxies, custom CAs, npm config)
+     * should merge `process.env` in before passing it; the {@link npm} helper does
+     * this by default.
+     */
+    env?: Record<string, string>;
+    /** Stream output as it arrives, e.g. to forward into the host's logger. */
+    onOutput?: (chunk: string, stream: 'stdout' | 'stderr') => void;
+}
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    /**
+     * Set when the process was terminated by a signal (e.g. `SIGKILL` from an OOM
+     * kill, `SIGTERM` from a timeout). Signal termination is always a failure.
+     */
+    signal?: NodeJS.Signals;
+}
+export interface CommandRunner {
+    /**
+     * Run `command` with `args`. Implementations SHOULD reject with a
+     * {@link CommandError} on a non-zero exit so callers can treat failures as
+     * exceptions.
+     */
+    run(command: string, args: string[], options?: RunCommandOptions): Promise<CommandResult>;
+}
+/** Thrown by the default runner when a command exits non-zero or is signalled. */
+export declare class CommandError extends Error {
+    readonly command: string;
+    readonly args: string[];
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly signal?: NodeJS.Signals;
+    constructor(command: string, args: string[], result: CommandResult);
+}
+/**
+ * Resolve a command to the form `spawn(..., { shell: false })` can launch on
+ * Windows. Keeping `shell: false` preserves argument boundaries — unlike
+ * `shell: true`, where a multi-word arg like a build command would be re-split
+ * by the shell. Only the known {@link WINDOWS_CMD_SHIMS} are rewritten to
+ * `.cmd`; everything else (native executables, already path- or
+ * extension-qualified commands) is returned unchanged. No-op off Windows.
+ */
+export declare function resolveExecutable(command: string): string;
+/**
+ * Default runner backed by `child_process.spawn`. Streams output in full via
+ * `onOutput`, retains a bounded tail for diagnostics, and rejects with
+ * {@link CommandError} on a non-zero exit OR signal termination. Hosts that need
+ * sandboxing or a curated environment supply their own implementation instead.
+ */
+export declare const nodeCommandRunner: CommandRunner;
+//# sourceMappingURL=command-runner.d.ts.map

package/dist/ports/command-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-runner.d.ts","sourceRoot":"","sources":["../../src/ports/command-runner.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,KAAK,IAAI,CAAC;CACjE;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CACzB;AAYD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3F;AAED,kFAAkF;AAClF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,aAAa;CAWnE;AAcD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIzD;AASD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,aA0C/B,CAAC"}

package/dist/ports/command-runner.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeCommandRunner = exports.CommandError = void 0;
+exports.resolveExecutable = resolveExecutable;
+/**
+ * Command-runner port.
+ *
+ * The build pipeline shells out for the heavy lifting (`npm install`, the
+ * framework build, `wrangler deploy --dry-run`). It never calls
+ * `child_process` directly — it goes through this port so the host owns *how*
+ * commands run: cosmic-builder runs them inside its ECS task with its own
+ * environment, the CLI runs them locally, and a sandboxed/agent host can
+ * intercept, restrict, or veto them. This is the security seam for a public,
+ * agent-importable package — nothing executes that the host didn't allow.
+ */
+const node_child_process_1 = require("node:child_process");
+/**
+ * Retained-output cap (per stream). Output is still streamed in full via
+ * `onOutput`; only the in-memory `stdout`/`stderr` kept for the result/error is
+ * bounded, so a runaway build can't exhaust memory. The tail is kept (build
+ * failures report their last lines) with a marker prepended once truncation
+ * begins.
+ */
+const MAX_CAPTURED_OUTPUT = 1024 * 1024; // 1 MiB per stream
+const TRUNCATION_MARKER = '…[output truncated]…\n';
+/** Thrown by the default runner when a command exits non-zero or is signalled. */
+class CommandError extends Error {
+    command;
+    args;
+    exitCode;
+    stdout;
+    stderr;
+    signal;
+    constructor(command, args, result) {
+        const reason = result.signal ? `killed by ${result.signal}` : `exit ${result.exitCode}`;
+        super(`Command failed (${reason}): ${command} ${args.join(' ')}`);
+        this.name = 'CommandError';
+        this.command = command;
+        this.args = args;
+        this.exitCode = result.exitCode;
+        this.stdout = result.stdout;
+        this.stderr = result.stderr;
+        this.signal = result.signal;
+    }
+}
+exports.CommandError = CommandError;
+/**
+ * npm-ecosystem launchers this port shells out to (`npm`/`npx`/`wrangler`/
+ * `yarn`/`pnpm`) ship on Windows as `.cmd` shims, which `spawn(..., { shell:
+ * false })` cannot launch by bare name — so they get resolved to their `.cmd`
+ * form. This is deliberately an allowlist, not "every extensionless command":
+ * native executables like `node` are `.exe` on PATH and spawn correctly by
+ * bare name, so appending `.cmd` to them points at a nonexistent file and
+ * fails with `spawn EINVAL` (which is exactly what a bare `node` did before
+ * this was narrowed).
+ */
+const WINDOWS_CMD_SHIMS = new Set(['npm', 'npx', 'wrangler', 'yarn', 'pnpm']);
+/**
+ * Resolve a command to the form `spawn(..., { shell: false })` can launch on
+ * Windows. Keeping `shell: false` preserves argument boundaries — unlike
+ * `shell: true`, where a multi-word arg like a build command would be re-split
+ * by the shell. Only the known {@link WINDOWS_CMD_SHIMS} are rewritten to
+ * `.cmd`; everything else (native executables, already path- or
+ * extension-qualified commands) is returned unchanged. No-op off Windows.
+ */
+function resolveExecutable(command) {
+    if (process.platform !== 'win32')
+        return command;
+    if (/[\\/]/.test(command) || /\.[^.]+$/.test(command))
+        return command;
+    return WINDOWS_CMD_SHIMS.has(command.toLowerCase()) ? `${command}.cmd` : command;
+}
+/** Append `chunk` to `captured`, keeping the tail within {@link MAX_CAPTURED_OUTPUT}. */
+function appendCapped(captured, chunk) {
+    const combined = captured + chunk;
+    if (combined.length <= MAX_CAPTURED_OUTPUT)
+        return combined;
+    return TRUNCATION_MARKER + combined.slice(combined.length - MAX_CAPTURED_OUTPUT);
+}
+/**
+ * Default runner backed by `child_process.spawn`. Streams output in full via
+ * `onOutput`, retains a bounded tail for diagnostics, and rejects with
+ * {@link CommandError} on a non-zero exit OR signal termination. Hosts that need
+ * sandboxing or a curated environment supply their own implementation instead.
+ */
+exports.nodeCommandRunner = {
+    run(command, args, options = {}) {
+        return new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)(resolveExecutable(command), args, {
+                cwd: options.cwd,
+                env: options.env ?? process.env,
+                shell: false,
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout?.on('data', (data) => {
+                const chunk = data.toString();
+                stdout = appendCapped(stdout, chunk);
+                options.onOutput?.(chunk, 'stdout');
+            });
+            child.stderr?.on('data', (data) => {
+                const chunk = data.toString();
+                stderr = appendCapped(stderr, chunk);
+                options.onOutput?.(chunk, 'stderr');
+            });
+            child.on('error', reject);
+            // `close` delivers exactly one of (code, signal). A signal kill (SIGKILL
+            // from OOM, SIGTERM from a timeout) arrives as `code === null` — treat it
+            // as a failure rather than letting `code ?? 0` mask it as success.
+            child.on('close', (code, signal) => {
+                if (code === 0) {
+                    resolve({ stdout, stderr, exitCode: 0 });
+                    return;
+                }
+                const result = {
+                    stdout,
+                    stderr,
+                    exitCode: code ?? 1,
+                    signal: signal ?? undefined,
+                };
+                reject(new CommandError(command, args, result));
+            });
+        });
+    },
+};
+//# sourceMappingURL=command-runner.js.map

package/dist/ports/command-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-runner.js","sourceRoot":"","sources":["../../src/ports/command-runner.ts"],"names":[],"mappings":"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"}

package/dist/ports/filesystem.d.ts

@@ -0,0 +1,19 @@
+export interface FileSystemPort {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    rename(from: string, to: string): Promise<void>;
+    /** Recursively copy `from` to `to`. */
+    copy(from: string, to: string): Promise<void>;
+}
+/** Default filesystem backed by `node:fs/promises`. */
+export declare const nodeFileSystem: FileSystemPort;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/ports/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/ports/filesystem.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,uCAAuC;IACvC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,uDAAuD;AACvD,eAAO,MAAM,cAAc,EAAE,cAmB5B,CAAC"}

package/dist/ports/filesystem.js

@@ -0,0 +1,68 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeFileSystem = void 0;
+/**
+ * Filesystem port.
+ *
+ * The pipeline reads/writes the ephemeral workspace through this port rather
+ * than `node:fs` directly. The node-backed default below is what every
+ * server/CLI host uses; the seam exists so unusual hosts (e.g. a browser-based
+ * agent with a virtual filesystem) can plug in their own, and so tests can
+ * observe filesystem effects without touching disk.
+ */
+const fs = __importStar(require("node:fs/promises"));
+/** Default filesystem backed by `node:fs/promises`. */
+exports.nodeFileSystem = {
+    readFile: (path) => fs.readFile(path, 'utf8'),
+    writeFile: (path, data) => fs.writeFile(path, data, 'utf8'),
+    exists: async (path) => {
+        try {
+            await fs.access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    mkdir: async (path, options) => {
+        await fs.mkdir(path, { recursive: options?.recursive ?? false });
+    },
+    rm: (path, options) => fs.rm(path, { recursive: options?.recursive ?? false, force: options?.force ?? false }),
+    readdir: (path) => fs.readdir(path),
+    rename: (from, to) => fs.rename(from, to),
+    copy: (from, to) => fs.cp(from, to, { recursive: true }),
+};
+//# sourceMappingURL=filesystem.js.map

package/dist/ports/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../src/ports/filesystem.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;GAQG;AACH,qDAAuC;AAcvC,uDAAuD;AAC1C,QAAA,cAAc,GAAmB;IAC5C,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC7C,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC;IAC3D,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAC7B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,KAAK,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CACpB,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,CAAC;IACzF,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;IACzC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;CACzD,CAAC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ports — the injection seam between the build engine and its host.
+ *
+ * Everything environment-specific (logging, command execution, telemetry,
+ * filesystem) is expressed as a port with a safe default. Hosts override what
+ * they need and inherit the rest, so the same engine runs in ECS
+ * (cosmic-builder), locally (CLI), and headless (MCP/agents).
+ */
+export type { Logger } from './logger';
+export { consoleLogger, silentLogger } from './logger';
+export type { CommandRunner, CommandResult, RunCommandOptions } from './command-runner';
+export { nodeCommandRunner, CommandError } from './command-runner';
+export type { Telemetry, Span, TagValue } from './telemetry';
+export { noopTelemetry } from './telemetry';
+export type { FileSystemPort } from './filesystem';
+export { nodeFileSystem } from './filesystem';
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEvD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/ports/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeFileSystem = exports.noopTelemetry = exports.CommandError = exports.nodeCommandRunner = exports.silentLogger = exports.consoleLogger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "consoleLogger", { enumerable: true, get: function () { return logger_1.consoleLogger; } });
+Object.defineProperty(exports, "silentLogger", { enumerable: true, get: function () { return logger_1.silentLogger; } });
+var command_runner_1 = require("./command-runner");
+Object.defineProperty(exports, "nodeCommandRunner", { enumerable: true, get: function () { return command_runner_1.nodeCommandRunner; } });
+Object.defineProperty(exports, "CommandError", { enumerable: true, get: function () { return command_runner_1.CommandError; } });
+var telemetry_1 = require("./telemetry");
+Object.defineProperty(exports, "noopTelemetry", { enumerable: true, get: function () { return telemetry_1.noopTelemetry; } });
+var filesystem_1 = require("./filesystem");
+Object.defineProperty(exports, "nodeFileSystem", { enumerable: true, get: function () { return filesystem_1.nodeFileSystem; } });
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":";;;AASA,mCAAuD;AAA9C,uGAAA,aAAa,OAAA;AAAE,sGAAA,YAAY,OAAA;AAGpC,mDAAmE;AAA1D,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAGxC,yCAA4C;AAAnC,0GAAA,aAAa,OAAA;AAGtB,2CAA8C;AAArC,4GAAA,cAAc,OAAA"}