@svenroth-ai/shipwright 0.24.1-next.0

package/server/dist/core/preview-child-lifecycle.js

@@ -0,0 +1,223 @@
+/*
+ * preview-child-lifecycle.ts — lifecycle mechanics for ONE preview dev-server
+ * child, factored out of preview-session-manager.ts (which sits at its bloat
+ * ceiling). Cohesion: everything about a single child from spawn → ready-probe
+ * → live → death, minus the projectId→entry state map (that stays in the
+ * manager). D20 / audit findings F11 + F12 + F13.
+ *
+ *   - drainStdio  — consume stdout/stderr into a bounded ring so a never-read
+ *     OS pipe buffer (~64KB) can't freeze the previewed dev server mid-session
+ *     (F11), and expose the captured tail as a diagnostic for early-exit /
+ *     timeout errors.
+ *   - treeKill    — terminate the child AND its descendants: win32 `taskkill
+ *     /T /F`, POSIX process-group `kill(-pid)` (the child is spawned `detached`
+ *     so it leads its own group). SIGTERMs npm's grandchildren, not just npm
+ *     (F13).
+ *   - awaitExit   — resolve once the child's `exit` fires (bounded), so a
+ *     profile-change respawn waits for the old child to release its port
+ *     before the new port probe (F13).
+ *   - port / readiness probes — gate a child's transition to "ready"; moved
+ *     here verbatim from the manager to keep it under the bloat ceiling.
+ *
+ * Security posture unchanged (ADR-044): the probes only ever touch 127.0.0.1
+ * and assert the resolved host before fetching; treeKill spawns `taskkill`
+ * with `shell: false` + discrete argv.
+ */
+import { spawn as realSpawn } from "node:child_process";
+import { createServer } from "node:net";
+const DEFAULT_RING_CHARS = 16 * 1024;
+/**
+ * Attach `data` listeners to stdout+stderr so the OS pipe is continuously
+ * drained (prevents the ~64KB pipe-buffer backpressure freeze, F11) while
+ * retaining only a bounded tail for diagnostics. A no-op on the null streams
+ * of a test fake-child.
+ */
+export function drainStdio(child, maxChars = DEFAULT_RING_CHARS) {
+    let buf = "";
+    const append = (chunk) => {
+        buf += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        if (buf.length > maxChars)
+            buf = buf.slice(buf.length - maxChars);
+    };
+    // Decode across chunk boundaries so a multi-byte UTF-8 sequence split by the
+    // pipe isn't mangled into a substitution char in the diagnostic tail.
+    if (child.stdout && typeof child.stdout.setEncoding === "function") {
+        child.stdout.setEncoding("utf8");
+    }
+    if (child.stderr && typeof child.stderr.setEncoding === "function") {
+        child.stderr.setEncoding("utf8");
+    }
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    return { tail: () => buf };
+}
+function safeKill(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // already dead / unkillable — nothing more we can do
+    }
+}
+/**
+ * Terminate a child AND its descendants. win32: `taskkill /T /F` (the
+ * `cmd.exe → npm.cmd → node` chain the D03 win32 spawn creates). POSIX: signal
+ * the whole process group via a negative pid (the child leads its own group
+ * because the manager spawns it `detached`). Falls back to a direct
+ * `child.kill` when no pid is available or the group signal throws.
+ */
+export function treeKill(child, signal = "SIGTERM", deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const pid = typeof child.pid === "number" && child.pid > 0 ? child.pid : null;
+    if (platform === "win32") {
+        if (pid !== null) {
+            const spawnFn = deps.killSpawn ?? realSpawn;
+            try {
+                const killer = spawnFn("taskkill", ["/pid", String(pid), "/t", "/f"], {
+                    stdio: "ignore",
+                    windowsHide: true,
+                    shell: false,
+                });
+                // If taskkill itself can't launch, fall back to the direct child.
+                if (killer && typeof killer.once === "function") {
+                    killer.once("error", () => safeKill(child, signal));
+                }
+                return;
+            }
+            catch {
+                // fall through to the direct kill below
+            }
+        }
+        safeKill(child, signal);
+        return;
+    }
+    if (pid !== null) {
+        const processKill = deps.processKill ?? ((p, s) => void process.kill(p, s));
+        try {
+            processKill(-pid, signal);
+            return;
+        }
+        catch {
+            // group gone, or the child wasn't a group leader — signal it directly
+        }
+    }
+    safeKill(child, signal);
+}
+/**
+ * Resolve once the child's `exit` event fires, or after `timeoutMs` as a
+ * bounded escape hatch. Lets a profile-change respawn wait for the old child
+ * to release its port before probing it again (F13).
+ */
+export function awaitExit(child, timeoutMs = 5000) {
+    if (child.exitCode !== null)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(finish, timeoutMs);
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        child.once("exit", finish);
+    });
+}
+// ── Port / readiness probes (moved verbatim from preview-session-manager.ts) ──
+export async function defaultProbePort(port) {
+    // `free` = we could create + bind a server on that port right now.
+    return await new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => {
+            server.close(() => resolve(true));
+        });
+        try {
+            server.listen(port, "127.0.0.1");
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * Defense: a malicious profile file could set ready_path to something
+ * like `@evil.com/` which, when concatenated into the URL string, would
+ * redirect the readiness probe off-host. We build the URL via the URL
+ * constructor and assert the resolved host is 127.0.0.1 before fetching.
+ */
+export function buildReadyUrl(port, readyPath) {
+    try {
+        const base = new URL(`http://127.0.0.1:${port}/`);
+        // Treat readyPath as a pathname+search segment. Strip any leading
+        // authority / scheme characters so a malicious string can't smuggle
+        // another host through the URL constructor.
+        const clean = readyPath.replace(/^[/@]+/, "/").trim() || "/";
+        const url = new URL(clean, base);
+        if (url.hostname !== "127.0.0.1")
+            return null;
+        if (url.port !== String(port))
+            return null;
+        return url;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A dev-server port must be a positive integer inside the TCP range (F30). A
+ * missing / zero / non-integer port would otherwise skip the pre-spawn probe
+ * and leave the readiness poll hammering port 0 for the full timeout before it
+ * tree-kills the healthy dev server and misreports preview_timeout.
+ */
+export function isValidPort(port) {
+    return (typeof port === "number" &&
+        Number.isInteger(port) &&
+        port > 0 &&
+        port <= 65535);
+}
+/**
+ * Build the RETURNED preview URL (the one handed to window.open in the
+ * browser). Mirrors buildReadyUrl's host-pinning (F10): a malicious profile
+ * ready_path like "@evil.com/" — or an absolute "http://evil.com/" — must not
+ * smuggle a new authority into the string. We resolve the path through the URL
+ * constructor against a localhost origin and reject any host drift, preserving
+ * the historical host-only shape for a root path.
+ */
+export function buildPreviewUrl(port, readyPath) {
+    const origin = `http://localhost:${port}`;
+    try {
+        const clean = readyPath.replace(/^[/@]+/, "/").trim() || "/";
+        const url = new URL(clean, `${origin}/`);
+        // Reject any host OR scheme drift: an absolute "http://evil.com/", a
+        // "//"/"\\" authority smuggle, or a "javascript:"/"data:" scheme all
+        // resolve away from the pinned http://localhost origin.
+        if (url.protocol !== "http:" || url.hostname !== "localhost")
+            return origin;
+        if (url.pathname === "/" && !url.search && !url.hash)
+            return origin;
+        return `${origin}${url.pathname}${url.search}${url.hash}`;
+    }
+    catch {
+        return origin;
+    }
+}
+export async function defaultProbeReady(args) {
+    const url = buildReadyUrl(args.port, args.readyPath);
+    if (!url)
+        return false;
+    try {
+        const res = await fetch(url.toString(), { signal: args.signal });
+        // Any HTTP response at all (even 404) proves the server bound the port
+        // and is routable. Vite's default index sometimes 404s on `/`.
+        return res.status >= 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=preview-child-lifecycle.js.map

package/server/dist/core/preview-child-lifecycle.js.map

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

package/server/dist/core/preview-coherence.d.ts

@@ -0,0 +1,59 @@
+import type { ProfileConfig } from "./profile-loader.js";
+/**
+ * Preview-capability coherence predicate + warn matrix (plan § 2.1).
+ *
+ * Extracted out of `index.ts`'s `isMainModule` boot IIFE so the frontend
+ * predicate and the warn matrix are unit-testable without a live server
+ * boot (that block never executes under Vitest) and so `index.ts` stays
+ * off its bloat baseline. `index.ts` still owns the iteration + the
+ * `console.warn` side effect — the two functions here are pure.
+ *
+ * Used by:
+ *   - index.ts § "Section 03 — boot-time profile coherence check".
+ */
+/**
+ * Preview-capability precedence (CLAUDE.md § "Preview-capability
+ * precedence") Step 1 — does this profile DECLARE a frontend stack?
+ *
+ * A profile counts as frontend-declared only when `stack.frontend` is a
+ * NON-EMPTY object (or a truthy non-object value). The bundled
+ * `python-plugin-monorepo` profile intentionally ships
+ * `stack.frontend: {}` alongside `dev_server: null` — a backend-only
+ * stack by design. Plain `Boolean({})` is `true`, which made the
+ * boot-time coherence check emit a spurious "preview misconfigured"
+ * warning on EVERY boot for such projects (F32). Treating an empty
+ * object as backend-only keeps the diagnostic honest and the
+ * PreviewButton gate coherent. Non-object values keep the pre-fix
+ * `Boolean(...)` semantics (this narrows ONLY the empty-object case),
+ * and the `typeof === "object"` guard is TypeError-safe for any stray
+ * primitive.
+ */
+export declare function profileDeclaresFrontend(frontend: unknown): boolean;
+/**
+ * The narrow slice of a resolved profile the coherence check reads.
+ * `dev_server` is `| null` because the bundled backend-only profiles ship
+ * `"dev_server": null` in their JSON (e.g. python-plugin-monorepo).
+ */
+export type PreviewCoherenceProfile = {
+    stack?: {
+        frontend?: unknown;
+    };
+    dev_server?: ProfileConfig["dev_server"] | null;
+};
+/** Warn envelope emitted (as a JSON string) for an incoherent profile. */
+export interface PreviewCoherenceWarning {
+    level: "warn";
+    message: string;
+    projectId: string;
+    profile: string;
+}
+/**
+ * Pure evaluation of the preview coherence matrix for a single resolved
+ * profile. Returns a warning envelope when the profile's frontend
+ * declaration and dev_server wiring disagree, or `null` when they are
+ * coherent — including an intentionally backend-only stack
+ * (`stack.frontend: {}` + `dev_server: null`, F32). The caller owns the
+ * `console.warn` side effect.
+ */
+export declare function evaluatePreviewCoherence(projectId: string, profile: string, prof: PreviewCoherenceProfile): PreviewCoherenceWarning | null;
+//# sourceMappingURL=preview-coherence.d.ts.map

package/server/dist/core/preview-coherence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-coherence.d.ts","sourceRoot":"","sources":["../../src/core/preview-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAIlE;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,uBAAuB,GAC5B,uBAAuB,GAAG,IAAI,CAsBhC"}

package/server/dist/core/preview-coherence.js

@@ -0,0 +1,66 @@
+/**
+ * Preview-capability coherence predicate + warn matrix (plan § 2.1).
+ *
+ * Extracted out of `index.ts`'s `isMainModule` boot IIFE so the frontend
+ * predicate and the warn matrix are unit-testable without a live server
+ * boot (that block never executes under Vitest) and so `index.ts` stays
+ * off its bloat baseline. `index.ts` still owns the iteration + the
+ * `console.warn` side effect — the two functions here are pure.
+ *
+ * Used by:
+ *   - index.ts § "Section 03 — boot-time profile coherence check".
+ */
+/**
+ * Preview-capability precedence (CLAUDE.md § "Preview-capability
+ * precedence") Step 1 — does this profile DECLARE a frontend stack?
+ *
+ * A profile counts as frontend-declared only when `stack.frontend` is a
+ * NON-EMPTY object (or a truthy non-object value). The bundled
+ * `python-plugin-monorepo` profile intentionally ships
+ * `stack.frontend: {}` alongside `dev_server: null` — a backend-only
+ * stack by design. Plain `Boolean({})` is `true`, which made the
+ * boot-time coherence check emit a spurious "preview misconfigured"
+ * warning on EVERY boot for such projects (F32). Treating an empty
+ * object as backend-only keeps the diagnostic honest and the
+ * PreviewButton gate coherent. Non-object values keep the pre-fix
+ * `Boolean(...)` semantics (this narrows ONLY the empty-object case),
+ * and the `typeof === "object"` guard is TypeError-safe for any stray
+ * primitive.
+ */
+export function profileDeclaresFrontend(frontend) {
+    if (frontend == null)
+        return false;
+    if (typeof frontend !== "object")
+        return Boolean(frontend);
+    return Object.keys(frontend).length > 0;
+}
+/**
+ * Pure evaluation of the preview coherence matrix for a single resolved
+ * profile. Returns a warning envelope when the profile's frontend
+ * declaration and dev_server wiring disagree, or `null` when they are
+ * coherent — including an intentionally backend-only stack
+ * (`stack.frontend: {}` + `dev_server: null`, F32). The caller owns the
+ * `console.warn` side effect.
+ */
+export function evaluatePreviewCoherence(projectId, profile, prof) {
+    const hasFrontend = profileDeclaresFrontend(prof.stack?.frontend);
+    const hasDevServer = Boolean(prof.dev_server?.command);
+    if (hasFrontend && !hasDevServer) {
+        return {
+            level: "warn",
+            message: "profile declares stack.frontend but no dev_server.command — preview button will stay hidden",
+            projectId,
+            profile,
+        };
+    }
+    if (!hasFrontend && hasDevServer) {
+        return {
+            level: "warn",
+            message: "profile has dev_server.command but no stack.frontend — preview gate denies regardless (ADR-036)",
+            projectId,
+            profile,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=preview-coherence.js.map

package/server/dist/core/preview-coherence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-coherence.js","sourceRoot":"","sources":["../../src/core/preview-coherence.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAiB;IACvD,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO,MAAM,CAAC,IAAI,CAAC,QAAmC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACrE,CAAC;AAoBD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAiB,EACjB,OAAe,EACf,IAA6B;IAE7B,MAAM,WAAW,GAAG,uBAAuB,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACvD,IAAI,WAAW,IAAI,CAAC,YAAY,EAAE,CAAC;QACjC,OAAO;YACL,KAAK,EAAE,MAAM;YACb,OAAO,EACL,6FAA6F;YAC/F,SAAS;YACT,OAAO;SACR,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,YAAY,EAAE,CAAC;QACjC,OAAO;YACL,KAAK,EAAE,MAAM;YACb,OAAO,EACL,iGAAiG;YACnG,SAAS;YACT,OAAO;SACR,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/server/dist/core/preview-session-manager.d.ts

@@ -0,0 +1,86 @@
+import { spawn as realSpawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { type TreeKillDeps } from "./preview-child-lifecycle.js";
+export interface PreviewProfile {
+    dev_server?: {
+        command?: string;
+        port?: number;
+        ready_path?: string;
+        ready_timeout_seconds?: number;
+    };
+}
+export interface PreviewSpawnOptions {
+    cwd: string;
+    /** Injected for tests — omit to use node's real child_process.spawn. */
+    spawn?: typeof realSpawn;
+    /** Injected for tests — override port probe. Returns true when free. */
+    probePort?: (port: number) => Promise<boolean>;
+    /** Injected for tests — readiness probe. Returns true when ready. */
+    probeReady?: (args: {
+        port: number;
+        readyPath: string;
+        signal: AbortSignal;
+    }) => Promise<boolean>;
+    /** Injected for tests — ms clock. */
+    now?: () => number;
+    /** Sanitized env. Defaults to process.env minus SHIPWRIGHT_* / CLAUDE_*. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface PreviewEntry {
+    projectId: string;
+    pid: number;
+    url: string;
+    sessionId: string;
+    startedAt: number;
+    profileHash: string;
+    /** Internal — retained so killAll() can terminate. */
+    child: ChildProcessWithoutNullStreams;
+}
+export declare class PreviewProfileInvalidError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+export declare class PreviewSpawnFailedError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+export declare class PreviewPortInUseError extends Error {
+    readonly port: number;
+    constructor(port: number);
+}
+export declare class PreviewExitedEarlyError extends Error {
+    readonly code: number | null;
+    /** Captured tail of the child's stdout/stderr (F11 diagnostic). */
+    readonly tail: string;
+    constructor(code: number | null, tail?: string);
+}
+export declare class PreviewTimeoutError extends Error {
+    readonly seconds: number;
+    /** Captured tail of the child's stdout/stderr (F11 diagnostic). */
+    readonly tail: string;
+    constructor(seconds: number, tail?: string);
+}
+/** Lifecycle deps (test seams for tree-kill + respawn exit-wait). */
+export interface PreviewLifecycleDeps extends TreeKillDeps {
+    /** Bounded wait (ms) for an old child to exit before a respawn port probe. */
+    awaitExitMs?: number;
+}
+export declare class PreviewSessionManager {
+    private readonly lifecycle;
+    private entries;
+    /** In-flight spawns keyed by projectId — dedup for concurrent clicks (F12). */
+    private inFlight;
+    constructor(lifecycle?: PreviewLifecycleDeps);
+    /**
+     * Validate + tokenize a dev command. Exposed for tests and for the
+     * routes layer, which can dry-validate without mutating state.
+     * Returns argv on success; throws PreviewProfileInvalidError otherwise.
+     */
+    static tokenizeCommand(command: string | undefined): string[];
+    get(projectId: string): PreviewEntry | undefined;
+    spawn(projectId: string, profile: PreviewProfile, opts: PreviewSpawnOptions): Promise<PreviewEntry>;
+    private doSpawn;
+    killAll(): void;
+    /** Test helper — exposes the internal map size without leaking entries. */
+    size(): number;
+}
+//# sourceMappingURL=preview-session-manager.d.ts.map

package/server/dist/core/preview-session-manager.d.ts.map

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