@momentiq/dark-factory-cli 3.0.2 → 3.1.1

package/dist/mode/init.js

@@ -4,8 +4,10 @@
 // Design constraints:
 //  - APPEND, never re-serialize the consumer's file: hand-maintained comments
 //    and formatting survive. The appended block is generated YAML.
-//  - Deterministic scope proposal: only directories that actually exist are
-//    proposed (the engineer reviews the init PR — this is a seed, not policy).
+//  - Deterministic scope proposal: directories that actually exist are proposed
+//    (the engineer reviews the init PR — this is a seed, not policy), plus two
+//    always-on seeds independent of layout — `**/*.css` (a minimal editable
+//    surface) and `.darkfactory/**` (the mode's own workflow artifacts).
 //  - Idempotent: an existing `modes.<name>` entry short-circuits to "exists".
 //  - Fail closed: the candidate file content must round-trip through the
 //    canonical parser (@momentiq/dark-factory-schemas) before it is written.
@@ -23,6 +25,14 @@ const DEFAULT_PROTECTED_PATHS = [
     "package.json",
     "package-lock.json",
 ];
+// Non-monorepo frontend roots (Next/Vite/CRA/Remix): the app lives in a named
+// top-level dir rather than at the repo root or under `apps/*`. Each root is
+// probed for the same conventional subdirs, mirrored one level deep — so a
+// designer on a `web/`-rooted repo gets real component scopes, not css-only (#354).
+// Exported so `df mode preview` resolves the SAME frontend workspace this init
+// step detects, instead of assuming the repo root is the frontend (#377/#379).
+export const FRONTEND_ROOT_DIRS = ["web", "frontend", "client"];
+const FRONTEND_ROOT_SUBDIRS = ["components", "app", "pages", "src", "lib", "styles"];
 const ROOT_SCOPE_DIR_CANDIDATES = [
     "src/components",
     "src/app",
@@ -33,6 +43,7 @@ const ROOT_SCOPE_DIR_CANDIDATES = [
     "pages",
     "styles",
     "public",
+    ...FRONTEND_ROOT_DIRS.flatMap((root) => FRONTEND_ROOT_SUBDIRS.map((sub) => `${root}/${sub}`)),
 ];
 const APP_SCOPE_SUBDIR_CANDIDATES = ["src/components", "src/app", "src/pages", "public"];
 function isDir(path) {
@@ -44,10 +55,13 @@ function isDir(path) {
     }
 }
 /**
- * Propose write scopes from directories that exist. Monorepo `apps/<name>`
- * workspaces are scanned one level deep. Styling files are always in scope —
- * a designer mode with no reachable surface still gets `**\/*.css` so the
- * engineer sees an editable (if minimal) seed to correct in the init PR.
+ * Propose write scopes from directories that exist. Root-level frontend roots
+ * (`web/`, `frontend/`, `client/`) and the Next `src/` conventions are probed,
+ * plus monorepo `apps/<name>` workspaces one level deep. Two always-on seeds
+ * are appended regardless of layout: `**\/*.css` (a designer with no reachable
+ * component surface still gets a minimal editable seed to correct in the init
+ * PR) and `.darkfactory/**` (the mode's own workflow — `designer-brief` and
+ * `df objectives derive --apply` — writes there, so its outputs stay in scope).
  */
 export function detectWriteScopes(repoRoot) {
     const scopes = [];
@@ -55,6 +69,17 @@ export function detectWriteScopes(repoRoot) {
         if (isDir(join(repoRoot, candidate)))
             scopes.push(`${candidate}/**`);
     }
+    // Bare top-level `src/` fallback (#354): repos that keep the whole frontend
+    // under a single `src/` (no Next `src/<area>` split) match none of the
+    // `src/<subdir>` candidates above and would otherwise fall through to
+    // css-only. Propose the broad `src/**` only when `src/` exists AND no
+    // more-specific `src/<subdir>` scope already matched, so the seed never lists
+    // `src/**` beside a scope it already contains. (The web/frontend/client roots
+    // need no such guard — their subdirs are siblings, not nested under a broader
+    // candidate.)
+    if (isDir(join(repoRoot, "src")) && !scopes.some((s) => s.startsWith("src/"))) {
+        scopes.push("src/**");
+    }
     const appsRoot = join(repoRoot, "apps");
     if (isDir(appsRoot)) {
         for (const entry of readdirSync(appsRoot).sort()) {
@@ -65,24 +90,135 @@ export function detectWriteScopes(repoRoot) {
             }
         }
     }
-    scopes.push("**/*.css");
+    // Always-on seeds, independent of repo layout: `**\/*.css` (a designer with no
+    // reachable component surface still gets a minimal editable seed) and
+    // `.darkfactory/**` — the mode's OWN workflow writes there (`designer-brief`
+    // → .darkfactory/briefs/…, `df objectives derive --apply` →
+    // .darkfactory/objectives.yaml), so seeding it keeps those outputs in scope
+    // and the mode doesn't fail its own `mode-scope-critic` gate (#361).
+    scopes.push("**/*.css", ".darkfactory/**");
     return scopes;
 }
-function detectDevServer(repoRoot) {
+// Best-effort default preview URL. The seed is reviewed in the init PR; the
+// engineer corrects the port if the detected server binds elsewhere.
+const DEFAULT_DEV_URL = "http://localhost:3000";
+// GNU make reads the first of these that exists (GNUmakefile → makefile →
+// Makefile); we mirror that precedence.
+const MAKEFILE_NAMES = ["GNUmakefile", "makefile", "Makefile"];
+// foreman/honcho read `Procfile.dev` for development when present, else `Procfile`.
+const PROCFILE_NAMES = ["Procfile.dev", "Procfile"];
+// Docker Compose v2 file precedence — the highest-precedence file that exists
+// is authoritative; the rest are ignored by the tool, so we don't read them.
+const COMPOSE_FILE_NAMES = [
+    "compose.yaml",
+    "compose.yml",
+    "docker-compose.yaml",
+    "docker-compose.yml",
+];
+// Service names that plausibly ARE the dev server, in priority order.
+const COMPOSE_DEV_SERVICE_NAMES = ["dev", "web", "app", "frontend", "client"];
+function detectPackageDevServer(repoRoot) {
     const pkgPath = join(repoRoot, "package.json");
     if (!existsSync(pkgPath))
         return undefined;
     try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-        if (pkg.scripts?.["dev"]) {
-            return { command: "npm run dev", url: "http://localhost:3000" };
-        }
+        if (pkg.scripts?.["dev"])
+            return { command: "npm run dev", url: DEFAULT_DEV_URL };
     }
     catch {
-        // Malformed package.json → no dev-server proposal; init still succeeds.
+        // Malformed package.json → no proposal from this source; init still succeeds.
+    }
+    return undefined;
+}
+function detectMakefileDevServer(repoRoot) {
+    for (const name of MAKEFILE_NAMES) {
+        const filePath = join(repoRoot, name);
+        if (!existsSync(filePath))
+            continue;
+        let content;
+        try {
+            content = readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of content.split("\n")) {
+            // A `dev` target is defined at column 0 as `dev:` / `dev: prereqs` /
+            // `dev::` (double-colon rule). Inspect the TARGET's own colon only: a
+            // `dev :=` / `dev ::=` / `dev :::=` variable assignment has `=`
+            // immediately after the colon run, while a real target does not. Keying
+            // on the target colon (not a `:=` substring anywhere on the line) keeps a
+            // valid target with a target-specific variable (`dev: FOO := bar`)
+            // correctly detected.
+            if (/^dev[ \t]*:{1,2}(?![:=])/.test(line)) {
+                return { command: "make dev", url: DEFAULT_DEV_URL };
+            }
+        }
+    }
+    return undefined;
+}
+function detectProcfileDevServer(repoRoot) {
+    for (const name of PROCFILE_NAMES) {
+        const filePath = join(repoRoot, name);
+        if (!existsSync(filePath))
+            continue;
+        let content;
+        try {
+            content = readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        // Procfile lines are `<process>: <command>`; the `web` process is the HTTP
+        // server a designer previews. Propose its command verbatim.
+        const match = content.match(/^web:\s*(.+)$/m);
+        const command = (match?.[1] ?? "").trim();
+        if (command)
+            return { command, url: DEFAULT_DEV_URL };
+    }
+    return undefined;
+}
+function detectComposeDevServer(repoRoot) {
+    for (const name of COMPOSE_FILE_NAMES) {
+        const filePath = join(repoRoot, name);
+        if (!existsSync(filePath))
+            continue;
+        // The highest-precedence compose file that exists is authoritative; Compose
+        // ignores the lower-precedence files, so we don't fall through to them.
+        try {
+            const doc = parseYaml(readFileSync(filePath, "utf8"));
+            const services = doc?.services;
+            if (services && typeof services === "object") {
+                for (const svc of COMPOSE_DEV_SERVICE_NAMES) {
+                    if (Object.prototype.hasOwnProperty.call(services, svc)) {
+                        return { command: `docker compose up ${svc}`, url: DEFAULT_DEV_URL };
+                    }
+                }
+            }
+        }
+        catch {
+            // Malformed compose file → no proposal; init still succeeds.
+        }
+        return undefined;
     }
     return undefined;
 }
+/**
+ * Propose a dev-server command for the mode's mandatory visual loop. Priority:
+ * an explicit npm `dev` script first, then the container-first / make / Procfile
+ * layouts that repos without a `scripts.dev` use — so a designer on a
+ * make-driven or compose-driven repo gets a real preview command instead of
+ * nothing (#357; the component-isolation preview harness is a separate PR).
+ * Only a source whose file/target actually exists yields a proposal; undefined
+ * when none match.
+ */
+function detectDevServer(repoRoot) {
+    return (detectPackageDevServer(repoRoot) ??
+        detectMakefileDevServer(repoRoot) ??
+        detectProcfileDevServer(repoRoot) ??
+        detectComposeDevServer(repoRoot));
+}
 export function buildDefaultModeEntry(repoRoot, modeName) {
     const writeScopes = detectWriteScopes(repoRoot);
     const devServer = detectDevServer(repoRoot);

package/dist/mode/init.js.map

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

package/dist/mode/preview-capture.d.ts

@@ -0,0 +1,3 @@
+import { type CaptureDeps } from "./preview.js";
+export declare const defaultCaptureDeps: CaptureDeps;
+//# sourceMappingURL=preview-capture.d.ts.map

package/dist/mode/preview-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-capture.d.ts","sourceRoot":"","sources":["../../src/mode/preview-capture.ts"],"names":[],"mappings":"AAmBA,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AA2BzE,eAAO,MAAM,kBAAkB,EAAE,WAoEhC,CAAC"}

package/dist/mode/preview-capture.js

@@ -0,0 +1,137 @@
+// Default `CaptureDeps` for `df mode preview` — the real Vite-server + Playwright
+// wiring. Kept in its own file (never imported by tests, which inject fakes) so
+// the pure harness/detection core in `preview.ts` stays browser- and
+// bundler-free.
+//
+// RESOLUTION CONTEXT (load-bearing). Vite and Playwright are NOT dependencies of
+// this CLI — like the `ui-visual` route, they are resolved from the CONSUMER's
+// repo. A bare `import("vite")` would resolve against the CLI's own node_modules
+// (wrong copy, or absent). So we resolve every consumer module against the
+// resolved FRONTEND WORKSPACE (`workspaceDir` — often a `web/` subdir, where the
+// frontend's node_modules actually live, NOT necessarily the repo root) and
+// dynamic-import the resolved path. When a module or the browser is missing, we
+// THROW — `runPreview` catches it and degrades with an actionable message (never
+// a crash, never fabricated evidence).
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { BrowserUnavailableError } from "./preview.js";
+/** Dynamic-import a module resolved from `baseDir` (the frontend workspace), NOT
+ *  the CLI's own node_modules. Throws (with the module name) when not installed. */
+async function importFrom(mod, baseDir) {
+    // The anchor file need not exist — node uses its dirname as the resolution base.
+    const req = createRequire(join(baseDir, "package.json"));
+    let resolved;
+    try {
+        resolved = req.resolve(mod);
+    }
+    catch {
+        throw new Error(`cannot resolve "${mod}" from ${baseDir} — is it installed here?`);
+    }
+    return (await import(pathToFileURL(resolved).href));
+}
+/** CJS/ESM interop: a CJS module imported via dynamic `import()` exposes its
+ *  `module.exports` under `.default`; a real ESM module exposes named exports
+ *  directly. Vite's and Playwright's resolved (CJS) builds land on `.default`,
+ *  so read the member from whichever object actually has it. */
+function member(mod, name) {
+    const direct = mod[name];
+    if (direct !== undefined)
+        return direct;
+    const def = mod["default"];
+    return def?.[name];
+}
+export const defaultCaptureDeps = {
+    async startServer({ workspaceDir, harnessDir, port, alias }) {
+        // Vite transforms the component's TSX/JSX (+ CSS, path aliases) on the fly —
+        // the "detected framework's isolated render" the harness relies on. Resolve
+        // vite + the react plugin from the frontend workspace (they live in its
+        // node_modules — `web/node_modules`, not necessarily the repo root's).
+        const viteMod = await importFrom("vite", workspaceDir);
+        const createServer = member(viteMod, "createServer");
+        if (typeof createServer !== "function") {
+            throw new Error("resolved `vite` but it exposes no createServer() — unexpected build shape");
+        }
+        const reactPluginMod = await importFrom("@vitejs/plugin-react", workspaceDir);
+        const reactPlugin = (typeof reactPluginMod["default"] === "function" ? reactPluginMod["default"] : reactPluginMod);
+        // root = harnessDir (inside workspaceDir), so its index.html is served at "/",
+        // bare `react` imports resolve up into the workspace's node_modules, and
+        // `fs.allow` lets the entry import the component under the workspace. The
+        // injected `resolve.alias` (from the workspace tsconfig `paths`) is what makes
+        // real components' `@/…` imports resolve (#377) — omit the key entirely when
+        // empty so Vite's defaults are untouched.
+        const server = await createServer({
+            root: harnessDir,
+            configFile: false,
+            logLevel: "silent",
+            plugins: [reactPlugin()],
+            ...(alias.length > 0 ? { resolve: { alias } } : {}),
+            server: {
+                port,
+                strictPort: false,
+                host: "127.0.0.1",
+                fs: { allow: [workspaceDir, harnessDir] },
+            },
+        });
+        await server.listen();
+        const url = server.resolvedUrls?.local?.[0] ?? `http://127.0.0.1:${port}/`;
+        return {
+            url,
+            close: async () => {
+                await server.close();
+            },
+        };
+    },
+    async capture({ url, workspaceDir }) {
+        // Resolve Playwright from the SAME frontend workspace as the server — accept
+        // either `playwright` or `@playwright/test` (the ui-visual route uses the
+        // latter). Resolution + launch failures are a genuinely-unavailable browser →
+        // BrowserUnavailableError (soft-degrade). Anything AFTER launch (navigation,
+        // the render, the screenshot) is a REAL failure and propagates as a plain
+        // Error so runPreview surfaces it loudly.
+        const browser = await launchBrowser(workspaceDir);
+        try {
+            const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+            await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+            // Structural render floor — the harness wraps the component in <main>.
+            await page.locator("main").first().waitFor({ state: "visible", timeout: 15_000 });
+            const aria = await page.locator("body").ariaSnapshot();
+            const png = await page.screenshot({ fullPage: true });
+            return { aria, png };
+        }
+        finally {
+            await browser.close();
+        }
+    },
+};
+/** Resolve + launch Chromium from the consumer repo. Every failure here is a
+ *  browser-unavailable condition (not installed / no binary / missing system
+ *  deps), so normalize it to `BrowserUnavailableError` — the ONLY capture failure
+ *  runPreview soft-degrades. */
+async function launchBrowser(baseDir) {
+    let pwMod;
+    try {
+        pwMod = await importFrom("playwright", baseDir);
+    }
+    catch {
+        try {
+            pwMod = await importFrom("@playwright/test", baseDir);
+        }
+        catch (err) {
+            throw new BrowserUnavailableError(`Playwright is not installed in ${baseDir} (${err instanceof Error ? err.message : String(err)}). ` +
+                `Install with \`npm i -D playwright\`.`);
+        }
+    }
+    const chromium = member(pwMod, "chromium");
+    if (!chromium || typeof chromium.launch !== "function") {
+        throw new BrowserUnavailableError("resolved Playwright but it exposes no chromium.launch() — unexpected shape");
+    }
+    try {
+        return await chromium.launch();
+    }
+    catch (err) {
+        // A launch failure is a missing/unusable browser binary or system deps.
+        throw new BrowserUnavailableError(err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=preview-capture.js.map

package/dist/mode/preview-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-capture.js","sourceRoot":"","sources":["../../src/mode/preview-capture.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,gFAAgF;AAChF,qEAAqE;AACrE,gBAAgB;AAChB,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,iFAAiF;AACjF,2EAA2E;AAC3E,iFAAiF;AACjF,4EAA4E;AAC5E,gFAAgF;AAChF,iFAAiF;AACjF,uCAAuC;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,uBAAuB,EAAoB,MAAM,cAAc,CAAC;AAEzE;oFACoF;AACpF,KAAK,UAAU,UAAU,CAAC,GAAW,EAAE,OAAe;IACpD,iFAAiF;IACjF,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;IACzD,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,UAAU,OAAO,0BAA0B,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAA4B,CAAC;AACjF,CAAC;AAED;;;gEAGgE;AAChE,SAAS,MAAM,CAAI,GAA4B,EAAE,IAAY;IAC3D,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAW,CAAC;IAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAwC,CAAC;IAClE,OAAO,GAAG,EAAE,CAAC,IAAI,CAAkB,CAAC;AACtC,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAgB;IAC7C,KAAK,CAAC,WAAW,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE;QACzD,6EAA6E;QAC7E,4EAA4E;QAC5E,wEAAwE;QACxE,uEAAuE;QACvE,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACvD,MAAM,YAAY,GAAG,MAAM,CACzB,OAAO,EACP,cAAc,CACf,CAAC;QACF,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,sBAAsB,EAAE,YAAY,CAAC,CAAC;QAC9E,MAAM,WAAW,GAAG,CAClB,OAAO,cAAc,CAAC,SAAS,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,cAAc,CAC9D,CAAC;QAEjC,+EAA+E;QAC/E,yEAAyE;QACzE,0EAA0E;QAC1E,+EAA+E;QAC/E,6EAA6E;QAC7E,0CAA0C;QAC1C,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;YAChC,IAAI,EAAE,UAAU;YAChB,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;YACxB,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,MAAM,EAAE;gBACN,IAAI;gBACJ,UAAU,EAAE,KAAK;gBACjB,IAAI,EAAE,WAAW;gBACjB,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC,EAAE;aAC1C;SACF,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,oBAAoB,IAAI,GAAG,CAAC;QAC3E,OAAO;YACL,GAAG;YACH,KAAK,EAAE,KAAK,IAAI,EAAE;gBAChB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE;QACjC,6EAA6E;QAC7E,0EAA0E;QAC1E,8EAA8E;QAC9E,6EAA6E;QAC7E,0EAA0E;QAC1E,0CAA0C;QAC1C,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,CAAC;QAClD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YAC/E,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACpE,uEAAuE;YACvE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAClF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,CAAC;YACvD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;CACF,CAAC;AAEF;;;gCAGgC;AAChC,KAAK,UAAU,aAAa,CAAC,OAAe;IAC1C,IAAI,KAA8B,CAAC;IACnC,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,UAAU,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,uBAAuB,CAC/B,kCAAkC,OAAO,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK;gBACjG,uCAAuC,CAC1C,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAA+B,KAAK,EAAE,UAAU,CAAC,CAAC;IACzE,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACvD,MAAM,IAAI,uBAAuB,CAC/B,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,wEAAwE;QACxE,MAAM,IAAI,uBAAuB,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/mode/preview.d.ts

@@ -0,0 +1,227 @@
+export interface FrontendWorkspace {
+    /** Absolute dir whose package.json declares react — the module/config base
+     *  (deps read, vite/plugin-react resolution, harness dir, fs.allow, aliases). */
+    workspaceDir: string;
+    /** Label relative to the invocation cwd, for the operator note ("web" or "."). */
+    relLabel: string;
+}
+/**
+ * Resolve the frontend workspace for a repo rooted at `cwd`. Mirrors
+ * `df mode init`'s detection (same FRONTEND_ROOT_DIRS): the first of
+ * `web/`,`frontend/`,`client/` whose package.json declares react wins; else the
+ * repo root itself when ITS package.json declares react. Returns `null` when no
+ * react is found anywhere — the caller degrades with the existing no-react
+ * blocker (which keeps the honest "install react" message + exit code). PURE.
+ */
+export declare function resolveFrontendWorkspace(cwd: string): FrontendWorkspace | null;
+/** A Vite/rollup alias entry. The regex `find` form maps a `/*` glob prefix
+ *  correctly (e.g. `{ find: /^@\//, replacement: "<ws>/src/" }`). */
+export interface AliasEntry {
+    find: string | RegExp;
+    replacement: string;
+}
+/**
+ * Strip line (`//`) and block comments from JSONC, STRING-AWARE: a naive
+ * stripper corrupts a value like `"./src/*"` (which contains a literal
+ * slash-star) by treating it as the start of a block comment. Tracks string
+ * state (and escapes) so only real comments are removed. PURE.
+ */
+export declare function stripJsonComments(text: string): string;
+/** Tolerant JSONC parse: strip comments (string-aware) + trailing commas, then
+ *  JSON.parse. Returns `null` on any failure (caller proceeds with no alias). */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * Convert tsconfig `compilerOptions.paths` (+ `baseUrl`) into Vite alias entries.
+ * `paths` targets resolve relative to `baseUrl` (default `.` = tsconfigDir).
+ * Only the FIRST target is used (Vite alias has no fallback array). PURE.
+ *
+ * A single `classifyGlob` is applied to BOTH the key and the target, and an entry
+ * is emitted ONLY when the two AGREE — so mis-shapen mappings can't leak through
+ * on either side:
+ *  - both `exact` → exact alias (`^<key>$` → resolved target).
+ *  - both `prefix` → prefix alias (`^<keyPrefix>/` → `<resolvedTargetPrefix>/`).
+ *    The find RE-ADDS the boundary `/` so it anchors on a path separator: `"@/*"`
+ *    → `^@/`, which never matches `@scope/pkg` (a bare `^@` WOULD shadow every
+ *    scoped npm package — the bug this guards).
+ *  - ANY other combination — either side `unsupported`, or a KIND MISMATCH like a
+ *    `prefix` key with an `exact` target (`"@/*": ["./src/index.ts"]`, invalid
+ *    TS) — is SKIPPED: the key is returned in `unsupported`, no alias, no throw.
+ *
+ * The common shadcn/Next shapes (`"@/*": ["./src/*"]`, `["./*"]`, exact keys) are
+ * unaffected; monorepo mid-glob mappings (a `@pkg` key mapped to a
+ * `packages`-style target with an inner wildcard) skip.
+ */
+export declare function tsconfigPathsToAlias(input: {
+    paths?: Record<string, string[]> | undefined;
+    baseUrl?: string | undefined;
+    tsconfigDir: string;
+}): {
+    alias: AliasEntry[];
+    unsupported: string[];
+};
+/** One file the harness writes into its temp dir. */
+export interface HarnessFile {
+    /** Path relative to the harness dir (e.g. "index.html", ENTRY_BASENAME). */
+    path: string;
+    contents: string;
+}
+export declare const ENTRY_BASENAME = "df-preview-entry.tsx";
+export declare const INDEX_HTML_BASENAME = "index.html";
+export interface GenerateHarnessInput {
+    /** Absolute path to the component file being previewed. */
+    componentAbsPath: string;
+    /** Absolute path to the (temp) harness dir the files are written into. The
+     *  entry imports the component by a path relative to here. */
+    harnessDir: string;
+    /** Human component name (from the filename) — used in the title + wrapper. */
+    componentName: string;
+    /** Named export to mount. When omitted the harness imports the DEFAULT export. */
+    exportName?: string;
+    /** React major (18/19 → `createRoot`; <18 → `ReactDOM.render`). */
+    reactMajor: number;
+}
+/**
+ * Generate the minimal isolated-render harness for a React component: an entry
+ * that mounts JUST that component (placeholder/default props) inside a `<main>`
+ * landmark, plus an `index.html`. The `<main>` wrapper guarantees the same
+ * structural render floor the `ui-visual` producer asserts (`getByRole("main")`),
+ * regardless of what the component itself renders. PURE — returns file contents;
+ * the caller writes them.
+ */
+export declare function generateHarness(input: GenerateHarnessInput): HarnessFile[];
+export type PreviewBlockerCode = "not-a-component-file" | "no-react" | "no-vite" | "server-component" | "no-export";
+export interface DetectInput {
+    /** Repo root (consumer cwd). */
+    cwd: string;
+    /** Absolute path to the component file. */
+    componentAbsPath: string;
+    /** The component file's source. */
+    source: string;
+    /** Parsed consumer package.json (deps ∪ devDeps ∪ peerDeps merged), or null. */
+    packageDeps: Record<string, string> | null;
+}
+export interface DetectResult {
+    /** `vite-harness` = renderable via the generated harness; `unsupported` = a
+     *  blocker prevents an honest render (see `blocker`). */
+    engine: "vite-harness" | "unsupported";
+    componentName: string;
+    reactMajor: number;
+    /** Resolved export to mount (undefined = default export). */
+    exportName?: string;
+    /** An isolation tool is present — reported (v1 still renders via the generated
+     *  harness; native story capture is deferred, see the PR body). */
+    storybook: boolean;
+    ladle: boolean;
+    /** Non-fatal advisories surfaced to the operator. */
+    warnings: string[];
+    /** Non-null when the component genuinely cannot be rendered — `runPreview`
+     *  degrades (exit 2) with this message rather than a wrong render. */
+    blocker?: {
+        code: PreviewBlockerCode;
+        message: string;
+    };
+}
+/** Best-effort PascalCase component name from a filename (`user-card.tsx` →
+ *  `UserCard`, `Button.tsx` → `Button`). */
+export declare function componentNameFromPath(componentAbsPath: string): string;
+/**
+ * Resolve which export the harness should mount. Preference order:
+ *   1. `export default` present → default import (undefined exportName).
+ *   2. a named export matching the PascalCase filename.
+ *   3. the first `export function|const <PascalCaseName>`.
+ * Returns `{ kind: "none" }` when no export is found (a blocker).
+ */
+export declare function resolveExport(source: string, componentName: string): {
+    kind: "default";
+} | {
+    kind: "named";
+    name: string;
+} | {
+    kind: "none";
+};
+/**
+ * Decide whether the component can be rendered via the generated Vite harness,
+ * and gather advisories. PURE — no fs, no network.
+ */
+export declare function detectStrategy(input: DetectInput): DetectResult;
+/** Injected boundary so the Vite-server + Playwright wiring is never imported by
+ *  tests. The default implementation lives in `preview-capture.ts`. */
+export interface CaptureDeps {
+    /** Start an isolated dev server rooted at the harness dir; resolve to its base
+     *  URL + a close(). `workspaceDir` is the resolved FRONTEND workspace (where
+     *  react/vite/node_modules + the tsconfig aliases live), NOT the invocation cwd
+     *  — vite/plugin-react resolve from it and `fs.allow` is scoped to it. `alias`
+     *  is the tsconfig `paths` map as Vite `resolve.alias` entries (may be empty).
+     *  Throws when the transform tool (Vite) is unavailable. */
+    startServer(input: {
+        workspaceDir: string;
+        harnessDir: string;
+        port: number;
+        alias: AliasEntry[];
+    }): Promise<{
+        url: string;
+        close: () => Promise<void>;
+    }>;
+    /** Drive a browser: navigate, wait for the `main` landmark, return the ARIA
+     *  snapshot + a full-page PNG. `workspaceDir` is threaded so the browser is
+     *  resolved from the SAME frontend workspace as the server (not `process.cwd()`
+     *  and not necessarily the repo root). Throws a `BrowserUnavailableError` when
+     *  the browser genuinely can't launch; any OTHER throw is treated as a real
+     *  render/transform failure (surfaced loudly). */
+    capture(input: {
+        url: string;
+        workspaceDir: string;
+    }): Promise<{
+        aria: string;
+        png: Buffer;
+    }>;
+}
+/** Thrown by a `CaptureDeps.capture` when the browser cannot be resolved/launched
+ *  (Playwright not installed, Chromium binary absent, missing system deps). This
+ *  is the ONLY capture failure that degrades softly (exit 2, "reached the capture
+ *  step") — a Vite transform error, a component runtime exception, missing props,
+ *  or an `fs.allow`-blocked import is a REAL failure and surfaces loudly (exit 1). */
+export declare class BrowserUnavailableError extends Error {
+    constructor(message: string);
+}
+/** Secondary heuristic (belt-and-suspenders alongside `BrowserUnavailableError`):
+ *  recognize a genuine missing-browser / launch / install failure from its message
+ *  so a raw Playwright error is still classified as degrade-soft, while a render or
+ *  transform error is NOT. Kept deliberately narrow. */
+export declare function isBrowserUnavailable(err: unknown): boolean;
+export interface RunPreviewOptions {
+    /** Component path as given by the operator (relative to cwd or absolute). */
+    componentPath: string;
+    cwd: string;
+    /** Local port for the isolated harness server (default 5199). */
+    port?: number;
+    /** Override the evidence slug (default: sanitized component filename). */
+    slug?: string;
+}
+export type PreviewStatus = "captured" | "degraded" | "error";
+export interface RunPreviewResult {
+    status: PreviewStatus;
+    /** 0 captured · 2 degraded (tool/browser/unsupported) · 1 hard usage error. */
+    exitCode: 0 | 1 | 2;
+    slug: string;
+    message: string;
+    warnings: string[];
+    /** Absolute evidence dir when `captured`. */
+    evidenceDir?: string;
+}
+/**
+ * A safe evidence slug is a SINGLE path segment: filesystem-safe chars only, and
+ * never `.` / `..` / anything with a separator. The slug is interpolated into the
+ * evidence path (`agent-reviews/quality-gates/ui/<sha>/<slug>/…`), so an operator
+ * `--slug ../../..` would otherwise traverse OUT of the evidence tree and clobber
+ * arbitrary files. The auto-derived slug is already safe (`sanitizeSlug`); this
+ * fail-closes an explicit `--slug`. Exported for the traversal regression test.
+ */
+export declare function isSafeSlug(slug: string): boolean;
+/**
+ * Render one component in isolation and write `ui-visual`-shaped evidence.
+ * Never throws for an expected failure — returns a `degraded`/`error` result
+ * with an actionable message and the right exit code.
+ */
+export declare function runPreview(opts: RunPreviewOptions, deps: CaptureDeps): Promise<RunPreviewResult>;
+//# sourceMappingURL=preview.d.ts.map

package/dist/mode/preview.d.ts.map

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