@prestyj/cli 5.28.0 → 5.29.0

package/dist/core/package-threats.js

@@ -0,0 +1,168 @@
+/**
+ * Package-install threat checks: typosquat detection against popular package
+ * names (local) and known-malicious packages via OSV (network, fail-open).
+ */
+import { log } from "./logger.js";
+import { POPULAR_NPM_PACKAGES, POPULAR_PYPI_PACKAGES } from "./shell-threats-popular-packages.js";
+const OSV_URL = "https://api.osv.dev/v1/querybatch";
+const OSV_TIMEOUT_MS = 3_000;
+const NPM_INSTALL = new Set(["add", "install", "i"]);
+const osvCache = new Map();
+/** Strip a version/range/extras suffix: `react@18`, `@a/b@1`, `requests==2.0`, `x[extra]`. */
+function bareName(spec, ecosystem) {
+    if (ecosystem === "npm") {
+        const at = spec.indexOf("@", 1);
+        const name = at === -1 ? spec : spec.slice(0, at);
+        return /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name) ? name.toLowerCase() : null;
+    }
+    const name = spec.split(/[[=<>!~;@\s]/)[0] ?? "";
+    return /^[a-z0-9][a-z0-9._-]*$/i.test(name) ? name.toLowerCase().replace(/[._]/g, "-") : null;
+}
+/** Packages named by install commands in `command`. Local paths/URLs are skipped. */
+export function parsePackageInstalls(command) {
+    const refs = [];
+    for (const segment of command.split(/(?:&&|\|\||[;|\n])/)) {
+        const tokens = segment
+            .trim()
+            .split(/\s+/)
+            .map((t) => t.replace(/^['"]|['"]$/g, ""))
+            .filter((t) => t.length > 0);
+        if (tokens[0] === "sudo")
+            tokens.shift();
+        const [program, sub, ...rest] = tokens;
+        let ecosystem = null;
+        let args = [];
+        if (program === "npx" && sub !== undefined) {
+            ecosystem = "npm";
+            args = [sub, ...rest].filter((a) => !a.startsWith("-")).slice(0, 1);
+        }
+        else if ((program === "npm" || program === "pnpm" || program === "yarn" || program === "bun") &&
+            sub !== undefined &&
+            NPM_INSTALL.has(sub)) {
+            ecosystem = "npm";
+            args = rest;
+        }
+        else if ((program === "pip" || program === "pip3") && sub === "install") {
+            ecosystem = "PyPI";
+            args = rest;
+        }
+        else if (program === "uv" && sub === "pip" && rest[0] === "install") {
+            ecosystem = "PyPI";
+            args = rest.slice(1);
+        }
+        if (!ecosystem)
+            continue;
+        let skipNext = false;
+        for (const arg of args) {
+            if (skipNext) {
+                skipNext = false;
+                continue;
+            }
+            // Options that take a value (`-r requirements.txt`, `--registry x`).
+            if (/^(?:-r|-c|-e|--requirement|--constraint|--editable|--registry|-i|--index-url)$/.test(arg)) {
+                skipNext = true;
+                continue;
+            }
+            if (arg.startsWith("-") || /[/\\:]/.test(arg.replace(/^@[^/]+\//, "")))
+                continue;
+            const name = bareName(arg, ecosystem);
+            if (name)
+                refs.push({ ecosystem, name });
+        }
+    }
+    return refs;
+}
+/** Optimal-string-alignment Damerau-Levenshtein distance. */
+export function damerauLevenshtein(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    const at = (i, j) => d[i]?.[j] ?? Number.POSITIVE_INFINITY;
+    for (let i = 1; i <= a.length; i++) {
+        const row = d[i];
+        if (!row)
+            continue;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let v = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                v = Math.min(v, at(i - 2, j - 2) + 1);
+            }
+            row[j] = v;
+        }
+    }
+    return at(a.length, b.length);
+}
+function typosquatOf(ref) {
+    const popular = ref.ecosystem === "npm" ? POPULAR_NPM_PACKAGES : POPULAR_PYPI_PACKAGES;
+    if (popular.includes(ref.name))
+        return null;
+    return (popular.find((p) => Math.abs(p.length - ref.name.length) <= 1 && damerauLevenshtein(p, ref.name) === 1) ?? null);
+}
+async function malwareIds(refs, options) {
+    const key = (r) => `${r.ecosystem}:${r.name}`;
+    const pending = refs.filter((r) => !osvCache.has(key(r)));
+    if (pending.length > 0) {
+        const doFetch = options.fetch ?? fetch;
+        const signals = [AbortSignal.timeout(OSV_TIMEOUT_MS)];
+        if (options.signal)
+            signals.push(options.signal);
+        try {
+            const res = await doFetch(OSV_URL, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    queries: pending.map((r) => ({ package: { ecosystem: r.ecosystem, name: r.name } })),
+                }),
+                signal: AbortSignal.any(signals),
+            });
+            if (!res.ok)
+                throw new Error(`OSV HTTP ${res.status}`);
+            const body = (await res.json());
+            pending.forEach((r, i) => {
+                const ids = (body.results?.[i]?.vulns ?? [])
+                    .map((v) => v.id ?? "")
+                    .filter((id) => id.startsWith("MAL-"));
+                osvCache.set(key(r), ids);
+            });
+        }
+        catch (err) {
+            log("WARN", "shell-threats", `OSV lookup failed, allowing install: ${String(err)}`);
+        }
+    }
+    const out = new Map();
+    for (const r of refs) {
+        const ids = osvCache.get(key(r));
+        if (ids && ids.length > 0)
+            out.set(r.name, ids);
+    }
+    return out;
+}
+/** Typosquat warnings (local) and known-malware blocks (OSV, fail-open). */
+export async function checkPackageInstall(command, options = {}) {
+    const refs = parsePackageInstalls(command);
+    if (refs.length === 0)
+        return [];
+    const threats = [];
+    for (const ref of refs) {
+        const intended = typosquatOf(ref);
+        if (intended) {
+            threats.push({
+                rule: "typosquat",
+                severity: "warn",
+                detail: `${ref.ecosystem} package "${ref.name}" is one edit away from popular "${intended}" — did you mean ${intended}?`,
+            });
+        }
+    }
+    for (const [name, ids] of await malwareIds(refs, options)) {
+        threats.push({
+            rule: "malicious-package",
+            severity: "block",
+            detail: `package "${name}" is flagged as malware by OSV (${ids.join(", ")})`,
+        });
+    }
+    return threats;
+}
+/** Test hook: forget cached OSV answers. */
+export function clearPackageThreatCache() {
+    osvCache.clear();
+}
+//# sourceMappingURL=package-threats.js.map

package/dist/core/package-threats.js.map

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

package/dist/core/persistent-shell.d.ts

@@ -2,7 +2,22 @@ import { type ResolveShellOpts, type ShellResolution } from "./shell.js";
 export interface PersistentRunResult {
     exitCode: number | "TIMEOUT";
     output: string;
+    /** Timeout/abort only: true when the command was stopped and the shell kept its state. */
+    shellKept?: boolean;
 }
+interface Snapshot {
+    cwd: string | null;
+    env: string;
+}
+/** Single-quote for bash. */
+export declare function shellQuote(value: string): string;
+/**
+ * Split a state file (`pwd -P` line, then `export -p`) into cwd + env script.
+ * Variables the new shell must own (PWD, OLDPWD, SHLVL) are dropped.
+ */
+export declare function parseStateSnapshot(text: string): Snapshot | null;
+/** Restore script: env first (its PWD is filtered), then cd, then report where we landed. */
+export declare function buildRestoreScript(snapshot: Snapshot): string;
 export declare class PersistentShell {
     private readonly cwd;
     private readonly env;
@@ -10,20 +25,57 @@ export declare class PersistentShell {
     private readonly shellOpts?;
     private readonly launch?;
     private child;
-    private buffer;
+    /** The shell's own `$$`, used to stop just its command. */
+    private shellPid;
     private busy;
+    private stateDir;
+    /**
+     * One-line notes about restarts, kept until `takeRestartNote()` so a helper
+     * run (e.g. a guard's `pwd`) cannot swallow the note meant for the model.
+     */
+    private pendingNotes;
+    /** Bumped by kill(): a run cut short by an explicit kill must not restart the shell. */
+    private generation;
     constructor(cwd: string, env: NodeJS.ProcessEnv, maxOutputBytes: number, shellOpts?: ResolveShellOpts | undefined, launch?: ShellResolution | undefined);
+    /**
+     * Consume the note(s) for the model about shell restarts since the last
+     * call, e.g. `[Shell exited with code 3, so it was restarted; restored
+     * working directory /x and exported environment variables. …]`.
+     */
+    takeRestartNote(): string | undefined;
     /** True while a previous persistent command is still running. */
     get isBusy(): boolean;
-    private ensureChild;
+    /** Private 0700 temp dir holding the state snapshot; null if unavailable. */
+    private get statePath();
+    private readSnapshot;
+    private spawnChild;
+    /** Spawn a shell, install the interrupt trap and learn its pid. */
+    private startShell;
+    /**
+     * Replace a dead (or killed) shell with a fresh one restored from the
+     * snapshot taken after the last completed command. Returns the one-line
+     * note for the tool result: `[Shell <how>, so it was restarted; <restored>.
+     * <lost> <tail>]`.
+     */
+    private restart;
+    /**
+     * The shell's own pid, if it is a real descendant of the spawned process
+     * (inside a Linux sandbox's pid namespace `$$` is not a host pid). Never on
+     * Windows, where MSYS pids are not native pids.
+     */
+    private verifiedShellPid;
+    private hardKill;
+    /**
+     * Write one script and wait for its sentinel. `run()` passes a signal and
+     * gets the stop-the-command-not-the-shell interrupt; setup scripts don't.
+     */
+    private send;
     /**
      * Run one command in the session shell. Serialized by the tool's sequential
      * execution mode; a concurrent call while busy is rejected defensively.
-     * On timeout or abort the whole session is killed (state is gone — the next
-     * call starts a fresh shell) because a wedged command cannot be safely
-     * skipped within the same shell.
      */
     run(command: string, timeoutMs: number, signal: AbortSignal, onChunk?: (text: string) => void): Promise<PersistentRunResult>;
-    /** Kill the session shell; the next run() starts a fresh one. */
+    /** Kill the session shell and drop its saved state; the next run() starts fresh. */
     kill(): void;
 }
+export {};