@possumtech/rummy 0.2.1

package/src/plugins/file/file.js

@@ -0,0 +1,85 @@
+import { isAbsolute, relative } from "node:path";
+
+export default class File {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			fidelity: "turn",
+			validStates: ["full", "summary", "index", "stored"],
+			category: "file",
+		});
+		core.registerScheme({
+			name: "http",
+			fidelity: "turn",
+			validStates: ["full", "summary", "stored"],
+			category: "file",
+		});
+		core.registerScheme({
+			name: "https",
+			fidelity: "turn",
+			validStates: ["full", "summary", "stored"],
+			category: "file",
+		});
+		core.on("full", this.full.bind(this));
+
+		// Register identity projections for schemes that just pass through body
+		for (const scheme of ["known", "skill", "ask", "act", "progress"]) {
+			core.hooks.tools.onView(scheme, (entry) => entry.body);
+		}
+	}
+
+	full(entry) {
+		return entry.body;
+	}
+
+	static async activate(
+		db,
+		knownStore,
+		projectId,
+		pattern,
+		visibility = "active",
+	) {
+		const path = await normalizePath(db, projectId, pattern);
+		if (!path) return { status: "ok" };
+
+		await db.upsert_file_constraint.run({
+			project_id: projectId,
+			pattern: path,
+			visibility,
+		});
+
+		if (visibility === "ignore") {
+			const runs = await db.get_all_runs.all({ project_id: projectId });
+			for (const run of runs) {
+				await knownStore.demoteByPattern(run.id, path, null);
+			}
+		}
+
+		return { status: "ok" };
+	}
+
+	static async ignore(db, knownStore, projectId, pattern) {
+		return File.activate(db, knownStore, projectId, pattern, "ignore");
+	}
+
+	static async drop(db, projectId, pattern) {
+		const path = await normalizePath(db, projectId, pattern);
+		if (!path) return { status: "ok" };
+
+		await db.delete_file_constraint.run({
+			project_id: projectId,
+			pattern: path,
+		});
+
+		return { status: "ok" };
+	}
+}
+
+async function normalizePath(db, projectId, path) {
+	if (!isAbsolute(path)) return path;
+	const project = await db.get_project_by_id.get({ id: projectId });
+	if (!project) return path;
+	return relative(project.project_root, path);
+}

package/src/plugins/get/README.md

@@ -0,0 +1,19 @@
+# get
+
+Retrieves and promotes entries by path or glob pattern.
+
+## Registration
+
+- **Tool**: `get`
+- **Modes**: ask, act
+- **Category**: ask
+- **Handler**: Fetches matching entries via `getEntriesByPattern`, promotes them with `promoteByPattern`, and records the result.
+
+## Projection
+
+Shows `get {path}` followed by the entry body.
+
+## Behavior
+
+- Pattern queries (globs or body filters) produce a summary of matched paths.
+- Exact path queries report the path and token count, or "not found".

package/src/plugins/get/docs.md

@@ -0,0 +1,6 @@
+## <get>[path/to/file]</get> - Load a file or entry into context
+Example: <get>docs/example.txt</get>
+Example: <get>known://auth_flow</get>
+* Entries at state="index" or state="summary" are promoted to full content.
+* Use "known://" paths to recall stored information.
+* When irrelevant or resolved, use <store/> to remove from context.

package/src/plugins/get/get.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { storePatternResult } from "../helpers.js";
+
+export default class Get {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({ validStates: ["full", "read", "pattern"] });
+		core.on("handler", this.handler.bind(this));
+		core.on("full", this.full.bind(this));
+		core.on("summary", this.summary.bind(this));
+		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+		core.filter("instructions.toolDocs", async (content) =>
+			content ? `${content}\n\n${docs}` : docs,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const target = entry.attributes.path;
+		const bodyFilter = entry.attributes.body || null;
+		const isPattern = bodyFilter || target.includes("*");
+		const matches = await store.getEntriesByPattern(runId, target, bodyFilter);
+		await store.promoteByPattern(runId, target, bodyFilter, turn);
+
+		if (isPattern) {
+			await storePatternResult(
+				store,
+				runId,
+				turn,
+				"get",
+				target,
+				bodyFilter,
+				matches,
+			);
+		} else {
+			const total = matches.reduce((s, m) => s + m.tokens_full, 0);
+			const paths = matches.map((m) => m.path).join(", ");
+			const body =
+				matches.length > 0 ? `${paths} ${total} tokens` : `${target} not found`;
+			await store.upsert(runId, turn, entry.resultPath, body, "read");
+		}
+	}
+
+	full(entry) {
+		return `# get ${entry.attributes.path || entry.path}\n${entry.body}`;
+	}
+
+	summary() {
+		return "";
+	}
+}

package/src/plugins/hedberg/README.md

@@ -0,0 +1,72 @@
+# hedberg
+
+The interpretation boundary between stochastic model output and
+deterministic system operations.
+
+Models speak in whatever syntax they were trained on — sed regex,
+SEARCH/REPLACE blocks, escaped characters, regex anchors, malformed
+XML. Hedberg normalizes all of it into clean, deterministic operations.
+
+## Usage
+
+Any plugin can access hedberg via `core.hooks.hedberg`:
+
+```js
+constructor(core) {
+    const { match, replace, parseSed } = core.hooks.hedberg;
+}
+```
+
+## API (available on core.hooks.hedberg)
+
+| Method | Purpose |
+|--------|---------|
+| `match(pattern, string)` | Full-string pattern match (glob, regex, literal) |
+| `search(pattern, string)` | Substring search, returns `{ found, match, index }` |
+| `replace(body, search, replacement, opts?)` | Apply replacement (sed regex → literal → heuristic) |
+| `parseSed(input)` | Parse sed syntax into `[{ search, replace, flags, sed }]` |
+| `parseEdits(content)` | Detect edit format (merge conflict, udiff, Claude XML) |
+| `normalizeAttrs(attrs)` | Heal model attribute names (value→body, unknown→path) |
+| `generatePatch(path, old, new)` | Generate unified diff |
+
+### Hedberg.replace(body, search, replacement, options?)
+
+Apply a replacement to text. Tries sed regex (if `sed: true`), then
+literal match, then heuristic fuzzy match.
+
+```js
+const result = Hedberg.replace(fileContent, "7 - a =$", "7 - a = 5", {
+    sed: true,
+    flags: "g",
+});
+// result: { patch, searchText, replaceText, warning, error }
+```
+
+### parseSed(input)
+
+Parse sed syntax into blocks. Handles escaped delimiters, chained
+commands, flag extraction.
+
+```js
+const blocks = parseSed("s/foo/bar/g s/baz\\/qux/hello/");
+// [{ search: "foo", replace: "bar", flags: "g", sed: true },
+//  { search: "baz/qux", replace: "hello", flags: "", sed: true }]
+```
+
+### Pattern functions (hedmatch, hedsearch, hedreplace)
+
+Auto-detect pattern type and match/search/replace accordingly.
+Used by SQL functions for database-level pattern operations.
+
+## Files
+
+- **hedberg.js** — plugin class, `replace()` method
+- **patterns.js** — pattern type detection (regex, glob, jsonpath, xpath, literal)
+- **matcher.js** — heuristic fuzzy matching, diff generation
+- **sed.js** — sed syntax parsing
+
+## Future
+
+This will become a separate npm package (`@possumtech/rummy.hedberg`)
+to isolate the stochastic interpretation logic from the deterministic
+core service.

package/src/plugins/hedberg/docs.md

@@ -0,0 +1,9 @@
+# Advanced Patterns
+* Paths accept globs: `src/**/*.js`, `known://api_*`
+* Body attributes filter by content: `<get path="src/*.js" body="TODO"/>`
+* Regex patterns use /slashes/: `<get path="/\.test\.js$/" preview/>`
+* Adding `preview` shows matches without making changes
+* Chain multiple replacements: `s/old/new/ s/foo/bar/`
+Example: <get path="src/**/*.js" body="TODO" preview/> (list js files containing TODO)
+Example: <store path="src/**/*.test.js"/> (store all test files)
+Example: <rm path="known://temp_*" preview/> (preview which temp entries would be deleted)

package/src/plugins/hedberg/edits.js

@@ -0,0 +1,65 @@
+/**
+ * Edit format detection. Identifies the edit syntax the model used
+ * and normalizes it into { search, replace } blocks.
+ *
+ * Supported formats:
+ * 1. SEARCH/REPLACE merge conflict blocks
+ * 2. Replace-only blocks (no search)
+ * 3. Unified diff
+ * 4. Claude XML (<old_text>/<new_text>)
+ */
+
+export function parseEditContent(content) {
+	const blocks = [];
+
+	// Format 1: Git merge conflict style (3-12 marker chars)
+	const mergeRe =
+		/<{3,12} SEARCH\n([\s\S]*?)\n={3,12}\n([\s\S]*?)\n>{3,12} REPLACE/g;
+	for (const m of content.matchAll(mergeRe)) {
+		blocks.push({ search: m[1], replace: m[2] });
+	}
+	if (blocks.length > 0) return blocks;
+
+	// Format 2: Replace-only (no search block, 3-12 marker chars)
+	const replaceOnly = /^={3,12}\n([\s\S]*?)\n>{3,12} REPLACE/gm;
+	for (const m of content.matchAll(replaceOnly)) {
+		blocks.push({ search: null, replace: m[1] });
+	}
+	if (blocks.length > 0) return blocks;
+
+	// Format 3: Unified diff
+	if (
+		content.includes("@@") &&
+		(content.includes("\n-") || content.includes("\n+"))
+	) {
+		const hunks = content.split(/^@@[^@]*@@/m).slice(1);
+		for (const hunk of hunks) {
+			const oldLines = [];
+			const newLines = [];
+			for (const line of hunk.split("\n")) {
+				if (line.startsWith("-")) oldLines.push(line.slice(1));
+				else if (line.startsWith("+")) newLines.push(line.slice(1));
+				else if (line.startsWith(" ")) {
+					oldLines.push(line.slice(1));
+					newLines.push(line.slice(1));
+				}
+			}
+			if (oldLines.length > 0 || newLines.length > 0) {
+				blocks.push({
+					search: oldLines.join("\n"),
+					replace: newLines.join("\n"),
+				});
+			}
+		}
+	}
+	if (blocks.length > 0) return blocks;
+
+	// Format 4: Claude XML style
+	const claudeRe =
+		/<old_text>([\s\S]*?)<\/old_text>\s*<new_text>([\s\S]*?)<\/new_text>/g;
+	for (const m of content.matchAll(claudeRe)) {
+		blocks.push({ search: m[1], replace: m[2] });
+	}
+
+	return blocks;
+}

package/src/plugins/hedberg/hedberg.js

@@ -0,0 +1,89 @@
+import { readFileSync } from "node:fs";
+import { parseEditContent } from "./edits.js";
+import HeuristicMatcher, { generatePatch } from "./matcher.js";
+import { normalizeAttrs } from "./normalize.js";
+import { hedmatch, hedsearch } from "./patterns.js";
+import { parseSed } from "./sed.js";
+
+/**
+ * Hedberg: the interpretation boundary between stochastic model output
+ * and deterministic system operations.
+ *
+ * Registers its functions on core.hedberg so any plugin can call them:
+ *   core.hedberg.match(pattern, string)
+ *   core.hedberg.search(pattern, string)
+ *   core.hedberg.replace(body, search, replacement, options?)
+ *   core.hedberg.parseSed(input)
+ *   core.hedberg.parseEdits(content)
+ *   core.hedberg.normalizeAttrs(attrs)
+ *   core.hedberg.generatePatch(path, old, new)
+ */
+export default class Hedberg {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+
+		core.hooks.hedberg = {
+			match: hedmatch,
+			search: hedsearch,
+			replace: Hedberg.replace,
+			parseSed,
+			parseEdits: parseEditContent,
+			normalizeAttrs,
+			generatePatch,
+		};
+
+		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+		core.filter("instructions.toolDocs", async (content) =>
+			content ? `${content}\n\n${docs}` : docs,
+		);
+	}
+
+	/**
+	 * Apply a replacement to text. Handles sed regex, literal match,
+	 * and heuristic fuzzy match — in that order.
+	 *
+	 * Returns { patch, searchText, replaceText, warning, error }
+	 */
+	static replace(body, search, replacement, { sed = false, flags = "" } = {}) {
+		let patch = null;
+		let warning = null;
+		let error = null;
+		const searchText = search;
+		const replaceText = replacement;
+
+		if (sed) {
+			try {
+				const re = new RegExp(
+					searchText,
+					flags.includes("g") ? flags : `${flags}g`,
+				);
+				patch = body.replace(re, replaceText);
+				if (patch === body) patch = null;
+			} catch {
+				// Invalid regex — fall through to literal/heuristic interpretation
+			}
+		}
+
+		if (!patch && body.includes(searchText)) {
+			patch = body.replaceAll(searchText, replaceText);
+		}
+
+		if (!patch) {
+			const matched = HeuristicMatcher.matchAndPatch(
+				"",
+				body,
+				searchText,
+				replaceText,
+			);
+			patch = matched.newContent;
+			warning = matched.warning;
+			error = matched.error;
+		}
+
+		return { patch, searchText, replaceText, warning, error };
+	}
+}
+
+export { generatePatch };

package/src/plugins/hedberg/matcher.js

@@ -0,0 +1,181 @@
+import { execSync } from "node:child_process";
+import { unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export function generatePatch(filePath, oldContent, newContent) {
+	const id = `${Date.now()}_${Math.random().toString(36).slice(2)}`;
+	const oldPath = join(tmpdir(), `rummy_diff_old_${id}`);
+	const newPath = join(tmpdir(), `rummy_diff_new_${id}`);
+
+	try {
+		writeFileSync(oldPath, oldContent);
+		writeFileSync(newPath, newContent);
+
+		const result = execSync(
+			`diff -u --label "${filePath}\told" --label "${filePath}\tnew" "${oldPath}" "${newPath}"`,
+			{ encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] },
+		);
+		return result;
+	} catch (err) {
+		// diff exits 1 when files differ — that's the success case
+		if (err.stdout) return err.stdout;
+		return "";
+	} finally {
+		try {
+			unlinkSync(oldPath);
+		} catch {}
+		try {
+			unlinkSync(newPath);
+		} catch {}
+	}
+}
+
+export default class HeuristicMatcher {
+	static matchAndPatch(filePath, fileContent, searchBlock, replaceBlock) {
+		// Unescape common regex escapes (models often escape brackets, parens, etc.)
+		const unescaped = searchBlock.replace(/\\([[\](){}.*+?^$|\\])/g, "$1");
+		if (unescaped !== searchBlock && fileContent.includes(unescaped)) {
+			searchBlock = unescaped;
+		}
+
+		const searchLines = searchBlock.split(/\r?\n/);
+		const fileLines = fileContent.split(/\r?\n/);
+
+		// 1. Exact Match Attempt (line-boundary substring search)
+		let exactIdx = fileContent.indexOf(searchBlock);
+		let lastExactIdx = -1;
+		let exactCount = 0;
+		while (exactIdx !== -1) {
+			const atLineBoundary =
+				exactIdx === 0 || fileContent[exactIdx - 1] === "\n";
+			if (atLineBoundary) {
+				exactCount++;
+				lastExactIdx = exactIdx;
+			}
+			exactIdx = fileContent.indexOf(searchBlock, exactIdx + 1);
+		}
+
+		if (exactCount > 0) {
+			const useIdx = lastExactIdx;
+			const newContent =
+				fileContent.slice(0, useIdx) +
+				replaceBlock +
+				fileContent.slice(useIdx + searchBlock.length);
+			const patch = generatePatch(filePath, fileContent, newContent);
+			const warning =
+				exactCount > 1
+					? `SEARCH block matched ${exactCount} locations. Edit was applied to the last occurrence. Use more surrounding context in future edits to avoid ambiguity.`
+					: null;
+			return { patch, newContent, warning, error: null };
+		}
+
+		// 2. Fuzzy Tokenized Match (Ignore leading/trailing whitespace per line)
+		const searchTokens = searchLines
+			.map((l) => l.trim())
+			.filter((l) => l !== "");
+		const fileTokens = fileLines.map((l) => l.trim());
+
+		if (searchTokens.length === 0) {
+			// Empty SEARCH = append REPLACE to end of file
+			const trailing = fileContent.endsWith("\n") ? "" : "\n";
+			const newContent = `${fileContent + trailing + replaceBlock}\n`;
+			const patch = generatePatch(filePath, fileContent, newContent);
+			return { patch, newContent, warning: null, error: null };
+		}
+
+		let matchStartIndex = -1;
+		let matchEndIndex = -1;
+		let matchCount = 0;
+
+		for (let i = 0; i < fileTokens.length; i++) {
+			if (fileTokens[i] === "" && searchTokens[0] !== "") continue;
+
+			let searchIdx = 0;
+			let fileIdx = i;
+
+			while (searchIdx < searchTokens.length && fileIdx < fileTokens.length) {
+				if (fileTokens[fileIdx] === "" && searchTokens[searchIdx] !== "") {
+					fileIdx++;
+					continue;
+				}
+
+				if (fileTokens[fileIdx] === searchTokens[searchIdx]) {
+					searchIdx++;
+					fileIdx++;
+				} else {
+					break;
+				}
+			}
+
+			if (searchIdx === searchTokens.length) {
+				matchCount++;
+				matchStartIndex = i;
+				matchEndIndex = fileIdx - 1;
+			}
+		}
+
+		if (matchCount === 0) {
+			return {
+				patch: null,
+				warning: null,
+				error:
+					"Could not find the SEARCH block in the file. Ensure you are providing an exact match of the existing code, without truncating lines with '...'.",
+			};
+		}
+
+		const fuzzyAmbiguous = matchCount > 1;
+
+		// 3. Indentation Healing
+		const matchedFileLines = fileLines.slice(
+			matchStartIndex,
+			matchEndIndex + 1,
+		);
+
+		const firstFileIndentedLine = matchedFileLines.find((l) => l.trim() !== "");
+		const fileIndentMatch = firstFileIndentedLine
+			? firstFileIndentedLine.match(/^(\s*)/)
+			: null;
+		const fileIndent = fileIndentMatch ? fileIndentMatch[1] : "";
+
+		const firstSearchIndentedLine = searchLines.find((l) => l.trim() !== "");
+		const searchIndentMatch = firstSearchIndentedLine
+			? firstSearchIndentedLine.match(/^(\s*)/)
+			: null;
+		const searchIndent = searchIndentMatch ? searchIndentMatch[1] : "";
+
+		let healedReplaceBlock = replaceBlock;
+		let warning = null;
+
+		if (fileIndent !== searchIndent) {
+			warning = `Indentation healing applied. The file has different indentation ('${fileIndent.replace(/\t/g, "\\t").replace(/ /g, "s")}') than your SEARCH block. Please try to match indentation exactly in future edits.`;
+
+			const replaceLines = replaceBlock.split(/\r?\n/);
+			const healedLines = replaceLines.map((line) => {
+				if (line.trim() === "") return line;
+				if (line.startsWith(searchIndent)) {
+					return fileIndent + line.substring(searchIndent.length);
+				}
+				return fileIndent + line.trimStart();
+			});
+			healedReplaceBlock = healedLines.join("\n");
+		}
+
+		const newFileLines = [
+			...fileLines.slice(0, matchStartIndex),
+			healedReplaceBlock,
+			...fileLines.slice(matchEndIndex + 1),
+		];
+		const newContent = newFileLines.join("\n");
+
+		const patch = generatePatch(filePath, fileContent, newContent);
+
+		if (fuzzyAmbiguous) {
+			warning =
+				(warning ? `${warning} ` : "") +
+				`SEARCH block matched ${matchCount} locations. Edit was applied to the last occurrence. Use more surrounding context in future edits to avoid ambiguity.`;
+		}
+
+		return { patch, newContent, warning, error: null };
+	}
+}

package/src/plugins/hedberg/normalize.js

@@ -0,0 +1,41 @@
+/**
+ * Attribute normalization. Heals legacy and alternative attribute names
+ * from model output into canonical form.
+ *
+ * - value="" → body=""
+ * - file="" or key="" → path="" (first unrecognized attr becomes path)
+ * - preview="" → preview=true
+ */
+
+const KNOWN_ATTRS = new Set([
+	"path",
+	"body",
+	"preview",
+	"question",
+	"options",
+	"search",
+	"replace",
+	"to",
+	"results",
+	"command",
+	"warn",
+]);
+
+export function normalizeAttrs(attrs) {
+	const out = { ...attrs };
+	if ("value" in out && !("body" in out)) {
+		out.body = out.value;
+		delete out.value;
+	}
+	if (!out.path) {
+		for (const [k, v] of Object.entries(out)) {
+			if (!KNOWN_ATTRS.has(k) && v) {
+				out.path = v;
+				delete out[k];
+				break;
+			}
+		}
+	}
+	if ("preview" in out) out.preview = true;
+	return out;
+}