peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/openspec-validate-command.js

@@ -0,0 +1,45 @@
+// src/cli/commands/openspec-validate-command.ts
+//
+// `peaks openspec validate <changeId>`. Extracted from `openspec-commands.ts`;
+// the registered name, description, options and envelopes are unchanged.
+import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, OPENSPEC_PATH_HINT, printChangeNotFound, toValidateOptions } from './openspec-command-shared.js';
+/** The `openspec.validate` failure shape for a change that did not validate. */
+function printValidateInvalid(io, changeId, result, json) {
+    printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_INVALID', `OpenSpec change ${changeId} failed validation`, result, result.issues.map((issue) => `${issue.level}: ${issue.rule}: ${issue.message}`)), json);
+    process.exitCode = 1;
+}
+export function registerOpenSpecValidateCommand(openspec, io) {
+    addJsonOption(openspec
+        .command('validate')
+        .description('Validate an OpenSpec change against internal lint rules (and optionally the external openspec CLI)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--prefer-external', 'use the external openspec CLI when available, fall back to internal lint')).action(async (changeId, options) => {
+        try {
+            const result = await validateOpenSpecChange(changeId, toValidateOptions(options.project, options));
+            if (result === null) {
+                printChangeNotFound(io, 'openspec.validate', changeId, options.json);
+                return;
+            }
+            if (!result.valid) {
+                printValidateInvalid(io, changeId, result, options.json);
+                return;
+            }
+            printResult(io, ok('openspec.validate', result, result.issues
+                .filter((issue) => issue.level === 'warning')
+                .map((issue) => `${issue.rule}: ${issue.message}`)), options.json);
+        }
+        catch (error) {
+            failOpenSpec(io, 'openspec.validate', {
+                code: 'OPENSPEC_VALIDATE_FAILED',
+                error,
+                data: { changeId },
+                nextActions: OPENSPEC_PATH_HINT,
+                json: options.json
+            });
+        }
+    });
+}

package/dist/cli/commands/playwright-browser-command.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+/**
+ * Wire `peaks browser action <intent>`. The wrapper is a thin adapter
+ * for the 5 intents. The real MCP caller is provided by the IDE / agent
+ * harness — this CLI surface is invoked by tests and skills to drive
+ * browser flows without hand-shelling the MCP protocol.
+ */
+export declare function registerBrowserActionCommand(program: Command): void;

package/dist/cli/commands/playwright-browser-command.js

@@ -0,0 +1,61 @@
+// src/cli/commands/playwright-browser-command.ts
+//
+// `peaks browser action <intent>` — the thin Playwright MCP wrapper for the 5
+// supported intents. Split out of `playwright-commands.ts`; the registered
+// name, description, options and envelopes are unchanged.
+import { runBrowserAction } from '../../services/qa/browser-wrapper-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+import { emitFailure, emitSuccess } from './playwright-envelope.js';
+const SUPPORTED_INTENTS = ['navigate', 'click', 'fill', 'snapshot', 'extract'];
+function isSupportedIntent(value) {
+    return SUPPORTED_INTENTS.includes(value);
+}
+/**
+ * Pass-through caller used when the CLI surface is invoked outside the
+ * harness. In production the IDE/agent harness intercepts the wrapper's
+ * output and routes the underlying MCP call. Tests inject a stub via
+ * the `runBrowserAction(..., caller)` overload.
+ */
+async function mockOrPassThroughCaller(tool, args) {
+    return { tool, args, routedBy: 'peaks-loop-browser-wrapper' };
+}
+/**
+ * Wire `peaks browser action <intent>`. The wrapper is a thin adapter
+ * for the 5 intents. The real MCP caller is provided by the IDE / agent
+ * harness — this CLI surface is invoked by tests and skills to drive
+ * browser flows without hand-shelling the MCP protocol.
+ */
+export function registerBrowserActionCommand(program) {
+    const browser = program
+        .command('browser')
+        .description('Browser action helpers (slice 3: thin Playwright MCP wrapper, 5 intents only)');
+    browser
+        .command('action')
+        .description('Run one of 5 browser intents: navigate, click, fill, snapshot, extract')
+        .argument('<intent>', 'one of: navigate, click, fill, snapshot, extract')
+        .option('--url <url>', 'URL (navigate)')
+        .option('--selector <selector>', 'simple selector: #id, .class, tag, tag#id, tag.class')
+        .option('--value <value>', 'value to fill')
+        .option('--expression <expr>', 'JS expression to evaluate (extract)')
+        .option('--json', 'emit JSON envelope')
+        .action(async (intent, opts) => {
+        try {
+            if (!isSupportedIntent(intent)) {
+                throw new Error(`unknown intent "${intent}" — fall back to raw MCP (supported: navigate, click, fill, snapshot, extract)`);
+            }
+            // The IDE/agent harness bridges `mcp__playwright__browser_*` tools.
+            // Outside the harness, we use a pass-through caller that records
+            // the intent + args so skills and tests can route the call.
+            const result = await runBrowserAction(intent, {
+                url: opts.url,
+                selector: opts.selector,
+                value: opts.value,
+                expression: opts.expression
+            }, mockOrPassThroughCaller);
+            emitSuccess(opts.json, result, `intent=${result.intent} ok=${result.ok} elapsedMs=${result.elapsedMs}`);
+        }
+        catch (error) {
+            emitFailure(opts.json, getErrorMessage(error));
+        }
+    });
+}

package/dist/cli/commands/playwright-commands.d.ts

@@ -27,68 +27,16 @@
  * The CLI does NOT bundle `playwright-mcp`; it shells out to
  * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle
  * orchestrator, not the install medium.
+ *
+ * The verb implementations live beside this file: `playwright-session-store.ts`
+ * (port range, terminal-id derivation, session records, spawn),
+ * `playwright-ls-stop-commands.ts` (`ls` / `stop`) and
+ * `playwright-browser-command.ts` (`peaks browser action`). Every symbol this
+ * path used to export is still exported from it, so importers are unaffected.
  */
-import { spawn } from 'node:child_process';
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export declare const DEFAULT_PORT = 8931;
-export declare const MAX_PORT = 8949;
-declare const BROWSERS: readonly ["chromium", "firefox", "webkit"];
-type Browser = (typeof BROWSERS)[number];
-export interface PlaywrightSession {
-    terminalId: string;
-    port: number;
-    browser: Browser;
-    userDataDir: string;
-    startedAt: string;
-    pid?: number;
-}
-export declare const PLAYWRIGHT_SESSIONS_DIR = "playwright-sessions";
-export declare function playwrightSessionsDir(projectRoot: string): string;
-export declare function sessionFilePath(projectRoot: string, terminalId: string): string;
-/**
- * Derive a stable terminal id from the process environment. Prefers
- * the platform's own terminal-session id (macOS Terminal, Windows
- * Terminal) and falls back to a hash of (ppid, tty).
- */
-export declare function deriveTerminalId(env?: NodeJS.ProcessEnv, ppid?: number): string;
-/**
- * Walk port range starting at `start` and return the first port
- * that is NOT bound. Defaults: 8931 → 8949. If the range is exhausted,
- * returns null.
- */
-export declare function findFreePort(start?: number, max?: number, probe?: (port: number) => Promise<boolean>): Promise<number | null>;
-export declare function listSessions(projectRoot: string): PlaywrightSession[];
-export declare function readSession(projectRoot: string, terminalId: string): PlaywrightSession | null;
-export declare function writeSession(projectRoot: string, session: PlaywrightSession): void;
-export declare function removeSession(projectRoot: string, terminalId: string): boolean;
-/**
- * Spawn the playwright MCP via npx. We do NOT bundle the binary;
- * we just orchestrate the lifecycle. Returns the child PID so the
- * session file can record it.
- */
-export declare function spawnPlaywrightMcp(port: number, browser: Browser, userDataDir: string, projectRoot: string): {
-    pid: number | undefined;
-    child: ReturnType<typeof spawn>;
-};
-export declare function registerPlaywrightCommands(program: Command, _io: ProgramIO): void;
-/**
- * Wire `peaks browser action <intent>`. The wrapper is a thin adapter
- * for the 5 intents. The real MCP caller is provided by the IDE / agent
- * harness — this CLI surface is invoked by tests and skills to drive
- * browser flows without hand-shelling the MCP protocol.
- */
-export declare function registerBrowserActionCommand(program: Command): void;
-/**
- * Resolve and validate a caller-supplied `--user-data-dir`. The dir must
- * live under `projectRoot` so a malicious `--user-data-dir /etc/foo`
- * cannot coerce the playwright-mcp browser into writing state to an
- *
- * Resolves `..` segments before checking, so a path like
- * `<projectRoot>/../escape` is correctly normalized and rejected.
- *
- * Throws `Error('INVALID_USER_DATA_DIR: ...')` on validation failure;
- * the action handler catches and emits the JSON envelope.
- */
-export declare function resolveUserDataDir(raw: string, projectRoot: string): string;
-export {};
+export { DEFAULT_PORT, MAX_PORT, PLAYWRIGHT_SESSIONS_DIR, playwrightSessionsDir, sessionFilePath, deriveTerminalId, findFreePort, listSessions, readSession, writeSession, removeSession, spawnPlaywrightMcp, resolveUserDataDir } from './playwright-session-store.js';
+export type { PlaywrightSession } from './playwright-session-store.js';
+export { registerBrowserActionCommand } from './playwright-browser-command.js';
+export declare function registerPlaywrightCommands(program: Command, io: ProgramIO): void;