@mojoaar/opencode-mimir 0.0.0-stage → 0.15.0

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @mojoaar/opencode-mimir
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mimir memory for [OpenCode](https://opencode.ai) v2: two tools and an automatic
+digest, no ceremony.
+
+Install straight from the repository this package lives in:
+
+```sh
+opencode plugin add 'github:mojoaar/mimir#main::path:packages/opencode-plugin'
+```
+
+Or point at it in `opencode.json` (or `~/.config/opencode/opencode.jsonc`):
+
+```jsonc
+{
+  "plugins": ["github:mojoaar/mimir#main::path:packages/opencode-plugin"]
+}
+```
+
+The options form is the same entry with your settings attached:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "github:mojoaar/mimir#main::path:packages/opencode-plugin",
+      "options": {
+        "url": "https://mimir.example.com",
+        "tokenFile": "~/.config/opencode/.secrets/mimir-token",
+        "tools": "auto"
+      }
+    }
+  ]
+}
+```
+
+`url`, `token` and `tokenFile` fall back to `MIMIR_URL` / `MIMIR_TOKEN`, and
+`MIMIR_REPO` overrides the repository read from git. The token file is the same
+one the MCP header can use.
+
+## What you get
+
+| Tool | What it does |
+|---|---|
+| `mimir_digest` | Returns what this project already knows: paths, titles, and a summary of the newest memories. |
+| `mimir_remember` | Stores one durable fact at a path like `deploy/rollback`. Writing the same path again replaces it. |
+
+`tools` decides whether they are added: `auto` (default) leaves them out when an
+MCP server already points at the same `/mcp` endpoint, `always` adds them
+anyway, `never` adds none. With only the plugin installed, `auto` gives you
+both.
+
+Both tools fail soft: if Mimir is down or unconfigured, the tool says so and the
+session carries on.
+
+## The digest arrives on its own
+
+The plugin registers a `context` hook that puts the project's digest at the top
+of the system prompt before the first turn, once per session. It asks for 800
+tokens with a 1.5 second timeout, and does nothing at all when Mimir is
+unreachable, slow, or unconfigured — a session never waits on memory.
+
+## Import an existing project
+
+Until the package is published, run the CLI from a checkout:
+
+```sh
+node packages/opencode-plugin/dist/bin.js ingest .
+```
+
+Walks the folder and loads its **documentation and configuration** — READMEs,
+`docs/`, markdown, compose files, `package.json` — under the `import/` path
+prefix. Source code is skipped by default; the agent already has it.
+
+| Flag | What it does |
+|---|---|
+| `--project <name>` | Name the project yourself. Required for a folder that is not a git repository. |
+| `--all` | Import every text file, not just documentation. |
+| `--dry-run` | Print what would be sent, send nothing. |
+| `--url`, `--token` | Override `MIMIR_URL` / `MIMIR_TOKEN`. |
+
+In a git repository the import lands in the project your agents already write
+to (the normalised remote). With `--project` it lands in a project keyed by
+name, so the same folder on another machine is a different project.
+
+Exit codes: `0` everything imported, `1` something was skipped or a batch
+failed, `2` bad arguments or no such directory.

package/dist/args.d.ts

@@ -0,0 +1,12 @@
+export type IngestArgs = {
+    command: 'ingest';
+    path: string;
+    project?: string;
+    url?: string;
+    token?: string;
+    all: boolean;
+    dryRun: boolean;
+    help: boolean;
+};
+/** Hand-rolled on purpose: three value flags do not justify a dependency. */
+export declare function parseArgs(argv: string[]): IngestArgs;

package/dist/args.js

@@ -0,0 +1,47 @@
+const VALUE_FLAGS = new Set(['project', 'url', 'token']);
+/** Hand-rolled on purpose: three value flags do not justify a dependency. */
+export function parseArgs(argv) {
+    const args = {
+        command: 'ingest',
+        path: '.',
+        all: false,
+        dryRun: false,
+        help: argv.length === 0,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === 'ingest' || token === 'import')
+            continue;
+        if (token === '-h' || token === '--help') {
+            args.help = true;
+            continue;
+        }
+        if (token === '--all') {
+            args.all = true;
+            continue;
+        }
+        if (token === '--dry-run') {
+            args.dryRun = true;
+            continue;
+        }
+        if (token.startsWith('--')) {
+            const body = token.slice(2);
+            const equals = body.indexOf('=');
+            const name = equals === -1 ? body : body.slice(0, equals);
+            if (!VALUE_FLAGS.has(name))
+                throw new Error(`unknown flag --${name}`);
+            const value = equals === -1 ? argv[++i] : body.slice(equals + 1);
+            if (value === undefined || value.startsWith('--'))
+                throw new Error(`--${name} needs a value`);
+            if (name === 'project')
+                args.project = value;
+            if (name === 'url')
+                args.url = value;
+            if (name === 'token')
+                args.token = value;
+            continue;
+        }
+        args.path = token;
+    }
+    return args;
+}

package/dist/batch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Batches are what the server will accept in one call: 100 files and 2 MB.
+ * Greedy and order-preserving, so a big repository becomes several requests
+ * instead of one rejected one.
+ */
+export type Batch<T> = {
+    files: T[];
+    bytes: number;
+};
+export declare function batchFiles<T extends {
+    bytes: number;
+}>(files: T[], maxFiles?: number, maxBytes?: number): Batch<T>[];

package/dist/batch.js

@@ -0,0 +1,16 @@
+export function batchFiles(files, maxFiles = 100, maxBytes = 2 * 1024 * 1024) {
+    const batches = [];
+    let current = { files: [], bytes: 0 };
+    for (const file of files) {
+        const wouldOverflow = current.files.length > 0 && (current.files.length >= maxFiles || current.bytes + file.bytes > maxBytes);
+        if (wouldOverflow) {
+            batches.push(current);
+            current = { files: [], bytes: 0 };
+        }
+        current.files.push(file);
+        current.bytes += file.bytes;
+    }
+    if (current.files.length > 0)
+        batches.push(current);
+    return batches;
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The published entrypoint. Kept separate from cli.ts so the command can be
+// imported by tests without running: npm installs a bin as a symlink, so a
+// `process.argv[1]` check here would never match `.bin/mimir` and the command
+// would exit 0 doing nothing.
+import { main } from './cli.js';
+void main(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { type IngestArgs } from './args.js';
+export type IngestIo = {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    cwd: string;
+};
+/**
+ * Returns the exit code instead of calling process.exit, so the whole command
+ * is testable and a caller can decide what a partial import means.
+ */
+export declare function runIngest(args: IngestArgs, io: IngestIo): Promise<number>;
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parseArgs } from './args.js';
+import { batchFiles } from './batch.js';
+import { callTool, detectRepo } from './client.js';
+import { selectFiles } from './select.js';
+const USAGE = `mimir ingest — load a project's documentation into Mimir
+
+  mimir ingest [path] [options]
+
+  --project <name>  name the project yourself. Required for a folder that is
+                    not a git repository; also keeps two folders apart.
+  --url <url>       Mimir base URL (default: MIMIR_URL)
+  --token <token>   API key (default: MIMIR_TOKEN)
+  --all             import every text file, not just documentation
+  --dry-run         print what would be sent and send nothing
+
+A git checkout imports into the project your agents already write to. Imports
+land under import/, where memory_search finds them.`;
+const MAX_BODY_BYTES = 262_144;
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the exit code instead of calling process.exit, so the whole command
+ * is testable and a caller can decide what a partial import means.
+ */
+export async function runIngest(args, io) {
+    if (args.help) {
+        io.out(USAGE);
+        return 0;
+    }
+    const root = resolve(io.cwd, args.path);
+    if (!(await isDirectory(root))) {
+        io.err(`no such directory: ${args.path}`);
+        return 2;
+    }
+    const repo = args.project ? null : detectRepo(root);
+    if (!args.project && !repo) {
+        // Falling back to the folder name would merge two different `docs/` folders
+        // into one project and let the second silently overwrite the first.
+        io.err(`not a git repository: pass --project <name> to name this folder's project`);
+        return 2;
+    }
+    const key = args.project ? { project: args.project } : { repo: repo };
+    const label = args.project ?? repo;
+    const walk = await selectFiles(root, { all: args.all });
+    const skipped = [...walk.skipped];
+    // Read before deciding: the server caps the decoded body, and a Latin-1 file
+    // can pass the byte check on disk and still exceed it once decoded.
+    const prepared = [];
+    for (const file of walk.files) {
+        try {
+            const body = await readFile(join(root, file.path), 'utf8');
+            const bytes = Buffer.byteLength(body, 'utf8');
+            if (bytes > MAX_BODY_BYTES) {
+                skipped.push({ path: file.path, reason: `too large (${bytes} bytes)` });
+                continue;
+            }
+            prepared.push({ path: file.path, body, bytes });
+        }
+        catch (error) {
+            skipped.push({ path: file.path, reason: error.message });
+        }
+    }
+    const batches = batchFiles(prepared);
+    const totalBytes = prepared.reduce((sum, file) => sum + file.bytes, 0);
+    if (args.dryRun) {
+        io.out(`would import ${prepared.length} files (${totalBytes} bytes) into ${label} as import/<path>`);
+        for (const file of skipped)
+            io.err(`skipped ${file.path}: ${file.reason}`);
+        if (walk.truncated) {
+            io.err(`the folder tree was larger than the walk limit; the list above is incomplete`);
+            return 1;
+        }
+        return 0;
+    }
+    let imported = 0;
+    let failed = 0;
+    for (const [index, batch] of batches.entries()) {
+        const result = await callTool('memory_ingest', {
+            ...key,
+            path_prefix: 'import',
+            files: batch.files.map((file) => ({ path: file.path, body: file.body })),
+        }, { url: args.url, token: args.token, timeoutMs: 60_000 });
+        if (!result.ok) {
+            failed++;
+            io.err(`batch ${index + 1} failed: ${result.error}`);
+            continue;
+        }
+        const outcome = result.result;
+        imported += outcome.written ?? batch.files.length;
+        for (const entry of outcome.skipped ?? []) {
+            skipped.push({ path: entry.path, reason: entry.reason });
+        }
+    }
+    for (const file of skipped)
+        io.err(`skipped ${file.path}: ${file.reason}`);
+    io.out(`imported ${imported} files, skipped ${skipped.length}`);
+    if (walk.truncated) {
+        io.err(`the folder tree was larger than the walk limit; not everything was considered`);
+    }
+    return failed > 0 || skipped.length > 0 || walk.truncated ? 1 : 0;
+}
+export async function main(argv) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        console.error(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    process.exitCode = await runIngest(args, {
+        out: (line) => console.log(line),
+        err: (line) => console.error(line),
+        cwd: process.cwd(),
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+export type CallResult = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+export type CallOptions = {
+    url?: string;
+    token?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+/**
+ * Calls one Mimir MCP tool. Never throws: a plugin must not break a session
+ * because the memory server is down.
+ */
+export declare function callTool(name: string, args: Record<string, unknown>, options?: CallOptions): Promise<CallResult>;
+/** A repo key for X-Mimir-Repo, from MIMIR_REPO or `git remote get-url origin`. */
+export declare function detectRepo(directory: string): string | null;

package/dist/client.js

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process';
+/**
+ * Calls one Mimir MCP tool. Never throws: a plugin must not break a session
+ * because the memory server is down.
+ */
+export async function callTool(name, args, options = {}) {
+    const url = (options.url ?? process.env.MIMIR_URL ?? '').replace(/\/+$/, '');
+    const token = options.token ?? process.env.MIMIR_TOKEN ?? '';
+    if (!url || !token)
+        return { ok: false, error: 'MIMIR_URL and MIMIR_TOKEN must be set' };
+    try {
+        const response = await (options.fetch ?? fetch)(`${url}/mcp`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'tools/call',
+                params: { name, arguments: args },
+            }),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 3000),
+        });
+        if (!response.ok)
+            return { ok: false, error: `mimir responded ${response.status}` };
+        const body = (await response.json());
+        if (body.error)
+            return { ok: false, error: body.error.message ?? 'mimir returned an error' };
+        const text = body.result?.content?.[0]?.text;
+        if (body.result?.isError)
+            return { ok: false, error: text ?? 'mimir returned an error' };
+        if (!text)
+            return { ok: true, result: body.result ?? null };
+        try {
+            return { ok: true, result: JSON.parse(text) };
+        }
+        catch {
+            return { ok: true, result: text };
+        }
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : 'request failed' };
+    }
+}
+/** A repo key for X-Mimir-Repo, from MIMIR_REPO or `git remote get-url origin`. */
+export function detectRepo(directory) {
+    if (process.env.MIMIR_REPO)
+        return process.env.MIMIR_REPO;
+    try {
+        const remote = execFileSync('git', ['-C', directory, 'remote', 'get-url', 'origin'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return remote || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export type ToolPolicy = 'auto' | 'always' | 'never';
+export type MimirConfig = {
+    url: string;
+    token: string;
+    tools: ToolPolicy;
+};
+/**
+ * Options win over the environment, which wins over the token file the MCP
+ * header already points at. Anything missing means "stay quiet": a plugin
+ * must never break a session it cannot reach Mimir from.
+ */
+export declare function resolveConfig(options: Record<string, unknown>, env?: Record<string, string | undefined>, readFile?: (path: string) => string): MimirConfig | null;

package/dist/config.js

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_TOKEN_FILE = join(homedir(), '.config/opencode/.secrets/mimir-token');
+/**
+ * Options win over the environment, which wins over the token file the MCP
+ * header already points at. Anything missing means "stay quiet": a plugin
+ * must never break a session it cannot reach Mimir from.
+ */
+export function resolveConfig(options, env = process.env, readFile = (path) => readFileSync(path, 'utf8')) {
+    const url = normaliseUrl(text(options.url) ?? text(env.MIMIR_URL));
+    const token = text(options.token) ?? text(env.MIMIR_TOKEN) ?? readTokenFile(text(options.tokenFile), readFile);
+    if (!url || !token)
+        return null;
+    const policy = options.tools;
+    return { url, token, tools: policy === 'always' || policy === 'never' ? policy : 'auto' };
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function readTokenFile(path, readFile) {
+    try {
+        // readFileSync does not expand `~`, and every example we print uses one.
+        return text(readFile((path ?? DEFAULT_TOKEN_FILE).replace(/^~(?=$|\/)/, homedir())));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A base URL, because callers append `/mcp` themselves. */
+function normaliseUrl(value) {
+    return text(value?.replace(/\/+$/, '').replace(/\/mcp$/, ''));
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from '@opencode/plugin';
+export declare const DIGEST_HEADER = "## What this project already knows (Mimir)\n\n";
+/**
+ * One injection point and two tools. The hook is what puts the project's
+ * digest in front of the model before the first turn, so a session starts
+ * informed without spending a tool call. Everything here is fail-soft: a slow
+ * or missing Mimir must never hold up a session.
+ */
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,44 @@
+import { Plugin } from '@opencode/plugin';
+import { callTool, detectRepo } from './client.js';
+import { resolveConfig } from './config.js';
+import { registerTools } from './tools.js';
+export const DIGEST_HEADER = '## What this project already knows (Mimir)\n\n';
+/**
+ * One injection point and two tools. The hook is what puts the project's
+ * digest in front of the model before the first turn, so a session starts
+ * informed without spending a tool call. Everything here is fail-soft: a slow
+ * or missing Mimir must never hold up a session.
+ */
+export default Plugin.define({
+    id: 'mimir',
+    async setup(ctx) {
+        const config = resolveConfig(ctx.options);
+        if (!config)
+            return;
+        // A folder without a git remote still needs a stable key, or every write
+        // lands in a fresh project. The server maps absolute paths to `local:<hash>`.
+        const repo = detectRepo(ctx.location.directory) ?? ctx.location.directory;
+        const seen = new Set();
+        // The hook runs before every model dispatch, so a session is fetched once
+        // and then left alone.
+        const session = await ctx.session.hook('context', async (event) => {
+            if (seen.has(event.sessionID))
+                return;
+            // One attempt per session: a failed digest must not be re-paid before
+            // every model dispatch, which is how often this hook runs.
+            seen.add(event.sessionID);
+            const result = await callTool('memory_digest', { repo: repo ?? undefined, budget_tokens: 800 }, { ...config, timeoutMs: 1500 }).catch(() => null);
+            if (!result?.ok)
+                return;
+            const text = result.result.text?.trim();
+            if (!text)
+                return;
+            event.system.push({ type: 'text', text: `${DIGEST_HEADER}${text}` });
+        });
+        const tools = await registerTools(ctx, config, repo);
+        return async () => {
+            await tools.dispose();
+            await session.dispose();
+        };
+    },
+});

package/dist/select.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What an import is for: the knowledge a reader would have to dig out of the
+ * repository, not a second copy of the code the agent already has on disk.
+ */
+export declare const IGNORED_DIRS: Set<string>;
+export declare const IGNORED_EXTENSIONS: Set<string>;
+export type WalkEntry = {
+    path: string;
+    bytes: number;
+};
+export type WalkResult = {
+    files: WalkEntry[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    /** True when the walk stopped early, so the caller must not report success. */
+    truncated: boolean;
+};
+export type WalkOptions = {
+    all?: boolean;
+    maxFileBytes?: number;
+    maxEntries?: number;
+};
+export declare function selectFiles(root: string, options?: WalkOptions): Promise<WalkResult>;

package/dist/select.js

@@ -0,0 +1,100 @@
+import { readdir, stat } from 'node:fs/promises';
+import { posix, join } from 'node:path';
+/**
+ * What an import is for: the knowledge a reader would have to dig out of the
+ * repository, not a second copy of the code the agent already has on disk.
+ */
+export const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    '.venv',
+    'venv',
+    '__pycache__',
+    '.idea',
+    '.vscode',
+    'vendor',
+    'target',
+    'tmp',
+]);
+export const IGNORED_EXTENSIONS = new Set([
+    'png', 'jpg', 'jpeg', 'gif', 'webp', 'ico', 'pdf', 'zip', 'gz', 'tar', 'bz2', '7z', 'rar',
+    'exe', 'dll', 'so', 'dylib', 'o', 'a', 'class', 'jar', 'wasm',
+    'mp3', 'mp4', 'mov', 'avi', 'woff', 'woff2', 'ttf', 'eot',
+]);
+const CONFIG_FILES = new Set([
+    'package.json',
+    'tsconfig.json',
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'compose.yml',
+    'compose.yaml',
+    'Dockerfile',
+    'Makefile',
+    'pyproject.toml',
+    'go.mod',
+    'Cargo.toml',
+    '.env.example',
+    'renovate.json',
+    'turbo.json',
+]);
+const PROSE = /\.(md|mdx)$/i;
+const ROOT_PROSE = /^(readme|changelog|contributing|license)/i;
+// A guard against a symlinked home directory, not a product limit: a real
+// repository of 250 000 files is still walked, and hitting the cap is reported.
+const MAX_ENTRIES = 250_000;
+function depth(path) {
+    return path.split('/').length - 1;
+}
+function wanted(path) {
+    const base = posix.basename(path);
+    if (ROOT_PROSE.test(base) && depth(path) <= 1)
+        return true;
+    if (path.startsWith('docs/') || path.startsWith('doc/'))
+        return PROSE.test(base);
+    if (PROSE.test(base) && depth(path) <= 3)
+        return true;
+    return CONFIG_FILES.has(base) && depth(path) <= 2;
+}
+export async function selectFiles(root, options = {}) {
+    const maxFileBytes = options.maxFileBytes ?? 262_144;
+    const maxEntries = options.maxEntries ?? MAX_ENTRIES;
+    const files = [];
+    const skipped = [];
+    let seen = 0;
+    let truncated = false;
+    async function walk(relative) {
+        const entries = await readdir(join(root, relative), { withFileTypes: true });
+        for (const entry of entries) {
+            if (++seen > maxEntries) {
+                truncated = true;
+                return;
+            }
+            const path = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                await walk(path);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const extension = posix.extname(entry.name).slice(1).toLowerCase();
+            if (IGNORED_EXTENSIONS.has(extension))
+                continue;
+            if (options.all !== true && !wanted(path))
+                continue;
+            const { size } = await stat(join(root, path));
+            if (size > maxFileBytes) {
+                skipped.push({ path, reason: `too large (${size} bytes)` });
+                continue;
+            }
+            files.push({ path, bytes: size });
+        }
+    }
+    await walk('');
+    return { files, skipped, truncated };
+}