@molecule/api-ai-tools 1.6.2 → 1.6.5

package/dist/suite-overlap.js

@@ -0,0 +1,208 @@
+/**
+ * The ONE rule that decides whether a suite run may start while another is already walking, and
+ * the command readings both sides of it need.
+ *
+ * Two sites ask "may a second run start now?" about the same pair of runs — the mid-run note that
+ * tells the executor what to do next while the suite it is waiting on is still going
+ * ({@link ./utilities.js} `repeatingFailureNote`), and the hold that refuses the run when it
+ * arrives (molecule-dev's `suite-overlap-hold.ts`) — and until xr-molecule-flash-m89 they answered
+ * it separately. That run's +19:59 `wait_for_task` handed over a repeating cause with "the test
+ * alone reproduces the first one … start on them now, while the run keeps walking"; 23 s later the
+ * executor sent exactly that re-run, and the overlap hold refused it — "A playwright suite is
+ * already running against this app and database … Wait for it." Two orders, one run, and the round
+ * trip between them was the whole cost.
+ *
+ * So the rule lives here ({@link suiteRunInTheWay}) and both of them call it: a run may start only
+ * when nothing in flight is already measuring the same app and database. What "the same app and
+ * database" MEANS lives here too ({@link suiteCommandTarget}) — the note and the hold have to key
+ * a command the same way before they can agree on whether two of them collide, and the re-run a
+ * note hands over is built from the same reading of the running command
+ * ({@link scopedRerunCommand}).
+ *
+ * The same treatment for the other pair that answered one question twice: whether a run walks the
+ * WHOLE suite or a part of it. The rewriter that decides whether a background Playwright run gets
+ * `--retries=0` ({@link ./utilities.js} `streamingBackgroundCommand`) and the platform's own notes
+ * (molecule-dev's `suite-cli-override.ts`) asked it separately — a regex there, a predicate here —
+ * until xr-molecule-flash-m89 showed the two answers were never the same question
+ * ({@link isDiagnosisRun}).
+ *
+ * @module
+ */
+import { commandSegments } from './command-position.js';
+import { commandRunsNoTests } from './no-test-run.js';
+/**
+ * A command with its heredoc bodies removed: the runs, kills and hosts it names in a file it
+ * WRITES are not what the command itself does.
+ *
+ * The header is kept (`cat > run.sh <<'EOF' …EOF` leaves `cat > run.sh`), which is what the
+ * readers here want: everything before the body is still readable as the command's own words.
+ *
+ * @param command - The shell command.
+ * @returns The command without its heredoc bodies.
+ */
+export function withoutHeredocs(command) {
+    return command.replace(/<<-?\s*(['"]?)(\w+)\1[\s\S]*?\n\s*\2\b/g, ' ');
+}
+/**
+ * The server a suite command points at, as a comparable key: the host it names (`HOST=`,
+ * `BASE_URL=`, `PLAYWRIGHT_BASE_URL=`, `--variable host=`, or a bare URL), or `local` for a run
+ * that names none — a suite run in the sandbox goes to the sandbox's own app unless the command
+ * says otherwise. Every localhost spelling collapses to `local` (one sandbox, one app, one
+ * database).
+ *
+ * @param command - The suite command.
+ * @returns The target key.
+ */
+export function suiteCommandTarget(command) {
+    const text = withoutHeredocs(command);
+    const named = /(?:\b(?:HOST|BASE_URL|PLAYWRIGHT_BASE_URL|E2E_BASE_URL)|--variable\s+host)\s*=\s*['"]?([^\s'"|;&]+)/i.exec(text)?.[1] ?? /https?:\/\/[^\s'"|;&]+/i.exec(text)?.[0];
+    if (!named)
+        return 'local';
+    const value = named.trim();
+    let host;
+    try {
+        const url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `http://${value}`);
+        host = url.hostname.toLowerCase();
+        if (!/^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1|\[::1\])$/.test(host))
+            return url.port ? `${host}:${url.port}` : host;
+    }
+    catch (_error) {
+        // Not a URL at all (a shell variable the command does not expand): compare
+        // the token itself, so the same spelling still reads as the same target.
+        return value.toLowerCase();
+    }
+    return 'local';
+}
+/**
+ * The whole-suite command made scoped to the tests it should re-run instead: the same
+ * invocation — same directory, same settings — with the named `file:line`s in place of the whole
+ * suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
+ * `--retries=0` set (a re-run of a known failure does not need to pay for retries).
+ *
+ * @param command - The whole-suite run's command.
+ * @param locations - The failing `file:line`s to re-run, as the run's own log printed them — or,
+ *   for a run that started outside the suite, the absolute form Playwright matches each file
+ *   argument against.
+ * @returns The scoped command, or the command unchanged when it runs no Playwright suite.
+ */
+export function scopedRerunCommand(command, locations) {
+    const at = command.search(/\bplaywright\s+test\b/);
+    if (at === -1)
+        return command;
+    const head = command.slice(0, at);
+    const rest = command.slice(at);
+    // Only the first statement runs the suite; the rest (`| tail -50`, `&& echo done`)
+    // is left exactly as it was.
+    const end = rest.search(/&&|\|\||;|\|/);
+    const statement = end === -1 ? rest : rest.slice(0, end);
+    const tail = end === -1 ? '' : rest.slice(end);
+    const scoped = statement
+        .replace(/\s*--last-failed\b/g, '')
+        .replace(/\s*--retries(?:[= ]\d+)?/g, '')
+        .replace(/^(playwright\s+test)\b/, `$1 ${locations.join(' ')} --retries=0`);
+    return `${head}${scoped}${tail}`;
+}
+/**
+ * The run in flight that makes a second run a hazard, or null when nothing is in the way.
+ *
+ * This is the ONE rule the mid-run note and the suite-overlap hold both answer with: a suite run
+ * may start only when this returns null, because two suites against one app and database share its
+ * rows — the failures one causes the other cannot be told from real ones. A run that invokes no
+ * suite is never in the way, and neither is one the candidate command stops first.
+ *
+ * @param candidate - The run about to start, by the app and database it would measure
+ *   ({@link suiteCommandTarget}).
+ * @param inFlight - The suite runs already going, in the order the caller found them.
+ * @returns The first run in the way, or null.
+ */
+export function suiteRunInTheWay(candidate, inFlight) {
+    return (inFlight.find((run) => run.runsSuite && run.target === candidate.target && !run.stoppedByCommand) ?? null);
+}
+/**
+ * The Playwright invocation of a command, as its own command-position text (`playwright test …`),
+ * or null when the command starts no Playwright run.
+ *
+ * The runner's own word has to END where the sub-command starts (`(?=\s|$)`, not a `\b`): a
+ * segment can be a fragment beginning at a `playwright test` printed INSIDE a string
+ * (`echo "then npx playwright test" && npx playwright test`), and a match that ends against the
+ * closing quote is that echo. A version-pinned `playwright@1.44.0 test` is the same run.
+ */
+const PLAYWRIGHT_RUN = /^(?:@playwright\/test|playwright)(?:@\S+)?\s+test(?=\s|$)/;
+/**
+ * What narrows a Playwright run to a part of the suite: a named file or line, a title filter, or
+ * the tests the run before it printed (`--last-failed`, `--only-changed`).
+ */
+const NARROWED_RUN = /\.(?:spec|test)\.[cm]?[jt]sx?\b|\.[cm]?[jt]sx?:\d+|(?:^|\s)(?:-g|--grep(?:-invert)?|--last-failed|--only-changed)\b/;
+/**
+ * The Playwright invocation's text when the command starts one, or null.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns The invocation's command-position text, or null.
+ */
+function playwrightRun(command) {
+    return (commandSegments(withoutHeredocs(command)).find((segment) => PLAYWRIGHT_RUN.test(segment.text))
+        ?.text ?? null);
+}
+/**
+ * Whether a `--max-failures` BOUNDS the walk: the flag is given a count above zero.
+ *
+ * Playwright's own spelling of "no cap" is zero — `maxFailures: 0` "disables the feature" — and
+ * that is the flag the platform's `testRunNote` asks for on the uncapped whole-suite run ("run the
+ * whole suite once with `--max-failures=0`"), which is why this is not a plain flag test.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns True when a failure cap would stop the walk.
+ */
+function boundsFailures(command) {
+    const flag = /(?:^|[\s;&|(])--max-failures(?![-\w])/.exec(command);
+    if (!flag)
+        return false;
+    const value = /(?:^|[\s;&|(])--max-failures(?:=|\s+)(['"]?)(\d[\d_]*)/.exec(command)?.[2];
+    // A `--max-failures` with no count at all is not the uncapped spelling of anything: it is read
+    // as a cap, the way Playwright's own default reading of the flag is a count of failures.
+    if (value === undefined)
+        return true;
+    return Number(value.replace(/_/g, '')) !== 0;
+}
+/**
+ * Whether a command walks a PART of a suite instead of all of it: a cap that stops it at a failure
+ * count, the failures the last run printed (`--last-failed`, `--only-changed`), a title filter, or
+ * named files/lines.
+ *
+ * THE one reading of that question, in one place. Two sites act on the answer and must never
+ * disagree:
+ *
+ * - the command rewriter that adds `--retries=0` to a background Playwright run
+ *   ({@link ./utilities.js} `streamingBackgroundCommand`) — a diagnosis walks each failure once,
+ *   while the run the suite is judged by keeps the suite's own retries; and
+ * - the platform's own notes (molecule-dev's `suite-cli-override.ts`), which must not tell the
+ *   executor to drop the `--retries=0` the platform itself has just added — the contradiction X1
+ *   flash-m74 and m75 filed, and m76 filed a third time.
+ *
+ * Until xr-molecule-flash-m89 they were a regex and a predicate that only LOOKED alike, and the
+ * gap was exactly the run the platform had asked for: its `testRunNote` says "run the whole suite
+ * once with `--max-failures=0`", and the rewriter read that cap flag as a capped diagnosis and
+ * stripped the suite's retries from the uncapped proof run that follows a deploy — the one run the
+ * graded run is compared against (+25:03, +31:39, +36:40 and +49:57, the last two against the
+ * deployed URL, where a network blip is likeliest and the retries it dropped are the ones that
+ * absorb it).
+ *
+ * `--max-failures=0` is Playwright's own "no cap" ({@link boundsFailures}), so it is not a
+ * diagnosis. A command that starts no Playwright run is not one either (false): the question is
+ * about a run already read as a Playwright suite.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns True when the run is a diagnosis or a re-run, not the whole suite.
+ */
+export function isDiagnosisRun(command) {
+    if (boundsFailures(command))
+        return true;
+    const run = playwrightRun(command);
+    if (run === null)
+        return false;
+    // A run that only collects and prints (`playwright test --list`, `--version`) walks no part of
+    // the suite either, and is not the whole-suite run the retries belong on.
+    if (commandRunsNoTests(run))
+        return true;
+    return NARROWED_RUN.test(run);
+}

package/dist/tools.d.ts

@@ -7,6 +7,24 @@
  * @module
  */
 import type { AITool } from '@molecule/api-ai';
+/**
+ * The command that stops a running background task, read from the sandbox's own pid files.
+ *
+ * THE one builder for it, so every note that hands the executor a way to stop a run hands over the
+ * same pid-only form: a `pkill -f <something>` matches the shell running it (its argv IS the
+ * command), and `molecule-dev/api/src/ai/pattern-kill-guard.ts` holds exactly that — X1
+ * xr-molecule-flash-m87's stuck note suggested `kill $(cat /tmp/<id>.pid) 2>/dev/null; pkill -f
+ * <id>.sh`, which the platform's own guard then refused, and the same shape cost a refused call at
+ * +21:57. The pid tree is the whole of what the pattern was for: the detached shell and every
+ * process under it.
+ *
+ * @param backend - The execution backend.
+ * @param taskId - The task's `mol-bg-…` handle.
+ * @returns The command to hand the executor — `kill <pids>` — falling back to the task's own pid
+ *   file when the walk comes back empty (a sandbox without `pgrep`, or a pid file already gone,
+ *   in which case the pid-file form is still the one the platform's guard names).
+ */
+export declare function taskStopCommand(backend: ExecutionBackend, taskId: string): Promise<string>;
 import type { ExecutionBackend, ToolBuildConfig } from './types.js';
 /**
  * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
@@ -21,6 +39,31 @@ import type { ExecutionBackend, ToolBuildConfig } from './types.js';
  * @returns The note, or null when the path is not inside a package's `dist`.
  */
 export declare function moleculeDistReadNote(path: string): string | null;
+/**
+ * The refusal for a write whose target is inside an installed package, or null
+ * when the path is not under a `node_modules` directory.
+ *
+ * `node_modules` is not the project's code: nothing written there survives the
+ * next install, no deploy carries it, and a sandbox whose dependency tree is
+ * shared (the pre-installed superset) breaks every other run through it. X0
+ * xr-molecule-flash-m91 (+04:43) called `write_file` on
+ * `node_modules/@molecule/api-resource-comment/dist/numbers.d.ts` while reading
+ * the package's declarations and clobbered its runtime module a call later
+ * (`module.exports = {}` over the ESM handler its own code imports) — the write
+ * answered `ok: true`, and 18 s went to noticing, `npm pack`-ing the package and
+ * putting the file back. Reading these files stays allowed (that is how the
+ * declarations above are read at all).
+ *
+ * The restore route is named because the model that has ALREADY clobbered a file
+ * (this refusal is too late for it) is the one who needs it, and because the
+ * obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
+ * sandbox. `npm pack` + a `tar` extraction over the package directory is what
+ * m91 used, and what both guards leave alone.
+ *
+ * @param path - An absolute path a tool is about to write.
+ * @returns The one-line refusal naming the package, or null when nothing is installed there.
+ */
+export declare function installedPackageWriteRefusal(path: string): string | null;
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAkL9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAm5DxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAiF9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAwHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsBxE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAgjExF"}