@sdods/cli 0.11.3 → 0.12.1

package/dist/commands/browsers.d.ts

@@ -9,7 +9,38 @@ export interface BrowserStatus {
     executable: string | null;
     playwrightVersion: string;
 }
-export declare function browserStatuses(names?: string[]): Promise<BrowserStatus[]>;
+/**
+ * Whether the download that produced `executable` finished.
+ *
+ * Playwright writes `INSTALLATION_COMPLETE` last. An executable without it is a download that was
+ * cut off, or one an antivirus scanner is still holding, and it does not launch reliably. Headless
+ * Chromium runs launch the separate headless shell of the same revision, so that must be complete
+ * too; a cache holding only one of the two fails every run with "Executable doesn't exist".
+ *
+ * A path outside Playwright's cache layout (a custom `executablePath`) has no marker to check, so
+ * the executable existing is all this can say.
+ */
+export declare function installationComplete(executable: string): boolean;
+export declare function browserStatuses(names?: string[], opts?: {
+    cwd?: string;
+}): Promise<BrowserStatus[]>;
+/**
+ * Make sure every downloaded engine a run needs is on disk, installing the missing ones when
+ * `install` is set.
+ *
+ * This is what stands between a run and Playwright's "Executable doesn't exist … run npx
+ * playwright install". That advice is wrong for SDODS: run from anywhere but the workspace it
+ * installs a different Playwright's revision, and without PLAYWRIGHT_BROWSERS_PATH it installs
+ * into a folder the desktop app never reads. Installing here, from the workspace, with the
+ * environment the run itself inherits, lands the exact revision where the runner will look, on
+ * every OS.
+ *
+ * Channel browsers (Edge) are a system install and stay with the check in `run`.
+ */
+export declare function ensureBrowsers(names: string[], opts: {
+    cwd: string;
+    install: boolean;
+}): Promise<string[]>;
 /** Install browser engines and channels (used by `browsers install`, `doctor --fix`, `init`). */
 export declare function installBrowsers(opts?: {
     browsers?: string[];

package/dist/commands/browsers.js

@@ -1,12 +1,12 @@
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
 import { BrowserSchema } from '@sdods/contracts';
 import { SdodsError } from '@sdods/core';
 import { createContext } from '../context.js';
-import { collect, json, ok, table } from '../ui.js';
+import { collect, info, json, ok, table, warn } from '../ui.js';
 // Typed against BrowserName (not `string`) so a new browser is a compile error here rather than a
 // silent fall-through to chromium.
 const ENGINE_OF = {
@@ -54,30 +54,83 @@ function channelExecutable(channel) {
     }
     return null;
 }
-export async function browserStatuses(names = DOWNLOADED_BROWSERS) {
-    const require = createRequire(import.meta.url);
-    let pw;
-    let version = 'unknown';
-    try {
-        pw = await import('playwright-core');
-        version = require('playwright-core/package.json').version;
+/**
+ * The playwright-core the RUNNER will launch, not the CLI's own copy.
+ *
+ * `@sdods/cli` depends on playwright-core, and the workspace depends on `@playwright/test`, which
+ * brings its own. When the two versions differ they want different browser revisions, and asking
+ * the CLI's copy would report `chromium-1243` present while the runner looks for `chromium-1250`.
+ * So resolve through the workspace's `@playwright/test` first, the same package `npx playwright
+ * install` runs from, and fall back to the CLI's copy only when there is no workspace install.
+ */
+function loadPlaywrightCore(cwd) {
+    const attempts = [];
+    if (cwd) {
+        attempts.push(() => {
+            const ws = createRequire(join(cwd, 'package.json'));
+            const test = createRequire(ws.resolve('@playwright/test/package.json'));
+            return createRequire(test.resolve('playwright/package.json'));
+        });
+        attempts.push(() => createRequire(join(cwd, 'package.json')));
     }
-    catch {
-        return names.map((name) => ({
-            name,
-            engine: ENGINE_OF[name] ?? 'chromium',
-            channel: CHANNEL_OF[name] ?? null,
-            installed: false,
-            executable: null,
-            playwrightVersion: version,
-        }));
+    attempts.push(() => createRequire(import.meta.url));
+    for (const attempt of attempts) {
+        try {
+            const req = attempt();
+            const pw = req('playwright-core');
+            const { version } = req('playwright-core/package.json');
+            return { pw, version };
+        }
+        catch {
+            // try the next location
+        }
     }
+    return null;
+}
+/** `chromium-1243`, `firefox-1543`, `webkit-2359`: the folder Playwright downloads a revision into. */
+const REVISION_DIR = /^(chromium|firefox|webkit)-(\d+)$/;
+/**
+ * Whether the download that produced `executable` finished.
+ *
+ * Playwright writes `INSTALLATION_COMPLETE` last. An executable without it is a download that was
+ * cut off, or one an antivirus scanner is still holding, and it does not launch reliably. Headless
+ * Chromium runs launch the separate headless shell of the same revision, so that must be complete
+ * too; a cache holding only one of the two fails every run with "Executable doesn't exist".
+ *
+ * A path outside Playwright's cache layout (a custom `executablePath`) has no marker to check, so
+ * the executable existing is all this can say.
+ */
+export function installationComplete(executable) {
+    if (!existsSync(executable))
+        return false;
+    let dir = dirname(executable);
+    while (!REVISION_DIR.test(basename(dir))) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            return true;
+        dir = parent;
+    }
+    const [, engine, revision] = REVISION_DIR.exec(basename(dir));
+    if (!existsSync(join(dir, 'INSTALLATION_COMPLETE')))
+        return false;
+    if (engine !== 'chromium')
+        return true;
+    const shell = join(dirname(dir), `chromium_headless_shell-${revision}`);
+    return existsSync(join(shell, 'INSTALLATION_COMPLETE'));
+}
+export async function browserStatuses(names = DOWNLOADED_BROWSERS, opts = {}) {
+    const loaded = loadPlaywrightCore(opts.cwd);
+    const version = loaded?.version ?? 'unknown';
     return names.map((name) => {
         const engine = ENGINE_OF[name] ?? 'chromium';
         const channel = CHANNEL_OF[name] ?? null;
         let executable;
         try {
-            executable = channel ? channelExecutable(channel) : pw[engine].executablePath();
+            executable = channel
+                ? channelExecutable(channel)
+                : loaded
+                    ? loaded.pw[engine].executablePath()
+                    : null;
         }
         catch {
             executable = null;
@@ -86,12 +139,58 @@ export async function browserStatuses(names = DOWNLOADED_BROWSERS) {
             name,
             engine,
             channel,
-            installed: Boolean(executable && existsSync(executable)),
+            installed: Boolean(executable && (channel ? existsSync(executable) : installationComplete(executable))),
             executable,
             playwrightVersion: version,
         };
     });
 }
+/**
+ * Make sure every downloaded engine a run needs is on disk, installing the missing ones when
+ * `install` is set.
+ *
+ * This is what stands between a run and Playwright's "Executable doesn't exist … run npx
+ * playwright install". That advice is wrong for SDODS: run from anywhere but the workspace it
+ * installs a different Playwright's revision, and without PLAYWRIGHT_BROWSERS_PATH it installs
+ * into a folder the desktop app never reads. Installing here, from the workspace, with the
+ * environment the run itself inherits, lands the exact revision where the runner will look, on
+ * every OS.
+ *
+ * Channel browsers (Edge) are a system install and stay with the check in `run`.
+ */
+export async function ensureBrowsers(names, opts) {
+    const wanted = [...new Set(names)].filter((n) => !CHANNEL_OF[n]);
+    if (!wanted.length)
+        return [];
+    const missing = (await browserStatuses(wanted, { cwd: opts.cwd })).filter((s) => !s.installed);
+    if (!missing.length)
+        return [];
+    // One engine can back several browsers (mobile-chrome is chromium); install each engine once.
+    const engines = [...new Set(missing.map((s) => s.engine))];
+    if (!opts.install) {
+        throw new SdodsError('NOT_SUPPORTED', `The ${engines.join(', ')} test browser${engines.length > 1 ? 's are' : ' is'} not installed.`, {
+            hint: `Run \`sdods browsers install ${engines.map((e) => `-b ${e}`).join(' ')}\` from the workspace, ` +
+                'or pass --install-browsers to install missing browsers before the run.',
+            exitCode: 2,
+        });
+    }
+    info(`Installing the ${engines.join(', ')} test browser${engines.length > 1 ? 's' : ''} for this run…`);
+    await installBrowsers({ browsers: engines, cwd: opts.cwd });
+    const still = (await browserStatuses(engines, { cwd: opts.cwd })).filter((s) => !s.installed);
+    if (still.length) {
+        throw new SdodsError('NOT_SUPPORTED', `Installing ${still.map((s) => s.name).join(', ')} did not complete.`, {
+            hint: 'Check the network or proxy (HTTPS_PROXY) and any antivirus quarantine, then run ' +
+                `\`sdods browsers install ${still.map((s) => `-b ${s.name}`).join(' ')}\`.`,
+            exitCode: 2,
+        });
+    }
+    if (process.platform === 'linux') {
+        warn('If the browser then fails to launch with missing libraries, run ' +
+            `\`sudo npx playwright install-deps ${engines.join(' ')}\` once on this machine.`);
+    }
+    ok(`Installed ${engines.join(', ')}`);
+    return engines;
+}
 /** Install browser engines and channels (used by `browsers install`, `doctor --fix`, `init`). */
 export async function installBrowsers(opts = {}) {
     const names = (opts.browsers?.length ? opts.browsers : DOWNLOADED_BROWSERS);
@@ -183,7 +282,7 @@ export function register(program) {
                 : DOWNLOADED_BROWSERS;
         for (const b of names)
             BrowserSchema.parse(b);
-        const statuses = await browserStatuses(names);
+        const statuses = await browserStatuses(names, { cwd: ctx.rootDir });
         if (ctx.opts.json)
             return json(statuses);
         table(statuses.map((s) => ({

package/dist/commands/doctor.js

@@ -37,7 +37,7 @@ export function registerDoctorCommand(program) {
                 fix: `npm i -D @playwright/test@^${MIN_PLAYWRIGHT_FOR_STEP_RESULTS} (or bun add -d)`,
             });
         }
-        const browsers = await browserCheck();
+        const browsers = await browserCheck(ctx.rootDir);
         checks.push(...browsers);
         if (opts.fix && browsers.some((b) => !b.ok)) {
             out(pc.cyan('Installing browsers…'));
@@ -239,11 +239,6 @@ function tokenMatrix(cliStatus, localLlm) {
         requirement: 'optional',
         present: has('SDODS_TOKEN'),
         detail: 'self-issued, free: MCP over HTTP and CI result ingest (`sdods tokens create`)',
-    }, {
-        name: 'FIREBASE_SERVICE_ACCOUNT_AUTOMAX_DOCS',
-        requirement: 'ci-only',
-        present: has('FIREBASE_SERVICE_ACCOUNT_AUTOMAX_DOCS'),
-        detail: 'GitHub secret for the docs deploy workflow',
     }, {
         name: 'NPM_TOKEN',
         requirement: 'ci-only',
@@ -351,11 +346,11 @@ async function versionCheck(name, args, fix, bin = name) {
         return { name, ok: false, detail: 'not found', fix };
     }
 }
-async function browserCheck() {
+async function browserCheck(cwd) {
     // Reuses `browsers list`'s detection so the two commands can never disagree about what is
     // installed — and so channel browsers are probed by path rather than by the bundled engine's
     // executable, which exists whether or not the branded browser does.
-    const statuses = await browserStatuses(['chromium', 'edge', 'firefox', 'webkit']);
+    const statuses = await browserStatuses(['chromium', 'edge', 'firefox', 'webkit'], { cwd });
     return statuses.map((s) => ({
         name: `browser:${s.name}`,
         ok: s.installed,

package/dist/commands/run.d.ts

@@ -41,6 +41,7 @@ export interface RunFlags {
     allowEmpty?: boolean;
     notify?: boolean;
     allowPoolContention?: boolean;
+    installBrowsers?: boolean;
 }
 export declare function register(program: Command): void;
 export declare function runCommand(flags: RunFlags, cmd: Command): Promise<number>;

package/dist/commands/run.js

@@ -6,7 +6,8 @@ import { RecordingModeSchema, newRunId, runFiles, } from '@sdods/contracts';
 import { SdodsError, CLI_OVERRIDES_ENV, VERSION, checkPoolCapacity, collectGateEvidence, effectiveWorkers, evaluateGates, formatFindings, hasGates, lintProject, listGeneratedProjects, moduleByName, moduleDir, normalizeTagExpr, parseTagExpr, poolAccountsFor, poolDemandByRole, poolTooSmallError, redactRunTraces, serializeCliOverrides, setupTierOf, } from '@sdods/core';
 import { analyzeChangeImpact } from '@sdods/mcp';
 import { createContext } from '../context.js';
-import { browserStatuses } from './browsers.js';
+import { workspaceBin } from '../workspace-bin.js';
+import { browserStatuses, ensureBrowsers } from './browsers.js';
 import { gateFailedError, printGates } from '../gates.js';
 import { maybeNotify, notifyRun } from '../notify.js';
 import { installedPlaywrightVersion, stepResultsWarning } from '../runner-compat.js';
@@ -36,6 +37,7 @@ function addRunOptions(cmd) {
         .option('--process <name>', 'run a named process (recipe) from the project or workspace')
         .option('--project-matrix', 'run every browser declared in the project yaml')
         .option('--device <name>', 'device name for mobile emulation, e.g. "iPhone 15"')
+        .option('--install-browsers', 'download any test browser the run needs that is missing (also SDODS_AUTO_INSTALL_BROWSERS=1)')
         .option('--headed', 'run headed')
         .option('-w, --workers <n>', 'parallel workers', parseIntFlag('workers'))
         .option('--allow-pool-contention', 'run even when a @user: role has fewer pool accounts than the workers that need it')
@@ -138,7 +140,7 @@ export async function runCommand(flags, cmd) {
     // selected browser here would fail runs that would have worked.
     const usesBrowser = !layers.length || layers.some((l) => l !== 'api');
     const missing = usesBrowser
-        ? (await browserStatuses(browsers)).filter((s) => s.channel && !s.installed)
+        ? (await browserStatuses(browsers, { cwd: ctx.rootDir })).filter((s) => s.channel && !s.installed)
         : [];
     if (missing.length) {
         const names = missing.map((s) => s.name);
@@ -313,10 +315,22 @@ export async function runCommand(flags, cmd) {
             exitCode: 2,
         });
     }
+    // Every run target launches a browser, including @api ones: the BDD fixtures are shared across
+    // layers, so an api target opens the runner's default engine (chromium). Checking here, against
+    // the targets actually generated, catches a missing or half-downloaded engine before bddgen, and
+    // either installs it (desktop app, --install-browsers) or stops with the SDODS command rather
+    // than Playwright's "npx playwright install", which installs to the wrong place.
+    if (!flags.list) {
+        await ensureBrowsers(runnerProjects.map((p) => p.browser ?? 'chromium'), {
+            cwd: ctx.rootDir,
+            install: Boolean(flags.installBrowsers) || process.env.SDODS_AUTO_INSTALL_BROWSERS === '1',
+        });
+    }
     // Recorded specs are plain runner tests: no Gherkin to generate.
     const recordedOnly = runnerProjects.every((p) => p.layer === 'recorded');
     if (!recordedOnly) {
-        const gen = await execa('npx', ['bddgen', '-c', configPath], {
+        const [bddgen, ...bddgenArgs] = workspaceBin(ctx.rootDir, 'playwright-bdd', 'bddgen');
+        const gen = await execa(bddgen, [...bddgenArgs, '-c', configPath], {
             cwd: ctx.rootDir,
             env: childEnv,
             stdio: ctx.opts.quiet ? 'pipe' : 'inherit',

package/dist/commands/watch.js

@@ -4,6 +4,7 @@ import pc from 'picocolors';
 import { newRunId } from '@sdods/contracts';
 import { SdodsError, listGeneratedProjects, normalizeTagExpr } from '@sdods/core';
 import { createContext } from '../context.js';
+import { workspaceBin } from '../workspace-bin.js';
 import { collect, out } from '../ui.js';
 /**
  * Spec generation runs in watch mode while the interactive UI
@@ -68,7 +69,8 @@ export function register(program) {
         process.on('SIGINT', stop);
         process.on('SIGTERM', stop);
         // initial generation so UI mode has specs to show
-        const gen = await execa('npx', ['bddgen', '-c', configPath], {
+        const [bddgen, ...bddgenArgs] = workspaceBin(ctx.rootDir, 'playwright-bdd', 'bddgen');
+        const gen = await execa(bddgen, [...bddgenArgs, '-c', configPath], {
             cwd: ctx.rootDir,
             env: childEnv,
             stdio: 'inherit',
@@ -79,7 +81,7 @@ export function register(program) {
                 exitCode: 1,
             });
         }
-        const watcher = execa('npx', ['bddgen', '-c', configPath, '--watch'], {
+        const watcher = execa(bddgen, [...bddgenArgs, '-c', configPath, '--watch'], {
             cwd: ctx.rootDir,
             env: childEnv,
             stdio: 'inherit',

package/dist/workspace-bin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * How to run a package's CLI from the workspace: `[node, <its bin script>]` when the package is
+ * installed there, else `['npx', <bin>]`.
+ *
+ * `npx <bin>` only finds a tool through a `node_modules/.bin` shim. Some layouts have the package
+ * but no shim npx recognises (bun on Windows writes `.bunx` shims), and npx then downloads an
+ * unrelated registry package of the same name: `npx bddgen` fetched `bddgen@1.0.5` and every run
+ * failed with "bddgen failed to generate specs". Resolving the package and running its bin with
+ * this Node works in every layout.
+ */
+export declare function workspaceBin(rootDir: string, pkg: string, bin: string): [string, ...string[]];
+//# sourceMappingURL=workspace-bin.d.ts.map

package/dist/workspace-bin.js

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/**
+ * How to run a package's CLI from the workspace: `[node, <its bin script>]` when the package is
+ * installed there, else `['npx', <bin>]`.
+ *
+ * `npx <bin>` only finds a tool through a `node_modules/.bin` shim. Some layouts have the package
+ * but no shim npx recognises (bun on Windows writes `.bunx` shims), and npx then downloads an
+ * unrelated registry package of the same name: `npx bddgen` fetched `bddgen@1.0.5` and every run
+ * failed with "bddgen failed to generate specs". Resolving the package and running its bin with
+ * this Node works in every layout.
+ */
+export function workspaceBin(rootDir, pkg, bin) {
+    try {
+        const manifest = createRequire(join(rootDir, 'package.json')).resolve(`${pkg}/package.json`);
+        const { bin: bins } = JSON.parse(readFileSync(manifest, 'utf8'));
+        const rel = typeof bins === 'string' ? bins : bins?.[bin];
+        if (rel)
+            return [process.execPath, join(dirname(manifest), rel)];
+    }
+    catch {
+        // not resolvable from here: fall back to npx
+    }
+    return ['npx', bin];
+}
+//# sourceMappingURL=workspace-bin.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/cli",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "description": "SDODS command line: run, record, analyze, agents, MCP server, scheduler and the web server.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -25,8 +25,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.11.3",
-    "@sdods/core": "0.11.3",
+    "@sdods/contracts": "0.12.1",
+    "@sdods/core": "0.12.1",
     "commander": "^15.0.0",
     "execa": "^10.0.1",
     "picocolors": "^1.1.1",
@@ -35,12 +35,12 @@
     "zod": "^4.6.5",
     "@playwright/test": "^1.63.0",
     "playwright-core": "^1.63.0",
-    "@sdods/integrations": "0.11.3",
-    "@sdods/mcp": "0.11.3",
-    "@sdods/agents": "0.11.3",
-    "@sdods/db": "0.11.3",
+    "@sdods/integrations": "0.12.1",
+    "@sdods/mcp": "0.12.1",
+    "@sdods/agents": "0.12.1",
+    "@sdods/db": "0.12.1",
     "csv-parse": "^7.0.2",
-    "@sdods/server": "0.11.3"
+    "@sdods/server": "0.12.1"
   },
   "homepage": "https://sdods.com",
   "bugs": {

package/skills/sdods-run/SKILL.md

@@ -32,13 +32,19 @@ an SDODS source checkout use `bun run sdods`.
    ```
 2. Run the requested slice. Typical combinations:
    ```bash
-   sdods run -p <project> -e <env> -l api                                  # API only, no browser
+   sdods run -p <project> -e <env> -l api                                  # API only (still launches chromium: shared fixtures)
    sdods run -p <project> -e <env> -l ui -b chromium -t @smoke             # quick UI smoke
    sdods run -p <project> -e <env> -t @regression --project-matrix         # every browser in the yaml
    sdods run -p <project> -e <env> -t "@user:admin"                        # scenarios that lease admin users
    sdods run -p <project> -e <env> -l hybrid -w 2                          # API→UI chaining
    sdods run -p <project> -e <env> --har-replay --strict -t @smoke         # offline, CI-style
+   sdods run -p <project> -e <env> -b firefox --install-browsers           # download missing browsers first
    ```
+   A run whose browser is missing or half-downloaded stops before generating specs with the
+   `sdods browsers install -b <engine>` command; `--install-browsers` (or
+   `SDODS_AUTO_INSTALL_BROWSERS=1`, which the desktop app sets) downloads it instead. Never answer
+   Playwright's "run npx playwright install" by running that from another folder: it installs a
+   different revision into a cache the runner does not read.
 3. Read results:
    ```bash
    sdods report --last                    # summary: totals, failed, flaky, report paths