mindweave 0.0.1 → 2.1.2

package/dist/tools/paths.js

@@ -0,0 +1,225 @@
+/**
+ * paths.ts — the one place tools turn a model-supplied path into a real one.
+ *
+ * Every file tool takes a path from the model that may be absolute or relative,
+ * and must resolve it against the *session* working directory (`ctx.cwd`), not
+ * Node's `process.cwd()` — because `run_command` can move the session's cwd with
+ * `cd`, and a later read/edit must follow it. Keeping this in one helper means
+ * every tool resolves paths the same way.
+ */
+import { promises as fs, realpath as realpathCb } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+/**
+ * The OS's own realpath, not Node's JS reimplementation, and the difference is
+ * load-bearing on Windows.
+ *
+ * `fs.realpath` resolves symlinks but leaves an 8.3 SHORT path exactly as it found
+ * it, so `C:\Users\RUNNER~1\...` and `C:\Users\runneradmin\...` both survive as
+ * distinct strings for one directory. The native call expands short names to their
+ * real on-disk form (and fixes the casing), which is what makes the two comparable.
+ *
+ * This is not exotic: Windows generates a short name for any component over eight
+ * characters, so it happens to every user whose account name is longer than that.
+ * An eleven-character account name such as a CI runner's `runneradmin` hits it on the
+ * first path it builds, while a short one never can — which is exactly the kind of
+ * difference between two machines that this function exists to erase.
+ *
+ * There is no `.native` on the promises API, so the callback form is promisified.
+ */
+const realpathNative = promisify(realpathCb.native);
+import { addFocus } from "./focus.js";
+import { noteScopePath } from "../governor/scope.js";
+/**
+ * Resolve a directory to its PHYSICAL path, following symlinks.
+ *
+ * Every root and every recorded cwd goes through this once, on the way in, so the
+ * whole session speaks one form of every path.
+ *
+ * Why it has to exist: `run_command` records where a command ended up using
+ * `pwd -P`, which is physical. macOS puts a great deal behind symlinks — `/tmp` is
+ * `/private/tmp`, and `os.tmpdir()` sits under `/private/var` — so a session opened
+ * at a logical path and a cwd read back as a physical one describe the same
+ * directory with different strings. Nothing compares equal after that: the session
+ * appears to have moved on a command that never ran `cd`, and because the recorded
+ * cwd is then no longer under the session root, `relativize` gives up and every path
+ * the model sees turns absolute.
+ *
+ * Canonicalising both sides is the fix, and it belongs here rather than at the call
+ * site: this module is already the one place a path becomes real.
+ *
+ * Degrades to the input when the path cannot be resolved (it may not exist yet), so
+ * this can be applied unconditionally.
+ */
+export async function canonicalRoot(path) {
+    try {
+        return await realpathNative(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * The session's roots, primary first. A single-root session is the common case;
+ * `/include` adds more (e.g. a backend + a frontend). Falls back to the live cwd
+ * when none are set (bare test contexts), so single-root behavior is unchanged.
+ */
+export function rootsOf(ctx) {
+    return ctx.roots && ctx.roots.length > 0 ? ctx.roots : [ctx.cwd];
+}
+/**
+ * The immutable session anchor — the primary root, which never moves. `run_command`
+ * shifts `ctx.cwd` with `cd`, but the anchor stays put, so file tools resolve relative
+ * paths against a fixed base instead of a shell cwd that may have wandered into a
+ * subdirectory. File tools never follow the shell cwd;
+ * without it, a `cd src-tauri` before a build makes a later `edit("App.css")`
+ * resolve to `…/src-tauri/App.css` and fail "file not found" on a file that plainly
+ * exists — the exact bug this decoupling kills.
+ */
+export function anchorOf(ctx) {
+    return rootsOf(ctx)[0];
+}
+/** True when more than one root is in play — the only time paths carry a label. */
+export function isMultiRoot(ctx) {
+    return rootsOf(ctx).length > 1;
+}
+/**
+ * A short, unique label for a root — its folder name, disambiguated with the
+ * parent folder if two roots share a name (`api/server` vs `web/server`). Labels
+ * are how a path stays collision-proof across roots: every displayed path is
+ * `label/relative`, and that exact string resolves back to the right root.
+ */
+export function rootLabel(roots, root) {
+    const base = basename(root) || root;
+    const collides = roots.some((r) => r !== root && (basename(r) || r) === base);
+    return collides ? `${basename(dirname(root))}/${base}` : base;
+}
+/** The root that contains `abs`, or null when it's outside every root. */
+function containingRoot(roots, abs) {
+    for (const root of roots) {
+        const rel = relative(root, abs);
+        if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+            return root;
+    }
+    return null;
+}
+/**
+ * Resolve a model-supplied path to an absolute path. Absolute paths pass through;
+ * a relative path resolves against the fixed session anchor (NOT the shell cwd, which
+ * `run_command` may have moved with `cd`) — UNLESS it's `label/…` for a known added
+ * root, which resolves under that root (so the model can reach any root by name without
+ * juggling absolute paths).
+ */
+export function resolvePath(ctx, raw) {
+    if (isAbsolute(raw))
+        return resolve(raw);
+    const roots = rootsOf(ctx);
+    if (roots.length > 1) {
+        const norm = raw.split("\\").join("/");
+        const slash = norm.indexOf("/");
+        const head = slash >= 0 ? norm.slice(0, slash) : norm;
+        const rest = slash >= 0 ? norm.slice(slash + 1) : "";
+        for (const root of roots) {
+            if (rootLabel(roots, root) === head)
+                return resolve(root, rest);
+        }
+    }
+    return resolve(anchorOf(ctx), raw);
+}
+/**
+ * A short, display-friendly form of an absolute path. Single-root: relative to the
+ * live cwd (or absolute when outside it). Multi-root: `label/relative` so a path is
+ * never ambiguous between roots — and that string round-trips back through
+ * `resolvePath`.
+ */
+export function relativize(ctx, abs) {
+    const roots = rootsOf(ctx);
+    if (roots.length <= 1) {
+        // Relative to the fixed anchor, not the moving shell cwd — so a path displays the
+        // same regardless of where a `cd` left the shell, and run_command's "in <dir>" line
+        // shows the shell's location as a clean subpath of the root (e.g. `src-tauri`).
+        const rel = relative(anchorOf(ctx), abs);
+        if (rel === "")
+            return ".";
+        return rel.startsWith("..") ? abs : rel.split("\\").join("/");
+    }
+    const root = containingRoot(roots, abs);
+    if (!root)
+        return abs; // outside all roots — show it absolute
+    const rel = relative(root, abs);
+    const label = rootLabel(roots, root);
+    return rel === "" ? label : `${label}/${rel.split("\\").join("/")}`;
+}
+/**
+ * Decide what a search tool should scan. With an explicit `path`, that one target
+ * (resolved, then expressed as root + subpath so output can be labeled). Without
+ * one: every root in a multi-root session (so "search" means "search everywhere"),
+ * or just the live cwd in the single-root case (unchanged behavior).
+ */
+export function searchUnits(ctx, rawPath) {
+    const roots = rootsOf(ctx);
+    if (rawPath && rawPath !== ".") {
+        const abs = resolvePath(ctx, rawPath);
+        const root = containingRoot(roots, abs) ?? ctx.cwd;
+        const rel = relative(root, abs);
+        return [{ root, sub: rel === "" ? "" : rel.split("\\").join("/") }];
+    }
+    if (roots.length > 1)
+        return roots.map((root) => ({ root, sub: "" }));
+    return [{ root: ctx.cwd, sub: "" }];
+}
+/**
+ * Tell the governor this session has worked in `absPath`, firing any glob-scoped rule
+ * that matches it.
+ *
+ * Called wherever a file enters the read ledger, which is the definition of "the
+ * session touched this". Deliberately separate from `ctx.reads` itself: the ledger is
+ * cleared at a compaction and this must not be, so the two are written together and
+ * forgotten apart.
+ *
+ * A no-op when the session has no governance or no scope (a sub-agent, a test), and
+ * cheap when it has no glob-scoped rules — see scope.ts.
+ */
+export function markScope(ctx, absPath) {
+    const scope = ctx.ruleScope;
+    const rules = ctx.governance?.rules;
+    if (!scope || !rules || rules.length === 0)
+        return;
+    noteScopePath(scope, rules, ctx.governance.forbidden.root, absPath);
+}
+/** Monotonic clock for read/edit recency (drives the working set's LRU ordering). */
+let touchClock = 0;
+export function nextTouch() {
+    return ++touchClock;
+}
+/** Bump a tracked file's recency (and optionally record a focused line span) without
+ *  changing its read state. Used by tools that re-touch a file they already track. */
+export function touch(ctx, absPath, focus) {
+    const rec = ctx.reads.get(absPath);
+    if (!rec)
+        return;
+    rec.touchedAt = nextTouch();
+    if (focus)
+        rec.focus = addFocus(rec.focus, focus);
+}
+/**
+ * Record that a file was just written/edited. It satisfies the read-before-edit gate
+ * (the path is now tracked) and updates recency + the focused region. Marked
+ * `full: false`: an edit hands the model only a WINDOW, not the whole file — the
+ * working set, not this record, is the source of truth for "the model has the current
+ * content." (Marking it `full: true` here is what caused the re-read storm: a later
+ * full read got wrongly deduped, so the model paged the file in ranges instead.)
+ */
+export async function recordWrite(ctx, absPath, focus) {
+    const prev = ctx.reads.get(absPath);
+    markScope(ctx, absPath);
+    const base = { full: false, touchedAt: nextTouch(), focus: addFocus(prev?.focus, focus) };
+    try {
+        const st = await fs.stat(absPath);
+        ctx.reads.set(absPath, { mtimeMs: st.mtimeMs, size: st.size, ...base });
+    }
+    catch {
+        ctx.reads.set(absPath, { mtimeMs: 0, size: 0, ...base });
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/tools/paths.js.map

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

package/dist/tools/posixShell.js

@@ -0,0 +1,123 @@
+/**
+ * posixShell.ts — which shell runs a command on macOS/Linux, and what to say when
+ * the one we got can't do what the model asked for.
+ *
+ * THE PROBLEM THIS FIXES. Commands used to run under a hardcoded `/bin/sh`. On
+ * Debian and Ubuntu — the most common Linux family by a wide margin — `/bin/sh` is
+ * `dash`, a deliberately minimal POSIX shell. Models are overwhelmingly bash-trained,
+ * so a perfectly ordinary command like `if [[ -f x ]]; then …` is a SYNTAX ERROR
+ * there, and the model gets back a terse dash complaint with no indication that the
+ * shell, not the command, is the problem.
+ *
+ * Windows already had both halves of this handled: it runs PowerShell (a real shell,
+ * not the most minimal one available) and `shellLint.ts` tells the model when it has
+ * written a bash-ism. POSIX had neither. This module is the missing half.
+ *
+ * THE FIX, IN TWO LAYERS:
+ *   1. Prefer bash. Nearly every macOS and Linux box has it, so the mismatch simply
+ *      stops existing. This is the cause, and it is fixed rather than reported.
+ *   2. When only a minimal `sh` exists (Alpine, slim containers, busybox), fall back
+ *      to it and lint — the residue is rare, but it should still explain itself
+ *      instead of failing cryptically.
+ *
+ * Deciding once, here, is also what keeps the knowledge in one place: before this,
+ * "which shell" was a string literal in the middle of a request builder.
+ */
+import { accessSync, constants } from "node:fs";
+// `posix.join` deliberately, not the platform-default `join`: every path this module
+// builds is a POSIX path, so it must use forward slashes even when the code is being
+// developed or tested on Windows. The platform-default version silently produced
+// backslashed paths that could never match anything, which is a bug that would only
+// have shown up on the machine least likely to run it.
+import { delimiter, posix } from "node:path";
+/**
+ * Where bash lives, in preference order, before falling back to a PATH lookup.
+ * `/bin/bash` covers mainstream Linux and macOS; `/usr/bin/bash` covers distributions
+ * that keep it there; `/opt/homebrew/bin/bash` is where a modern bash lands on Apple
+ * Silicon (macOS itself still ships bash 3.2, which is fine for our purposes but not
+ * everyone's). A PATH lookup then catches NixOS and anything unusual.
+ */
+const BASH_CANDIDATES = ["/bin/bash", "/usr/bin/bash", "/usr/local/bin/bash", "/opt/homebrew/bin/bash"];
+/** Last resort. POSIX guarantees a shell here, whatever it turns out to be. */
+const FALLBACK_SH = "/bin/sh";
+/**
+ * Choose a shell from a candidate list. Pure — `isExecutable` is injected so this is
+ * testable on any platform, including the Windows box this is usually developed on.
+ */
+export function pickShell(candidates, pathDirs, isExecutable) {
+    for (const bin of candidates) {
+        if (isExecutable(bin))
+            return { bin, isBash: true };
+    }
+    for (const dir of pathDirs) {
+        const bin = posix.join(dir, "bash");
+        if (isExecutable(bin))
+            return { bin, isBash: true };
+    }
+    return { bin: FALLBACK_SH, isBash: false };
+}
+/** Is this path a file we can actually execute? Existence is not enough on POSIX: a
+ *  readable-but-not-executable file, or a directory, would pass and then fail to spawn. */
+export function isExecutableFile(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let cached = null;
+/** The shell this machine will use, resolved once. */
+export function posixShell() {
+    if (cached)
+        return cached;
+    const pathDirs = (process.env.PATH || "").split(delimiter).filter(Boolean);
+    cached = pickShell(BASH_CANDIDATES, pathDirs, isExecutableFile);
+    return cached;
+}
+/** Test seam: forget the resolved shell so the next call re-detects. */
+export function resetPosixShellCache() {
+    cached = null;
+}
+/**
+ * Bash-only constructs that are GUARANTEED syntax errors in a strict POSIX shell.
+ *
+ * Deliberately conservative, exactly like `shellLint.ts`: every entry here must be
+ * something dash genuinely cannot parse, because the cost of a false positive is
+ * nagging the model about a command that would have worked. Constructs that merely
+ * behave differently are left alone.
+ */
+const BASHISMS = [
+    { pattern: /\[\[|\]\]/, what: "[[ ]] tests", fix: "use [ ] instead" },
+    { pattern: /<\(|>\(/, what: "process substitution <( )", fix: "use a pipe or a temp file" },
+    { pattern: /(^|\s)source\s/, what: "`source`", fix: "use `.` (dot)" },
+    { pattern: /(^|\s)function\s+\w+\s*(\(\s*\))?\s*\{/, what: "the `function` keyword", fix: "write `name() { … }`" },
+    { pattern: /\$\{?RANDOM\b/, what: "$RANDOM", fix: "use $$ or awk" },
+    { pattern: /\{\d+\.\.\d+\}/, what: "brace ranges like {1..5}", fix: "use seq or a while loop" },
+    { pattern: /&>/, what: "&> redirection", fix: "use > file 2>&1" },
+    { pattern: /\w+\+=/, what: "+= append", fix: "use var=\"$var…\"" },
+    { pattern: /\$\{\w+\[/, what: "arrays", fix: "use separate variables or a delimited string" },
+    { pattern: /(^|\s)echo\s+-e\b/, what: "echo -e", fix: "use printf" },
+];
+/**
+ * Warn when a command needs bash but this machine only has a minimal `sh`.
+ *
+ * Returns null on the overwhelmingly common path — either bash is present (so
+ * anything goes) or the command is portable. The note is only for the rare box where
+ * the command genuinely cannot run, and it names the construct and the fix rather
+ * than leaving the model to interpret a one-line dash error.
+ */
+export function shellMismatchNote(command, shell = posixShell()) {
+    if (shell.isBash)
+        return null;
+    // Ignore quoted substrings so a bash-ism mentioned inside a string isn't flagged.
+    const bare = command.replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
+    const hits = BASHISMS.filter((b) => b.pattern.test(bare));
+    if (hits.length === 0)
+        return null;
+    const list = hits.map((h) => `${h.what} (${h.fix})`).join("; ");
+    return (`[This machine has no bash, so commands run under ${shell.bin}, which is a strict POSIX shell. ` +
+        `That command uses ${list}. Rewrite it in portable shell syntax.]`);
+}
+//# sourceMappingURL=posixShell.js.map

package/dist/tools/posixShell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"posixShell.js","sourceRoot":"","sources":["../../src/tools/posixShell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,qFAAqF;AACrF,qFAAqF;AACrF,iFAAiF;AACjF,oFAAoF;AACpF,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAU7C;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,CAAC,WAAW,EAAE,eAAe,EAAE,qBAAqB,EAAE,wBAAwB,CAAC,CAAC;AAExG,+EAA+E;AAC/E,MAAM,WAAW,GAAG,SAAS,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,UAA6B,EAC7B,QAA2B,EAC3B,YAAoC;IAEpC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,YAAY,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,YAAY,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;2FAC2F;AAC3F,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,MAAM,GAAsB,IAAI,CAAC;AAErC,sDAAsD;AACtD,MAAM,UAAU,UAAU;IACxB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3E,MAAM,GAAG,SAAS,CAAC,eAAe,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAqD;IACjE,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,EAAE;IACrE,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,2BAA2B,EAAE,GAAG,EAAE,2BAA2B,EAAE;IAC3F,EAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,eAAe,EAAE;IACrE,EAAE,OAAO,EAAE,wCAAwC,EAAE,IAAI,EAAE,wBAAwB,EAAE,GAAG,EAAE,sBAAsB,EAAE;IAClH,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,eAAe,EAAE;IACnE,EAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,0BAA0B,EAAE,GAAG,EAAE,yBAAyB,EAAE;IAC/F,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,EAAE;IACjE,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,mBAAmB,EAAE;IAClE,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,8CAA8C,EAAE;IAC7F,EAAE,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,YAAY,EAAE;CACrE,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,QAAoB,UAAU,EAAE;IACjF,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC9B,kFAAkF;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,CACL,oDAAoD,KAAK,CAAC,GAAG,mCAAmC;QAChG,qBAAqB,IAAI,yCAAyC,CACnE,CAAC;AACJ,CAAC"}