@expressots/studio-agent 4.0.0-preview.1

package/dist/security/lockfile-graph.d.ts

@@ -0,0 +1,69 @@
+/**
+ * In-memory model of `package-lock.json` v2/v3.
+ *
+ * The lockfile is the ground truth for *what's actually installed* in
+ * the user's `node_modules`. npm audit's output is a flat list keyed by
+ * package name and a partial `effects` array — useful, but it doesn't
+ * give us the full transitive chain or the direct dependency that
+ * brought a vulnerable package in. We need that for two features:
+ *
+ *   1. Root-cause routing — show "lodash@4.17.10 reached via
+ *      express-session → fix by upgrading express-session 1.17.0 → 1.17.3".
+ *   2. Fix-group construction — collapse N CVEs that all resolve via
+ *      one upgrade into a single "Upgrade X — fixes N advisories" row.
+ *
+ * The graph is intentionally minimal: we parse the lockfile once,
+ * resolve each "node_modules/<path>" entry's dependencies against npm's
+ * hoist rules (nearest ancestor wins), and store the forward edges. We
+ * do *not* try to invert it — root-cause queries do a small BFS from
+ * the project's direct deps, which is cheap enough at any realistic
+ * project size (thousands of packages, milliseconds).
+ */
+import type { RootCause } from '../types/index.js';
+/**
+ * Loaded lockfile graph. A `null` instance means we couldn't parse the
+ * lockfile (no file, unsupported version, etc.) — callers should treat
+ * that as "no transitive resolution available" and skip enrichment.
+ */
+export declare class LockfileGraph {
+    private readonly root;
+    private readonly nodes;
+    /** Adjacency cache: node-key → array of resolved-child node-keys. */
+    private readonly childCache;
+    private constructor();
+    /**
+     * Parse the lockfile at `cwd`. Returns `null` for missing /
+     * unparseable lockfiles — root-cause routing then no-ops, which is
+     * better than a hard failure.
+     */
+    static load(cwd: string): LockfileGraph | null;
+    /** True when `pkg` is declared as a direct dep / devDep / optionalDep. */
+    isDirect(pkg: string): boolean;
+    /** Version of a direct dep, or undefined if it's not a direct dep. */
+    directVersion(pkg: string): string | undefined;
+    /** Returns the set of every distinct package name in the graph. */
+    packageNames(): Set<string>;
+    /**
+     * Find the shortest chain of dependency names from any direct dep to
+     * an installation of `vulnerablePkg`.
+     *
+     * Returns `null` when:
+     *   - the vulnerable package isn't installed at all, or
+     *   - the BFS exhausts the graph without finding a route (shouldn't
+     *     happen if the lockfile is internally consistent).
+     */
+    findRootCause(vulnerablePkg: string): RootCause | null;
+    /**
+     * Resolve `parentKey`'s declared dep `depName` to the lockfile entry
+     * that actually fulfils it. npm's hoist rule is "nearest ancestor with
+     * a matching `node_modules/<name>` wins" — we walk back up by trimming
+     * the path one segment at a time until we hit a match.
+     */
+    private resolveDep;
+    /**
+     * Find *some* installation of `pkg`. We prefer a hoisted top-level
+     * one (most common); falling back to the first nested copy found.
+     */
+    private findInstalledNode;
+}
+//# sourceMappingURL=lockfile-graph.d.ts.map

package/dist/security/lockfile-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile-graph.d.ts","sourceRoot":"","sources":["../../src/security/lockfile-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAqBnD;;;;GAIG;AACH,qBAAa,aAAa;IAKJ,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAE1D,OAAO;IAIP;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IA4D9C,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI9B,sEAAsE;IACtE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK9C,mEAAmE;IACnE,YAAY,IAAI,GAAG,CAAC,MAAM,CAAC;IAQ3B;;;;;;;;OAQG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IA8DtD;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAyBlB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/security/lockfile-graph.js

@@ -0,0 +1,245 @@
+/**
+ * In-memory model of `package-lock.json` v2/v3.
+ *
+ * The lockfile is the ground truth for *what's actually installed* in
+ * the user's `node_modules`. npm audit's output is a flat list keyed by
+ * package name and a partial `effects` array — useful, but it doesn't
+ * give us the full transitive chain or the direct dependency that
+ * brought a vulnerable package in. We need that for two features:
+ *
+ *   1. Root-cause routing — show "lodash@4.17.10 reached via
+ *      express-session → fix by upgrading express-session 1.17.0 → 1.17.3".
+ *   2. Fix-group construction — collapse N CVEs that all resolve via
+ *      one upgrade into a single "Upgrade X — fixes N advisories" row.
+ *
+ * The graph is intentionally minimal: we parse the lockfile once,
+ * resolve each "node_modules/<path>" entry's dependencies against npm's
+ * hoist rules (nearest ancestor wins), and store the forward edges. We
+ * do *not* try to invert it — root-cause queries do a small BFS from
+ * the project's direct deps, which is cheap enough at any realistic
+ * project size (thousands of packages, milliseconds).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Loaded lockfile graph. A `null` instance means we couldn't parse the
+ * lockfile (no file, unsupported version, etc.) — callers should treat
+ * that as "no transitive resolution available" and skip enrichment.
+ */
+export class LockfileGraph {
+    root;
+    nodes = new Map();
+    /** Adjacency cache: node-key → array of resolved-child node-keys. */
+    childCache = new Map();
+    constructor(root) {
+        this.root = root;
+        this.nodes.set(root.key, root);
+    }
+    /**
+     * Parse the lockfile at `cwd`. Returns `null` for missing /
+     * unparseable lockfiles — root-cause routing then no-ops, which is
+     * better than a hard failure.
+     */
+    static load(cwd) {
+        const file = path.join(cwd, 'package-lock.json');
+        let raw;
+        try {
+            raw = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        // We only handle lockfile v2/v3 (which share the `packages` map).
+        // npm v7+ defaults to v2; npm v9+ to v3. Both are universally
+        // supported by the Node LTS releases we care about.
+        if (!parsed.packages || typeof parsed.packages !== 'object') {
+            return null;
+        }
+        const rootEntry = parsed.packages[''];
+        const root = {
+            key: '',
+            name: parsed.name ?? rootEntry?.name ?? '<project>',
+            version: parsed.version ?? rootEntry?.version ?? '0.0.0',
+            deps: {
+                ...(rootEntry?.dependencies ?? {}),
+                ...(rootEntry?.devDependencies ?? {}),
+                ...(rootEntry?.optionalDependencies ?? {}),
+            },
+            isRoot: true,
+        };
+        const graph = new LockfileGraph(root);
+        for (const [key, entry] of Object.entries(parsed.packages)) {
+            if (key === '')
+                continue;
+            // The lockfile key encodes the install path; the package name is
+            // the last segment after the final `node_modules/`. Take that
+            // rather than trust `entry.name` (which v2 sometimes omits).
+            const name = nameFromKey(key) ?? entry?.name;
+            if (!name)
+                continue;
+            graph.nodes.set(key, {
+                key,
+                name,
+                version: entry?.version ?? 'unknown',
+                deps: {
+                    ...(entry?.dependencies ?? {}),
+                    ...(entry?.optionalDependencies ?? {}),
+                },
+                isRoot: false,
+            });
+        }
+        return graph;
+    }
+    /** True when `pkg` is declared as a direct dep / devDep / optionalDep. */
+    isDirect(pkg) {
+        return pkg in this.root.deps;
+    }
+    /** Version of a direct dep, or undefined if it's not a direct dep. */
+    directVersion(pkg) {
+        const child = this.resolveDep(this.root.key, pkg);
+        return child ? this.nodes.get(child)?.version : undefined;
+    }
+    /** Returns the set of every distinct package name in the graph. */
+    packageNames() {
+        const out = new Set();
+        for (const node of this.nodes.values()) {
+            if (!node.isRoot)
+                out.add(node.name);
+        }
+        return out;
+    }
+    /**
+     * Find the shortest chain of dependency names from any direct dep to
+     * an installation of `vulnerablePkg`.
+     *
+     * Returns `null` when:
+     *   - the vulnerable package isn't installed at all, or
+     *   - the BFS exhausts the graph without finding a route (shouldn't
+     *     happen if the lockfile is internally consistent).
+     */
+    findRootCause(vulnerablePkg) {
+        const vulnNode = this.findInstalledNode(vulnerablePkg);
+        if (!vulnNode)
+            return null;
+        // Direct dep? No further work — the "chain" is just the package itself.
+        if (this.isDirect(vulnerablePkg)) {
+            return {
+                rootPackage: vulnerablePkg,
+                rootInstalledVersion: vulnNode.version,
+                chain: [vulnerablePkg],
+                isDirect: true,
+            };
+        }
+        // BFS from every direct dep, taking the first chain that reaches a
+        // node whose `name === vulnerablePkg`. We keep a parent map keyed
+        // by node-key so we can walk back to the root once we find a hit.
+        // Tracking visited *nodes* (by key) prevents cycles and keeps the
+        // search bounded by the lockfile size.
+        const parent = new Map(); // childKey → parentKey ('' marks a root entry)
+        const queue = [];
+        for (const directName of Object.keys(this.root.deps)) {
+            const childKey = this.resolveDep(this.root.key, directName);
+            if (!childKey || parent.has(childKey))
+                continue;
+            parent.set(childKey, null);
+            queue.push(childKey);
+        }
+        while (queue.length > 0) {
+            const curKey = queue.shift();
+            const node = this.nodes.get(curKey);
+            if (!node)
+                continue;
+            if (node.name === vulnerablePkg) {
+                const chain = [];
+                let cursor = curKey;
+                while (cursor !== null) {
+                    const n = this.nodes.get(cursor);
+                    if (n)
+                        chain.unshift(n.name);
+                    cursor = parent.get(cursor) ?? null;
+                }
+                const rootName = chain[0] ?? vulnerablePkg;
+                return {
+                    rootPackage: rootName,
+                    rootInstalledVersion: this.directVersion(rootName) ?? 'unknown',
+                    chain,
+                    isDirect: false,
+                };
+            }
+            for (const depName of Object.keys(node.deps)) {
+                const nextKey = this.resolveDep(curKey, depName);
+                if (!nextKey || parent.has(nextKey))
+                    continue;
+                parent.set(nextKey, curKey);
+                queue.push(nextKey);
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve `parentKey`'s declared dep `depName` to the lockfile entry
+     * that actually fulfils it. npm's hoist rule is "nearest ancestor with
+     * a matching `node_modules/<name>` wins" — we walk back up by trimming
+     * the path one segment at a time until we hit a match.
+     */
+    resolveDep(parentKey, depName) {
+        const cacheKey = `${parentKey}::${depName}`;
+        const hit = this.childCache.get(cacheKey);
+        if (hit !== undefined)
+            return hit[0] ?? null;
+        // Direct attempt: `<parentKey>/node_modules/<depName>`.
+        let cursor = parentKey;
+        while (true) {
+            const candidate = cursor
+                ? `${cursor}/node_modules/${depName}`
+                : `node_modules/${depName}`;
+            if (this.nodes.has(candidate)) {
+                this.childCache.set(cacheKey, [candidate]);
+                return candidate;
+            }
+            if (!cursor)
+                break;
+            // Strip the last `node_modules/<x>` segment, if any.
+            const idx = cursor.lastIndexOf('/node_modules/');
+            cursor = idx === -1 ? '' : cursor.slice(0, idx);
+        }
+        this.childCache.set(cacheKey, []);
+        return null;
+    }
+    /**
+     * Find *some* installation of `pkg`. We prefer a hoisted top-level
+     * one (most common); falling back to the first nested copy found.
+     */
+    findInstalledNode(pkg) {
+        const top = this.nodes.get(`node_modules/${pkg}`);
+        if (top)
+            return top;
+        for (const node of this.nodes.values()) {
+            if (!node.isRoot && node.name === pkg)
+                return node;
+        }
+        return null;
+    }
+}
+/**
+ * Pull the package name from a lockfile key. Handles scoped packages
+ * (`node_modules/@scope/name`) and nested ones
+ * (`node_modules/foo/node_modules/@scope/bar`).
+ */
+function nameFromKey(key) {
+    const idx = key.lastIndexOf('node_modules/');
+    if (idx === -1)
+        return null;
+    const tail = key.slice(idx + 'node_modules/'.length);
+    if (!tail)
+        return null;
+    return tail; // `@scope/name` or `name`
+}
+//# sourceMappingURL=lockfile-graph.js.map

package/dist/security/lockfile-graph.js.map

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

package/dist/security/npm-audit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `npm audit --json` runner.
+ *
+ * Spawns the host project's `npm audit` in a child process, captures
+ * stdout, and normalises the result into `DependencyFinding[]` so the
+ * agent doesn't have to know about npm's wire format anywhere else.
+ *
+ * Design constraints:
+ *   - **Async only.** This runs inside the host's process; blocking the
+ *     event loop with `execSync` would freeze the host server.
+ *   - **Bounded.** We cap stdout at 16 MB and impose a 30 s wall timeout
+ *     to keep a misbehaving npm install from hanging Studio forever.
+ *   - **Defensive.** `npm audit` writes useful JSON to stdout even when
+ *     it exits 1 (the convention is "exit 1 means vulns were found").
+ *     We treat exit codes 0 and 1 as success.
+ *
+ * The runner is decoupled from the engine: it returns a structured
+ * result plus a `state` value the engine maps onto `scanState.audit`.
+ */
+import type { DependencyFinding } from '../types/index.js';
+/**
+ * Per-package raw `fixAvailable` data lifted from npm audit's report,
+ * indexed by package name. Used by the fix-resolver to decide whether
+ * a finding can be cleared by `npm audit fix`, `npm audit fix --force`,
+ * or a manual `npm install`.
+ *
+ * npm's `fixAvailable` is tri-modal:
+ *
+ *   - `false`       → no upstream fix exists.
+ *   - `true`        → `npm audit fix` can resolve it, but npm declines
+ *                     to commit to a specific target version (typical
+ *                     for transitive vulns where the root upgrade is
+ *                     `audit-fix`'s choice).
+ *   - `{ name, version, isSemVerMajor }` → exact target.
+ *
+ * We keep all three cases distinct here so the fix-resolver can produce
+ * the right command for each. Kept separate from the public
+ * `DependencyFinding` shape so the agent doesn't leak npm's wire format
+ * into the WS protocol.
+ */
+export type AuditFixAvailability = {
+    kind: 'specific';
+    name: string;
+    version: string;
+    isSemVerMajor: boolean;
+} | {
+    kind: 'auto';
+} | {
+    kind: 'none';
+};
+export interface NpmAuditResult {
+    state: 'ok' | 'error' | 'missing-lockfile';
+    /** Empty on `missing-lockfile` / `error`. */
+    findings: DependencyFinding[];
+    /** Raw `fixAvailable` info keyed by *vulnerable package name*. */
+    fixAvailability: Map<string, AuditFixAvailability>;
+    /** Short, user-facing error message when state === 'error'. */
+    error?: string;
+}
+/**
+ * Run `npm audit --json` in `cwd` and return findings. The function is
+ * resilient to npm not being installed, the project missing a
+ * lockfile, or audit returning malformed JSON — every error path
+ * yields a structured `NpmAuditResult` instead of throwing.
+ */
+export declare function runNpmAudit(cwd: string): Promise<NpmAuditResult>;
+//# sourceMappingURL=npm-audit.d.ts.map

package/dist/security/npm-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-audit.d.ts","sourceRoot":"","sources":["../../src/security/npm-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,mBAAmB,CAAC;AAO3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,IAAI,GAAG,OAAO,GAAG,kBAAkB,CAAC;IAC3C,6CAA6C;IAC7C,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,kEAAkE;IAClE,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACnD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAmCD;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAoDtE"}