mindweave 0.0.1 → 2.1.2

package/dist/tools/search.js

@@ -0,0 +1,121 @@
+import { grepDef, GREP_MAX_OUTPUT_LINES } from "./grep.js";
+import { globDef, GLOB_MAX_RESULTS } from "./glob.js";
+import { listDir, MAX_ENTRIES } from "./listDir.js";
+export const search = {
+    name: "search",
+    readOnly: true,
+    description: "Find things in the project. Pass `pattern` to search file CONTENTS with a regular " +
+        "expression, or `files` to find files by PATH, or both to search contents only " +
+        "within files whose path matches — which saves a separate lookup first. Pass " +
+        "NEITHER to LIST what is there, one level deep.\n" +
+        "CONTENTS (`pattern`): `output_mode` is 'files_with_matches' (default, just paths), " +
+        "'content' (matching lines), or 'count'. Avoid lookahead, lookbehind and " +
+        "backreferences; the search engine rejects them. Character classes, groups, " +
+        "alternation and anchors are all fine. `multiline` lets a pattern cross line breaks, " +
+        "which is how you find a construct that is not on one line (a signature and its body, " +
+        `an object literal, a JSX block). Output stops after ${GREP_MAX_OUTPUT_LINES} matching ` +
+        "lines and tells you the `offset` to pass for the next page — a capped search is " +
+        "something to CONTINUE, not a reason to start reading whole files. Use `after` when " +
+        "you want what follows a match (a declaration's body) rather than a symmetric window.\n" +
+        `PATHS (\`files\`): a glob like \`**/*.ts\` or \`src/**/*.{ts,tsx}\`, matched against ` +
+        "each file's path RELATIVE to the root being searched, so a leading slash does not " +
+        `work. Results stop after ${GLOB_MAX_RESULTS} paths and say so when they do.\n` +
+        "LISTING (neither argument): the immediate contents of `path`, one level, not " +
+        "recursive — or of every session root if you give no path. Entries come directories " +
+        "first, then alphabetically. A trailing slash means a directory. `(symlink)` marks a " +
+        "link, and it still gets the slash when it points at a directory; `(broken symlink)` " +
+        "means the target is gone. `(skipped by search)` marks a directory that is really " +
+        "there but that the two searches above will not descend into, which is why a file " +
+        `inside it can exist and never appear in a search. Listings stop after ${MAX_ENTRIES} ` +
+        "entries and say how many were left out.\n" +
+        "Searches every session root unless `path` (a file, directory, or root label) is given.\n" +
+        "WHAT IS NOT SEARCHED, so an empty result is NOT proof something is absent: anything " +
+        "the project's .gitignore excludes (build output, dist, generated code), node_modules " +
+        "and .git always, and secrets (.env, keys) plus other coding agents' data, which are " +
+        "refused rather than missing. If what you need lives in one of those, read the file " +
+        "directly instead of concluding it is not there. LISTING is the exception and the " +
+        "reason to reach for it: it reports the DISK, so ignored build output, secrets and " +
+        "other agents' folders all appear. Seeing something listed is not a promise you may " +
+        "open it — read_file still refuses secrets and asks before another agent's data. " +
+        "Treat a listing as evidence of what exists, and let the read decide what you see.\n" +
+        "To find the uses of a symbol you can NAME, try references first: it reads parsed " +
+        "code rather than raw text, so a mention in a comment or a string is not a match. " +
+        "Come back here when it reports a name-level answer and exact identity matters.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            pattern: {
+                type: "string",
+                description: "Regular expression to search file CONTENTS for. Omit to search by path only.",
+            },
+            files: {
+                type: "string",
+                description: 'Glob for file paths (e.g. "**/*.ts"). Alone: find files by name. With `pattern`: ' +
+                    "search contents only inside these files.",
+            },
+            path: {
+                type: "string",
+                description: "File, directory, or root label to search — or, with neither `pattern` nor " +
+                    "`files`, the directory to list. Defaults to all session roots.",
+            },
+            output_mode: {
+                type: "string",
+                enum: ["files_with_matches", "content", "count"],
+                description: "Contents search only. What to return. Defaults to files_with_matches.",
+            },
+            ignore_case: { type: "boolean", description: "Contents search only. Case-insensitive." },
+            context: {
+                type: "integer",
+                minimum: 0,
+                description: "Contents search only. Lines of context around each match (content mode).",
+            },
+            before: {
+                type: "integer",
+                minimum: 0,
+                description: "Lines to show BEFORE each match (content mode). Overrides `context` on that side.",
+            },
+            after: {
+                type: "integer",
+                minimum: 0,
+                description: "Lines to show AFTER each match (content mode). Overrides `context` on that side.",
+            },
+            multiline: {
+                type: "boolean",
+                description: "Let the pattern span line breaks, with `.` matching newlines too. Off by default. " +
+                    "Use it for constructs that are not on one line — a function signature and its body, " +
+                    "an object literal, a JSX block.",
+            },
+            head_limit: {
+                type: "integer",
+                minimum: 0,
+                description: "Return at most this many results. 0 means no limit. Defaults to the cap below.",
+            },
+            offset: {
+                type: "integer",
+                minimum: 0,
+                description: "Skip this many results first — page through a capped search instead of narrowing it. " +
+                    "The result tells you the offset to pass next.",
+            },
+        },
+    },
+    async execute(args, ctx) {
+        const pattern = typeof args.pattern === "string" ? args.pattern.trim() : "";
+        const files = typeof args.files === "string" ? args.files.trim() : "";
+        // Contents search. `files` becomes the path filter it always was under grep's own
+        // `glob` argument — the merge is what makes that reachable without knowing two tools.
+        //
+        // Neither argument is no longer an error: nothing to match by means "show me what
+        // is here", which is what a model reaching for a listing meant anyway.
+        const result = pattern
+            ? await grepDef.execute({ ...args, pattern, ...(files ? { glob: files } : {}) }, ctx)
+            : files
+                ? await globDef.execute({ ...args, pattern: files }, ctx)
+                : await listDir.execute({ ...(args.path ? { path: args.path } : {}) }, ctx);
+        // Quiet is applied HERE, on every path including errors, rather than inside either
+        // implementation. One tool, one display policy — and a failed search is exactly the
+        // row most likely to creep back onto the screen if each branch decided for itself.
+        return { ...result, quiet: true };
+    },
+};
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

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

package/dist/tools/sessionTools.js

@@ -0,0 +1,187 @@
+import { anchorOf } from "./paths.js";
+import { listSessions, loadSessionNotes, loadTranscript } from "../memory/store.js";
+import { fail } from "./results.js";
+/** How many sessions to list at once unless asked for more. */
+const DEFAULT_LIMIT = 10;
+/** Characters of transcript to return before clipping — a transcript is unbounded. */
+const MAX_TRANSCRIPT_CHARS = 20_000;
+/**
+ * One tool, two levels of specificity: no `id` lists, an `id` reads.
+ *
+ * These were `list_sessions` and `read_session`. Same store, same access pattern, and
+ * the second was almost always a direct follow-up to the first — so the split bought
+ * the model a routing decision and cost two advertised schemas to describe one idea.
+ */
+export const sessionsTool = {
+    name: "sessions",
+    deferred: true,
+    readOnly: true,
+    description: "Look at your own past sessions in this project. Use this whenever the user refers " +
+        "to earlier work ('last session', 'what did we do', 'the bug we fixed yesterday') — " +
+        "you have this history, so look it up instead of guessing or saying you cannot see " +
+        "it.\n" +
+        "With no `id` it LISTS past sessions, newest first: when each ran, what the user " +
+        "opened with, what they last asked, how long it went. Cheap — no transcripts are " +
+        "opened.\n" +
+        "With an `id` it READS that session, returning its maintained notes (its own running " +
+        "summary of the work and where it got to, which is what 'what did we do' means). If " +
+        "that session kept no notes you get its raw exchange instead, in the same call, so " +
+        "one call always answers. Pass `id: 'latest'` for the most recent past session, and " +
+        "`full: true` only when you specifically want the raw exchange over the notes.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            id: {
+                type: "string",
+                description: "A session id to read, or 'latest' for the most recent. Omit entirely to list sessions instead.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: 50,
+                description: `Listing only: how many to list (default ${DEFAULT_LIMIT}, newest first).`,
+            },
+            full: {
+                type: "boolean",
+                description: "Reading only: return the raw transcript instead of the notes. Large.",
+            },
+        },
+    },
+    async execute(args, ctx) {
+        // The dispatch: naming a session means read it, otherwise list what there is.
+        const wanted = typeof args.id === "string" ? args.id.trim() : "";
+        return wanted ? readOne(args, ctx, wanted) : listAll(args, ctx);
+    },
+};
+async function listAll(args, ctx) {
+    const root = anchorOf(ctx);
+    const all = await listSessions(root);
+    const past = all.filter((m) => m.id !== ctx.sessionId);
+    if (past.length === 0) {
+        return { output: "No earlier sessions are saved for this project.", summary: "no past sessions", quiet: true };
+    }
+    const limit = clampInt(args.limit, DEFAULT_LIMIT, 1, 50);
+    const shown = past.slice(0, limit);
+    const lines = shown.map(describe);
+    const more = past.length > shown.length ? `\n\n(${past.length - shown.length} older, raise \`limit\` to see them.)` : "";
+    return {
+        output: `Your past sessions in this project, newest first. Call sessions again with an ` +
+            `id for what happened in one:\n\n${lines.join("\n\n")}${more}`,
+        summary: `${past.length} past session${past.length === 1 ? "" : "s"}`,
+        // Looking up its own history is bookkeeping, not news — same call made for
+        // compaction/verification. The answer shows up in the reply itself.
+        quiet: true,
+    };
+}
+async function readOne(args, ctx, wanted) {
+    const root = anchorOf(ctx);
+    const all = await listSessions(root);
+    const past = all.filter((m) => m.id !== ctx.sessionId);
+    if (past.length === 0) {
+        return { output: "No earlier sessions are saved for this project.", summary: "no past sessions", quiet: true };
+    }
+    // "latest" is the explicit spelling of what used to be "omit the id". Omitting it
+    // now means LIST, so the shorthand needs a word of its own rather than a gap.
+    const meta = wanted === "latest" ? past[0] : past.find((m) => m.id === wanted);
+    if (!meta) {
+        return fail(`no saved session with id '${wanted}'. Call sessions with no id to see which ids exist.`);
+    }
+    const header = describe(meta);
+    if (args.full === true) {
+        const transcript = await loadTranscript(root, meta.id);
+        return {
+            output: `${header}\n\n${renderTranscript(transcript ?? [])}`,
+            summary: `session ${short(meta.id)} (transcript)`,
+            quiet: true,
+        };
+    }
+    const notes = await loadSessionNotes(root, meta.id);
+    if (!notes) {
+        // No notes → answer anyway, from the transcript, in THIS call. Telling the model
+        // to come back with full:true bought nothing: it spent an extra round trip to
+        // reach the same clipped transcript we can already return, and a model that reads
+        // "call again" as "that failed" answers from the project files instead — the exact
+        // deflection these tools exist to stop. The render is bounded, so this is safe.
+        const transcript = await loadTranscript(root, meta.id);
+        const body = renderTranscript(transcript ?? []);
+        return {
+            output: `${header}\n\nThat session kept no notes (it may have been short), so this is its ` +
+                `raw exchange instead:\n\n${body}`,
+            summary: `session ${short(meta.id)} (transcript, no notes)`,
+            quiet: true,
+        };
+    }
+    return {
+        output: `${header}\n\nWhat that session recorded about its own work:\n\n${notes}`,
+        summary: `session ${short(meta.id)} (notes)`,
+        // Reading its own history is bookkeeping, not news — same as the listing above.
+        // The answer is what shows up, not the lookup itself.
+        quiet: true,
+    };
+}
+/** One session as a compact block: id, when, size, and the prompts that bracket it. */
+function describe(meta) {
+    const parts = [
+        `id: ${meta.id}`,
+        `when: ${timeAgo(meta.updatedAt)} (${new Date(meta.updatedAt).toISOString().slice(0, 16).replace("T", " ")})`,
+        `length: ${meta.entryCount} messages`,
+        `opened with: ${clip(meta.firstPrompt)}`,
+    ];
+    // The last prompt is only worth a line when it differs — a one-exchange session
+    // would otherwise print the same text twice.
+    if (meta.lastPrompt && meta.lastPrompt.trim() !== meta.firstPrompt.trim()) {
+        parts.push(`last asked: ${clip(meta.lastPrompt)}`);
+    }
+    return parts.join("\n");
+}
+/** Render a saved transcript readably, clipped — transcripts have no size bound. */
+function renderTranscript(entries) {
+    const body = entries
+        .filter((e) => e.role === "user" || e.role === "assistant")
+        .map((e) => `${e.role === "user" ? "User" : "You"}: ${e.content.trim()}`)
+        .filter((line) => line.length > 6)
+        .join("\n\n");
+    if (!body)
+        return "(that session's transcript is empty)";
+    return body.length > MAX_TRANSCRIPT_CHARS
+        ? body.slice(0, MAX_TRANSCRIPT_CHARS) + "\n\n… (transcript clipped)"
+        : body;
+}
+/** "3 days ago" / "2 hours ago" — how a human refers to a past session. */
+export function timeAgo(when, now = Date.now()) {
+    const seconds = Math.max(0, Math.round((now - when) / 1000));
+    if (seconds < 60)
+        return "just now";
+    const units = [
+        [60, "minute"],
+        [3600, "hour"],
+        [86400, "day"],
+        [604800, "week"],
+    ];
+    let label = "minute";
+    let size = 60;
+    for (const [unitSeconds, name] of units) {
+        if (seconds >= unitSeconds) {
+            size = unitSeconds;
+            label = name;
+        }
+    }
+    const n = Math.floor(seconds / size);
+    return `${n} ${label}${n === 1 ? "" : "s"} ago`;
+}
+function short(id) {
+    return id.slice(0, 8);
+}
+function clip(text, max = 140) {
+    const line = (text ?? "").replace(/\s+/g, " ").trim();
+    if (!line)
+        return "(nothing recorded)";
+    return line.length > max ? line.slice(0, max - 1) + "…" : line;
+}
+function clampInt(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+//# sourceMappingURL=sessionTools.js.map

package/dist/tools/sessionTools.js.map

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

package/dist/tools/shellCheckpoint.js

@@ -0,0 +1,123 @@
+/**
+ * shellCheckpoint.ts — bringing shell-caused file changes into /undo.
+ *
+ * `run_command` was the one mutation path that bypassed checkpoints entirely. The
+ * write tools snapshot a file before they touch it, so /undo can put it back; a shell
+ * command that rewrites the same file through a formatter, a codemod, or an improvised
+ * one-off script left nothing to restore. The turn was flagged as "a shell ran" and the
+ * user was told, in effect, that some unspecified part of it could not be undone.
+ *
+ * That gap matters more than it looks, because improvisation via run_command is a
+ * FEATURE — a capable model covers missing capabilities by writing a script, and the
+ * tool-trimming work leans on that being possible. Every capability reached that way was
+ * landing outside the safety net that the equivalent dedicated tool sits inside.
+ *
+ * ── WHAT THIS CAN AND CANNOT DO, PRECISELY ──────────────────────────────────────
+ *
+ * Undo needs the bytes from BEFORE the change, and after a command has run they are
+ * gone. So the only honest fix is to snapshot first, and snapshotting the whole working
+ * tree before every command is not affordable.
+ *
+ * The bounded thing that IS affordable is the read ledger: the files this session has
+ * actually opened. That set is capped, usually small, and warm in the OS cache — and it
+ * is overwhelmingly the set an improvised script aims at, because the model writes the
+ * script about the files it has been working on. So those files get a real, restorable
+ * checkpoint.
+ *
+ * Files the session never read are not covered, and that is not papered over: they are
+ * counted and reported, so /undo says what it did not cover rather than implying it
+ * covered everything. An honest gap beats a silent one.
+ */
+import { promises as fs } from "node:fs";
+/** Per-file ceiling for a pre-command snapshot. Above this, skip rather than stall. */
+const MAX_SNAPSHOT_FILE_BYTES = 512 * 1024;
+/** Total ceiling across one snapshot, so a big ledger cannot pause a command. */
+const MAX_SNAPSHOT_TOTAL_BYTES = 8 * 1024 * 1024;
+/**
+ * Commands that cannot change files, so the snapshot is skipped entirely.
+ *
+ * Deliberately a SMALL allow-list of obviously-read-only starts, not an attempt to
+ * classify shell commands in general. Getting this wrong in the permissive direction
+ * silently drops undo coverage, so anything unrecognised is treated as mutating and
+ * pays for a snapshot it may not need. A wasted stat is cheap; a lost file is not.
+ */
+const READ_ONLY_STARTS = [
+    "cat", "head", "tail", "less", "more", "ls", "dir", "pwd", "echo", "which", "type",
+    "git status", "git log", "git diff", "git show", "git branch",
+    "node --version", "npm --version", "npm ls", "npm list",
+];
+export function looksReadOnly(command) {
+    const c = command.trim().toLowerCase();
+    // Anything chaining or redirecting can write, whatever it starts with.
+    if (/[>|;&]/.test(c))
+        return false;
+    return READ_ONLY_STARTS.some((p) => c === p || c.startsWith(`${p} `));
+}
+/**
+ * Capture the ledger's files before a command runs.
+ *
+ * Failures are silent per file: a file that vanished or cannot be read is simply not
+ * covered, which is the same outcome as not being in the ledger. This must never be
+ * the reason a command does not run.
+ */
+export async function snapshotBeforeCommand(ctx) {
+    const snapshot = new Map();
+    if (!ctx.checkpoints || ctx.reads.size === 0)
+        return snapshot;
+    let total = 0;
+    for (const absPath of ctx.reads.keys()) {
+        try {
+            const stat = await fs.stat(absPath);
+            if (!stat.isFile() || stat.size > MAX_SNAPSHOT_FILE_BYTES)
+                continue;
+            if (total + stat.size > MAX_SNAPSHOT_TOTAL_BYTES)
+                break;
+            const content = await fs.readFile(absPath, "utf8");
+            snapshot.set(absPath, { content, mtimeMs: stat.mtimeMs, size: stat.size });
+            total += stat.size;
+        }
+        catch {
+            // Gone, unreadable, or binary — not coverable, and not worth failing over.
+        }
+    }
+    return snapshot;
+}
+/**
+ * Compare the tree against the snapshot and check in whatever the command changed.
+ *
+ * Mtime AND size are both compared, for the same reason the edit-freshness gate does:
+ * a coarse filesystem clock hides a fast rewrite, and a same-size change (a flipped
+ * boolean, a renamed identifier) hides from a size check. Either signal alone misses
+ * real cases.
+ */
+export async function captureAfterCommand(ctx, before) {
+    const captured = [];
+    const uncaptured = [];
+    if (!ctx.checkpoints)
+        return { captured, uncaptured };
+    for (const [absPath, prior] of before) {
+        let now;
+        try {
+            const stat = await fs.stat(absPath);
+            if (stat.mtimeMs === prior.mtimeMs && stat.size === prior.size)
+                continue;
+            now = { content: await fs.readFile(absPath, "utf8"), changed: true };
+        }
+        catch {
+            // Deleted by the command: still a change, and one undo can reverse by writing
+            // the old bytes back.
+            now = { content: null, changed: true };
+        }
+        if (!now.changed)
+            continue;
+        if (now.content === prior.content)
+            continue; // touched but identical: nothing to undo
+        ctx.checkpoints.backup(absPath, prior.content, now.content ?? "");
+        captured.push(absPath);
+    }
+    // Anything the session had never read is outside the snapshot by construction. We
+    // cannot enumerate it without walking the tree, so it is reported as a category
+    // rather than a list — see noteShell, which still fires for exactly this reason.
+    return { captured, uncaptured };
+}
+//# sourceMappingURL=shellCheckpoint.js.map

package/dist/tools/shellCheckpoint.js.map

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

package/dist/tools/shellLint.js

@@ -0,0 +1,102 @@
+/**
+ * shellLint.ts — a conservative advisory for bash-isms in a Windows PowerShell
+ * command (pure, so it's unit-tested).
+ *
+ * Models are overwhelmingly bash-trained, but Mindweave runs commands in
+ * powershell.exe (5.1) on Windows, where some bash constructs silently break:
+ * `&&`/`||` are parse errors, `2>/dev/null` isn't a thing, and tools like `grep`
+ * / `sed` / `head` don't exist. This returns a short note the caller appends to
+ * the command result so the model corrects itself next time.
+ *
+ * Deliberately conservative — it must NOT flag valid PowerShell. In particular
+ * `ls`, `cat`, `rm`, `cp`, `mv`, `echo`, `pwd`, `sort` are real PowerShell
+ * ALIASES and work fine, so they are never flagged. Only genuinely-broken
+ * constructs are. Quoted substrings are ignored to avoid matching inside strings.
+ */
+/** GNU/bash tools with no PowerShell alias (so they fail on a stock Windows box). */
+const BASH_ONLY_TOOLS = ["grep", "sed", "awk", "head", "tail", "touch", "which", "wc"];
+/**
+ * The subset of bash-isms that are GUARANTEED Windows PowerShell 5.1 PARSE ERRORS —
+ * the command cannot run at all. Used as a PRE-execution gate so a run isn't wasted on
+ * a command that will only ever fail to parse. ONLY `&&`/`||` qualify: everything else
+ * the advisory notes (missing tools, `/dev/null`, `export`) actually executes — and a
+ * tool like `grep` may even be on PATH — so those must stay advisory, never blocked.
+ * Returns a fix hint (including the `shell:'cmd'` escape hatch) or null.
+ */
+export function powershellParseError(command) {
+    const bare = command.replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
+    if (/\&\&|\|\|/.test(bare)) {
+        return ("`&&`/`||` are parse errors in Windows PowerShell — this command won't run. Join with `;` " +
+            "(use `if`/`$?` to stop on failure), or pass shell:'cmd' to run it in cmd.exe, which supports `&&`/`||`.");
+    }
+    return null;
+}
+/**
+ * PowerShell automatic variables that are read-only/constant — assigning to one throws
+ * "Cannot overwrite variable X because it is read-only or constant" and the command dies.
+ * `$pid` is the one models reach for constantly (parsing a PID out of netstat), which is
+ * exactly the wall that turned a "start the app" request into a 90-second flailing loop.
+ * This is the constant set from PowerShell's own `AvoidAssignmentToAutomaticVariable`
+ * rule that hard-errors on assignment ($null is excluded — assigning it is a silent no-op).
+ */
+const PS_READONLY_VARS = ["PID", "Host", "ExecutionContext", "PSHOME", "ShellId", "true", "false"];
+/**
+ * A guaranteed runtime failure: assigning to a read-only automatic variable. Detected
+ * pre-execution (like the `&&` parse gate) so the run isn't wasted — the model gets the
+ * fix immediately instead of firing the command, reading the error, and retrying. Only
+ * ASSIGNMENT is flagged (`$pid = …`), never a read/compare (`if ($pid -eq …)`). Quoted
+ * spans are blanked first so a literal inside a string never trips it. Returns the fix
+ * hint or null.
+ */
+export function powershellReservedAssignmentReason(command) {
+    const bare = command.replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
+    const re = new RegExp(`\\$(${PS_READONLY_VARS.join("|")})\\s*\\+?=(?!=)`, "i");
+    const m = bare.match(re);
+    if (!m)
+        return null;
+    const name = m[1];
+    return (`\`$${name}\` is a read-only automatic variable in Windows PowerShell — assigning to it fails with ` +
+        `"Cannot overwrite variable ${name} because it is read-only or constant." Use a different variable ` +
+        `name (e.g. \`$procId\` instead of \`$pid\`).`);
+}
+/**
+ * A one-line advisory if `command` contains a clear bash-ism that breaks in
+ * Windows PowerShell, else null. `command` is the raw command the model sent.
+ */
+export function powershellLintReason(command) {
+    // Blank out quoted spans so we don't match inside string literals.
+    const bare = command
+        .replace(/'[^']*'/g, " ")
+        .replace(/"[^"]*"/g, " ");
+    const problems = [];
+    if (/\&\&|\|\|/.test(bare)) {
+        problems.push("`&&`/`||` are parse errors in Windows PowerShell 5.1 — run separate commands or join with `;` (use `if`/`$?` to stop on failure)");
+    }
+    if (/\/dev\/null/.test(bare)) {
+        problems.push("`/dev/null` doesn't exist — redirect with `2>$null` / `>$null`");
+    }
+    // A bash-only tool in command position: at the start, or right after ; | & (
+    const toolRe = new RegExp(`(^|[;|&(])\\s*(${BASH_ONLY_TOOLS.join("|")})\\b`, "i");
+    const m = bare.match(toolRe);
+    if (m) {
+        const tool = m[2].toLowerCase();
+        const suggestion = {
+            grep: "Select-String",
+            sed: "-replace / Get-Content",
+            awk: "Select-Object / ForEach-Object",
+            head: "Get-Content -TotalCount N",
+            tail: "Get-Content -Tail N",
+            touch: "New-Item",
+            which: "(Get-Command x).Source",
+            wc: "Measure-Object",
+        };
+        problems.push(`\`${tool}\` isn't available in PowerShell — use \`${suggestion[tool]}\` (or Mindweave's grep/read tools)`);
+    }
+    if (/(^|[;|&(])\s*export\s+\w+=/.test(bare)) {
+        problems.push("bash `export VAR=...` doesn't work — use `$env:VAR = '...'`");
+    }
+    if (problems.length === 0)
+        return null;
+    return `Note: this looks like bash, but the shell is Windows PowerShell. ${problems.join("; ")}.`;
+}
+//# sourceMappingURL=shellLint.js.map

package/dist/tools/shellLint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shellLint.js","sourceRoot":"","sources":["../../src/tools/shellLint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qFAAqF;AACrF,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAEvF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACvE,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,CACL,2FAA2F;YAC3F,yGAAyG,CAC1G,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnG;;;;;;;GAOG;AACH,MAAM,UAAU,kCAAkC,CAAC,OAAe;IAChE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC/E,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACnB,OAAO,CACL,MAAM,IAAI,0FAA0F;QACpG,8BAA8B,IAAI,kEAAkE;QACpG,8CAA8C,CAC/C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,mEAAmE;IACnE,MAAM,IAAI,GAAG,OAAO;SACjB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAE5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,kIAAkI,CAAC,CAAC;IACpJ,CAAC;IACD,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAClF,CAAC;IACD,6EAA6E;IAC7E,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,kBAAkB,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClF,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC;QACN,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC;QACjC,MAAM,UAAU,GAA2B;YACzC,IAAI,EAAE,eAAe;YACrB,GAAG,EAAE,wBAAwB;YAC7B,GAAG,EAAE,gCAAgC;YACrC,IAAI,EAAE,2BAA2B;YACjC,IAAI,EAAE,qBAAqB;YAC3B,KAAK,EAAE,UAAU;YACjB,KAAK,EAAE,wBAAwB;YAC/B,EAAE,EAAE,gBAAgB;SACrB,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,KAAK,IAAI,4CAA4C,UAAU,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IAC5H,CAAC;IACD,IAAI,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,oEAAoE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACpG,CAAC"}