@wrongstack/plugin-sdk 0.308.7

package/dist/runtime/local-bin.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @wrongstack/plugins — project-local binary resolution.
+ *
+ * Why this module exists
+ * ----------------------
+ * Several plugins need to run a Node CLI that ships with the project
+ * (`biome`, `eslint`, `tsc`, `vitest`, …). The obvious spelling —
+ * `execFile('npx', ['biome', …])` — is wrong in three separate ways:
+ *
+ *  1. **It does not run on Windows at all.** `npx`/`pnpm`/`npm` are
+ *     `.cmd` shims there, and `execFile`/`spawn` without a shell do not
+ *     consult `PATHEXT`. The call fails `ENOENT`, plugins swallow the
+ *     error as "tool not installed", and the feature silently no-ops on
+ *     every Windows machine.
+ *  2. **It is slow.** `npx` re-resolves the package on each invocation,
+ *     and for a missing package it may try to *download* one — on a hook
+ *     that fires after every write.
+ *  3. **It is a weaker sandbox.** The shim is a shell script; arguments
+ *     cross a `cmd.exe` boundary on Windows (the BatBadBut class).
+ *
+ * `lint-gate` and `test-flake-detector` already solved this locally by
+ * resolving the package's `bin` entry through `createRequire` and running
+ * it as `process.execPath <entry>`. That is the correct pattern: no shell,
+ * no shim, no network, identical on every platform. This module promotes
+ * that proven approach to a shared helper so every plugin gets it.
+ *
+ * Fallback: when the package is genuinely absent from the project,
+ * `resolveNodeBin` returns `null` and the caller decides whether to
+ * degrade gracefully or fall back to a PATH lookup via
+ * `resolveWin32Command` (exported here for that purpose).
+ */
+import { resolveWin32Command } from '@wrongstack/tools/win32';
+export { resolveWin32Command };
+/** A spawn-ready invocation, already adjusted for the host platform. */
+export interface ExecInvocation {
+    cmd: string;
+    args: string[];
+    /** Only ever true on the Windows `.cmd`/`.bat` shim path. */
+    windowsVerbatimArguments: boolean;
+}
+/**
+ * Turn a `(command, args)` pair into something `execFile`/`spawn` can
+ * actually launch on this platform.
+ *
+ * On Windows, `npx`/`npm`/`pnpm`/`biome`/`tsc`/… ship as `.cmd` wrappers.
+ * `execFile` and `spawn` without a shell ignore `PATHEXT`, so a bare
+ * `execFile('npx', …)` fails `ENOENT` — and because every plugin treats a
+ * spawn failure as "tool not installed", the feature silently no-ops on
+ * every Windows machine. This resolves the real path first and, for a
+ * `.cmd`/`.bat` shim, routes through `cmd.exe` with per-argument quoting
+ * and a metacharacter guard (the BatBadBut argument-injection class), so
+ * a dynamic path argument still cannot chain a second command.
+ *
+ * On non-Windows, and for real `.exe` binaries, this is a passthrough.
+ *
+ * Throws when an argument carries a `cmd.exe` metacharacter on the shim
+ * path — callers should treat that as "skip", never as "run anyway".
+ *
+ * Prefer {@link resolveNodeBin} when the target is a Node CLI that the
+ * project depends on: `node <bin-entry>` needs no shim at all.
+ */
+export declare function resolveExecInvocation(command: string, args?: readonly string[]): ExecInvocation;
+/**
+ * Locate `cmd` on `PATH`, or return `null` if it is not there.
+ *
+ * This is the existence check `resolveWin32Command` deliberately does not
+ * provide: that function returns its input unchanged when nothing matches,
+ * so a caller cannot distinguish "found `biome`" from "gave up and handed
+ * back the string `biome`". Treating the passthrough as success makes a
+ * missing tool look installed — the caller then spawns it, gets `ENOENT`,
+ * and (because plugins read a spawn failure as "not installed") silently
+ * does nothing while reporting itself healthy.
+ *
+ * Returns the resolved path on success. Walks `PATH` directly, applying
+ * `PATHEXT` suffixes on Windows for a bare name and checking the execute
+ * bit on POSIX.
+ */
+export declare function findOnPath(cmd: string): string | null;
+/** A resolved, directly-spawnable invocation. Never a shell or a shim. */
+export interface ResolvedNodeBin {
+    /** Always `process.execPath` — the Node binary running this process. */
+    cmd: string;
+    /** `[binEntryPath, ...extraArgs]`. */
+    args: string[];
+    /** Absolute path of the package's bin entry, for diagnostics. */
+    entry: string;
+}
+/** Drop every cached resolution. Call from `teardown()`. */
+export declare function clearLocalBinCache(): void;
+/**
+ * Resolve a project-local Node CLI to a `process.execPath <entry>`
+ * invocation.
+ *
+ * @param packageName npm package to resolve, e.g. `@biomejs/biome`.
+ * @param binName     which `bin` key to prefer when the package declares
+ *                    several. Falls back to the sole/first entry.
+ * @param cwd         project root whose `package.json` anchors resolution.
+ * @param extraArgs   arguments appended after the bin entry.
+ *
+ * Returns `null` when the package is not installed, declares no `bin`, or
+ * the declared entry escapes its own package directory (a tampered
+ * `package.json` must not become an arbitrary-file execution primitive).
+ */
+export declare function resolveNodeBin(packageName: string, binName: string, cwd: string, extraArgs?: readonly string[]): ResolvedNodeBin | null;
+/**
+ * Resolve the first installed package from `candidates`.
+ *
+ * Used by plugins that accept several equivalent tools (biome *or*
+ * eslint, vitest *or* jest) and want the first one the project actually
+ * has, without probing each with a subprocess.
+ */
+export declare function resolveFirstNodeBin(candidates: readonly {
+    packageName: string;
+    binName: string;
+    args?: readonly string[];
+}[], cwd: string): (ResolvedNodeBin & {
+    packageName: string;
+    binName: string;
+}) | null;
+//# sourceMappingURL=local-bin.d.ts.map

package/dist/runtime/redos-guard.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Redos guard — run a regex inside a `node:worker_threads` worker so
+ * the host can actually terminate it on a wall-clock budget.
+ *
+ * Why a worker thread?
+ *   A `setTimeout`-based watchdog cannot interrupt a synchronous
+ *   CPU-bound regex in Node.js's single-threaded event loop. The
+ *   `setImmediate`/`setTimeout` race fires whichever wins the next
+ *   event-loop tick; if the regex blocks the loop synchronously for
+ *   7 seconds, the timer has long since fired and the regex still
+ *   returns a result — only after the loop is unblocked does the
+ *   `setImmediate` callback resume and resolve `{ timedOut: false }`.
+ *
+ *   The only honest fix is to run the regex in a separate thread that
+ *   the host can `worker.terminate()`. `node:worker_threads` gives us
+ *   that, and the per-thread cost is amortized by the runtime helper
+ *   itself (the host doesn't pay for the thread except when it
+ *   invokes `withReDoSGuard`).
+ *
+ * Why is this here, not inside each plugin?
+ *   Three plugins (`secret-scanner`, `prompt-firewall`, `path-guard`)
+ *   need the same contract. Three copies would drift; one copy is
+ *   auditable and testable.
+ *
+ * Contract:
+ *   `withReDoSGuard(re, input, ms)` returns:
+ *     { timedOut: false, match: RegExpExecArray | null }   on normal completion
+ *     { timedOut: true,  match: null }                     on timeout
+ */
+export interface ReDoSResult {
+    /** True when the regex did not complete within the wall-clock budget. */
+    timedOut: boolean;
+    /** The match result (groups, indices) when `timedOut === false`; null otherwise. */
+    match: RegExpExecArray | null;
+}
+export interface ReDoSOptions {
+    /** Wall-clock budget in ms. Default 50. */
+    budgetMs?: number;
+    /**
+     * Optional hook invoked exactly once when the budget is exceeded.
+     * Called synchronously after the regex is terminated. Default: no-op.
+     */
+    onTimeout?: (info: {
+        regex: RegExp;
+        input: string;
+        budgetMs: number;
+        elapsedMs: number;
+    }) => void;
+}
+/**
+ * Run `re.exec(input)` inside a worker thread with a wall-clock
+ * watchdog. The worker is terminated when the budget elapses; the
+ * regex cannot keep running.
+ *
+ * Returns a Promise; resolved with `{ timedOut, match }`.
+ */
+export declare function withReDoSGuard(re: RegExp, input: string, budgetMs?: number, options?: ReDoSOptions): Promise<ReDoSResult>;
+/**
+ * Convenience: build a guarded matcher.
+ *
+ * ```ts
+ * const matchCredential = guardedMatcher(/AKIA[0-9A-Z]{16}/g, 25);
+ * const r = await matchCredential(line);
+ * if (r.timedOut) counters.redosTimeouts++;
+ * else if (r.match) report(r.match);
+ * ```
+ */
+export declare function guardedMatcher(re: RegExp, budgetMs?: number, onTimeout?: ReDoSOptions['onTimeout']): (input: string) => Promise<ReDoSResult>;
+//# sourceMappingURL=redos-guard.d.ts.map

package/dist/runtime/safe-json.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @wrongstack/plugins — serialisation that cannot take the process down.
+ *
+ * Plugins routinely stringify values they did not construct: event-bus
+ * payloads, tool results, mailbox bodies. `JSON.stringify` throws on a
+ * circular reference and on `BigInt`, and several of these call sites sit
+ * inside detached (fire-and-forget) work where a throw becomes an
+ * unhandled rejection rather than a handled failure.
+ *
+ * `safeJsonStringify` never throws. A value it cannot represent is
+ * replaced with a marker, so the surrounding feature degrades to "this
+ * field is unreadable" instead of failing — or crashing — outright.
+ */
+/** Placeholder substituted for a value that cannot be serialised. */
+export declare const UNSERIALIZABLE = "[unserializable]";
+/**
+ * `JSON.stringify` with cycle handling and a total-failure fallback.
+ *
+ * @param value  anything
+ * @param indent passed through to `JSON.stringify` (e.g. `2` to pretty-print)
+ * @returns a JSON string, or a marker string when the value resists
+ *          serialisation entirely. Never throws.
+ */
+export declare function safeJsonStringify(value: unknown, indent?: number): string;
+//# sourceMappingURL=safe-json.d.ts.map

package/dist/runtime/sandbox.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Sandbox — canonical project-path validation with symlink resolution.
+ *
+ * Why a new helper when `runtime/index.ts` already exports
+ * `withinProject` and `sanitizeRunnerPath`?
+ *
+ *  - `withinProject` does NOT resolve symlinks: a path like
+ *    `project/link-to-/etc/passwd` reports as inside the project
+ *    even though the resolved target is outside.
+ *  - `sanitizeRunnerPath` is for runner argv (linter binaries),
+ *    not user-supplied tool input. The two paths share the
+ *    leading-dash + length checks but `sanitizeRunnerPath`
+ *    rejects a `cwd` for which it cannot resolve; user-input
+ *    sandbox needs canonicalization instead.
+ *
+ * The previous design (per SAGE memory T-03) relied on three
+ * duplicate `withinProject` copies in `runtime/index.ts`,
+ * `file-watcher/index.ts`, and `path-guard/glob.ts`. They drifted
+ * on edge cases. This helper is the single replacement.
+ *
+ * Contract:
+ *   `safePath(input, projectRoot?)` returns the canonical absolute
+ *   path inside the project on success, or `null` on rejection.
+ *
+ * Rejection cases:
+ *   - empty string
+ *   - length > 4096 bytes (matches `runtime.withinProject`)
+ *   - leading-dash (option smuggling)
+ *   - cannot be resolved (path doesn't exist or EPERM)
+ *   - resolved path escapes the project root
+ *   - symlink target is outside the project
+ */
+export interface SafePathOptions {
+    /**
+     * Project root for the sandbox. Defaults to `process.cwd()`. Pass
+     * the session cwd from the plugin host when available so that
+     * tools running in a subdirectory are scoped to that directory.
+     */
+    projectRoot?: string;
+    /**
+     * If true (default), follow symlinks via `realpathSync`. Set false
+     * for plugins that need to record the literal path the user wrote
+     * (e.g. checkpoint capture, git diff).
+     */
+    followSymlinks?: boolean;
+}
+/**
+ * Resolve `input` to an absolute path inside the project root.
+ *
+ * Returns `null` for empty/oversized/leading-dash inputs and for
+ * paths whose real target escapes the project.
+ */
+export declare function safePath(input: string, options?: SafePathOptions): string | null;
+/**
+ * Boolean convenience for callers that don't need the canonical path.
+ * Equivalent to `safePath(input, options) !== null`.
+ */
+export declare function isInsideProject(input: string, options?: SafePathOptions): boolean;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/runtime.d.ts

@@ -0,0 +1 @@
+export * from './runtime/index.js';