@jbarket/loomai 0.5.0

package/dist/cli/doctor.js

@@ -0,0 +1,206 @@
+/**
+ * loom doctor — read-only environment probe. Reports node version
+ * compatibility, stack version, existing agents under
+ * ~/.config/loom/*, and forward-looking git fields per agent. Never
+ * writes. Exit 0 regardless of findings; health is the output, not
+ * the exit code.
+ */
+import { parseArgs } from 'node:util';
+import { readdir, readFile, stat, lstat, readlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { extractGlobalFlags } from './args.js';
+import { renderJson } from './io.js';
+import { CURRENT_STACK_VERSION, resolveDefaultContextPath } from '../config.js';
+const USAGE = `Usage: loom doctor [options]
+
+Probes the loom environment. Read-only; exits 0 regardless of findings.
+
+Options:
+  --json    Machine-readable output
+  --help    Show this help
+`;
+async function fileExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function probeGit(agentDir) {
+    const dotGit = join(agentDir, '.git');
+    const initialized = await fileExists(dotGit);
+    const gitignorePresent = await fileExists(join(agentDir, '.gitignore'));
+    return {
+        initialized,
+        hasRemote: false,
+        dirty: false,
+        gitignorePresent,
+    };
+}
+async function probeDefault(root) {
+    const defaultPath = join(root, 'default');
+    let s;
+    try {
+        s = await lstat(defaultPath);
+    }
+    catch {
+        return { exists: false, isSymlink: false };
+    }
+    if (s.isSymbolicLink()) {
+        const target = await readlink(defaultPath);
+        try {
+            await stat(defaultPath); // follows the symlink; throws if dangling
+            const empty = !(await fileExists(join(defaultPath, 'IDENTITY.md')));
+            return { exists: true, isSymlink: true, target, dangling: false, empty };
+        }
+        catch {
+            return { exists: true, isSymlink: true, target, dangling: true };
+        }
+    }
+    // A real directory named "default" — should be a symlink per the spec
+    const empty = !(await fileExists(join(defaultPath, 'IDENTITY.md')));
+    return { exists: true, isSymlink: false, empty };
+}
+async function probeAgents(home) {
+    const root = join(home, '.config', 'loom');
+    const agents = [];
+    let entries = [];
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        const defaultStatus = await probeDefault(root);
+        return { root, agents, defaultStatus };
+    }
+    for (const name of entries.sort()) {
+        if (name === 'default')
+            continue; // handled via probeDefault
+        const p = join(root, name);
+        let s;
+        try {
+            s = await stat(p);
+        }
+        catch {
+            continue;
+        }
+        if (!s.isDirectory())
+            continue;
+        agents.push({
+            name,
+            path: p,
+            hasIdentity: await fileExists(join(p, 'IDENTITY.md')),
+            hasMemoriesDb: await fileExists(join(p, 'memories.db')),
+            git: await probeGit(p),
+        });
+    }
+    const defaultStatus = await probeDefault(root);
+    return { root, agents, defaultStatus };
+}
+function defaultIsOk(ds) {
+    if (!ds.exists)
+        return false;
+    if (!ds.isSymlink)
+        return false; // real dir is not ok — must be a symlink
+    if (ds.dangling)
+        return false;
+    if (ds.empty)
+        return false;
+    return true;
+}
+function nodeOk(version) {
+    const m = version.match(/^v(\d+)\./);
+    return m !== null && Number(m[1]) >= 20;
+}
+async function probeStackVersion(contextDir) {
+    const file = join(contextDir, 'LOOM_STACK_VERSION');
+    try {
+        const body = (await readFile(file, 'utf-8')).trim();
+        const v = Number(body);
+        return Number.isInteger(v) && v <= CURRENT_STACK_VERSION;
+    }
+    catch {
+        return true;
+    }
+}
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: {
+                json: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const home = io.env.HOME ?? process.env.HOME ?? '';
+    const contextDir = global.contextDir ?? io.env.LOOM_CONTEXT_DIR ?? resolveDefaultContextPath(home);
+    const { root, agents, defaultStatus } = await probeAgents(home);
+    const report = {
+        nodeOk: nodeOk(process.version),
+        nodeVersion: process.version,
+        stackVersionOk: await probeStackVersion(contextDir),
+        contextDirResolved: contextDir,
+        agentsRoot: root,
+        existingAgents: agents,
+        defaultStatus,
+        defaultOk: defaultIsOk(defaultStatus),
+    };
+    const json = Boolean(parsed.values.json) || Boolean(global.json);
+    if (json) {
+        renderJson(io, report);
+        return 0;
+    }
+    const lines = [];
+    lines.push(`node:        ${report.nodeVersion}${report.nodeOk ? '' : '  (unsupported — need ≥ 20)'}`);
+    lines.push(`stack:       ${report.stackVersionOk ? 'compatible' : 'incompatible'}`);
+    lines.push(`context dir: ${report.contextDirResolved}`);
+    lines.push(`agents root: ${report.agentsRoot}`);
+    const ds = report.defaultStatus;
+    if (!ds.exists) {
+        lines.push('default:     missing  [FAIL — run `loom bootstrap` to create an agent and set up the default pointer]');
+    }
+    else if (!ds.isSymlink) {
+        lines.push('default:     real directory (should be a symlink)  [FAIL]');
+    }
+    else if (ds.dangling) {
+        lines.push(`default:     ${ds.target} (dangling — target does not exist)  [FAIL]`);
+    }
+    else if (ds.empty) {
+        lines.push(`default:     -> ${ds.target} (no IDENTITY.md)  [FAIL]`);
+    }
+    else {
+        lines.push(`default:     -> ${ds.target}  [ok]`);
+    }
+    if (report.existingAgents.length === 0) {
+        lines.push('agents:      (none)');
+    }
+    else {
+        lines.push(`agents:      ${report.existingAgents.length}`);
+        for (const a of report.existingAgents) {
+            const flags = [];
+            if (a.hasIdentity)
+                flags.push('identity');
+            if (a.hasMemoriesDb)
+                flags.push('memories.db');
+            if (a.git.initialized)
+                flags.push('git');
+            lines.push(`  - ${a.name} (${flags.join(', ') || 'empty'})`);
+        }
+    }
+    io.stdout(lines.join('\n') + '\n');
+    return 0;
+}

package/dist/cli/forget.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/forget.js

@@ -0,0 +1,97 @@
+/**
+ * loom forget — remove memories by ref, category+title, or title pattern.
+ */
+import { parseArgs } from 'node:util';
+import { forget } from '../tools/forget.js';
+import { createBackend } from '../backends/index.js';
+import { assertStackVersionCompatible } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+import { renderJson } from './io.js';
+const USAGE = `Usage:
+  loom forget <ref>
+  loom forget --category <cat> --title <exact>
+  loom forget --title-pattern <glob> (--category <cat> | --project <name>)
+
+Options:
+  --confirm              Required for scope deletion (category/project/pattern
+                         without an exact target). Without it, prints a preview
+                         of what would be deleted and deletes nothing.
+  --json                 Emit ForgetResult
+  --context-dir <path>   Agent context dir
+  --help, -h             Show this help
+`;
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: {
+                category: { type: 'string' },
+                title: { type: 'string' },
+                project: { type: 'string' },
+                'title-pattern': { type: 'string' },
+                confirm: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+            allowPositionals: true,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const input = {
+        ref: parsed.positionals[0],
+        category: parsed.values.category,
+        title: parsed.values.title,
+        project: parsed.values.project,
+        title_pattern: parsed.values['title-pattern'],
+    };
+    const confirm = parsed.values.confirm === true;
+    const isSingleTarget = Boolean(input.ref) || Boolean(input.category && input.title);
+    if (input.title_pattern && !input.category && !input.project) {
+        io.stderr(`--title-pattern requires --category or --project as a scope guard.\n`);
+        return 2;
+    }
+    const hasAny = input.ref || input.category || input.project || input.title_pattern;
+    if (!hasAny) {
+        io.stderr(`Nothing to forget.\n${USAGE}`);
+        return 2;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    // Scope deletion ceremony holds at every surface (store-convergence
+    // §"One guard grammar") — the --json fast path must not bypass the gate.
+    if (!isSingleTarget && !confirm) {
+        const preview = await forget(env.contextDir, { ...input, confirm: false });
+        if (env.json) {
+            renderJson(io, { deleted: [], preview, confirmRequired: true });
+        }
+        else {
+            io.stdout(preview.endsWith('\n') ? preview : preview + '\n');
+            io.stdout('Re-run with --confirm to delete.\n');
+        }
+        return 2;
+    }
+    if (env.json) {
+        const backend = createBackend(env.contextDir);
+        const result = await backend.forget(input);
+        renderJson(io, result);
+        return result.deleted.length === 0 ? 3 : 0;
+    }
+    const text = await forget(env.contextDir, { ...input, confirm });
+    io.stdout(text.endsWith('\n') ? text : text + '\n');
+    return /not found|No memories matched/i.test(text) ? 3 : 0;
+}

package/dist/cli/harness.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/harness.js

@@ -0,0 +1,91 @@
+/**
+/**
+ * loom harness — manifest lifecycle for harness adapters.
+ *
+ * The only subcommand is `init`: writes a manifest template to
+ * <contextDir>/harnesses/<name>.md. Reading is implicit — identity()
+ * already composes the manifest from disk.
+ */
+import { parseArgs } from 'node:util';
+import { assertStackVersionCompatible } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+import { renderJson } from './io.js';
+import { initHarness } from '../blocks/harness.js';
+const USAGE = `Usage: loom harness <subcommand> [options]
+
+Subcommands:
+  init [<name>]    Write a manifest template for <name>
+
+Options (init):
+  --force          Overwrite existing manifest
+  --json           Emit InitResult as JSON
+
+<name> falls back to --client, then $LOOM_CLIENT.
+
+Global: --context-dir, --client, --json, --help
+`;
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    const sub = rest[0];
+    const subRest = rest.slice(1);
+    if (!sub || sub === '--help' || sub === '-h') {
+        io.stdout(USAGE);
+        return sub ? 0 : 2;
+    }
+    if (sub !== 'init') {
+        io.stderr(`Unknown harness subcommand: ${sub}\n${USAGE}`);
+        return 2;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: subRest,
+            options: {
+                force: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+            allowPositionals: true,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const name = parsed.positionals[0] ?? env.client;
+    if (!name) {
+        io.stderr('loom harness init: <name> required (or pass --client / set $LOOM_CLIENT)\n');
+        return 2;
+    }
+    try {
+        const result = await initHarness(env.contextDir, name, {
+            overwrite: parsed.values.force === true,
+        });
+        if (env.json) {
+            renderJson(io, result);
+            return 0;
+        }
+        io.stdout(`${result.name}: ${result.path} (${result.action})\n`);
+        return 0;
+    }
+    catch (err) {
+        if (err.message.startsWith('Invalid harness name')) {
+            io.stderr(`${err.message}\n`);
+            return 2;
+        }
+        io.stderr(`loom harness init: ${err.message}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function runCli(argv: string[], io?: IOStreams): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,127 @@
+/**
+ * CLI dispatcher — top-level --help / --version plus subcommand routing.
+ * Individual subcommand files land in Tasks 2–10.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveRepoRoot } from '../config.js';
+import { realStreams } from './io.js';
+import { SUBCOMMANDS } from './subcommands.js';
+const TOP_HELP = `Usage: loom <command> [options]
+
+Commands:
+  wake               Print agent identity to stdout
+  recall <query>     Search memories
+  remember <title>   Save a new memory (body via stdin/$EDITOR)
+  update <ref>       Modify an existing memory
+  forget <ref|scope> Remove memories
+  memory list|prune|similar|audit
+                     Browse / clean / find duplicates / health report
+  knowledge write|recall|maintain
+                     Write / search / health-report the knowledge store
+  update-identity    Edit preferences.md / self-model.md sections
+  bootstrap          Initialize a fresh agent
+  serve              Explicit MCP stdio startup (same as no args)
+  inject             Write loom identity pointer into harness dotfiles
+  harness init      Scaffold a harness manifest from template
+  install           Write loom-setup skill into a harness's skills dir
+  doctor            Probe the loom environment (read-only)
+  migrate           Apply pending schema migrations to memories.db
+
+Global flags:
+  --context-dir <path>   Agent context dir (default: $LOOM_CONTEXT_DIR or ~/.config/loom/default)
+  --client <name>        Harness adapter hint (default: $LOOM_CLIENT)
+  --model <name>         Model manifest hint (default: $LOOM_MODEL)
+  --json                 Machine-readable output
+  --help, -h             Show help
+  --version, -V          Print loom version
+
+Run 'loom <command> --help' for per-command usage.
+`;
+async function readVersion() {
+    const pkg = JSON.parse(await readFile(join(resolveRepoRoot(), 'package.json'), 'utf-8'));
+    return pkg.version;
+}
+export async function runCli(argv, io = realStreams()) {
+    const first = argv[0];
+    if (first === '--help' || first === '-h' || first === undefined) {
+        io.stdout(TOP_HELP);
+        return 0;
+    }
+    if (first === '--version' || first === '-V') {
+        io.stdout(`loom v${await readVersion()}\n`);
+        return 0;
+    }
+    if (!SUBCOMMANDS.includes(first)) {
+        io.stderr(`Unknown subcommand: ${first}\n`);
+        io.stderr(TOP_HELP);
+        return 2;
+    }
+    const sub = first;
+    const rest = argv.slice(1);
+    switch (sub) {
+        case 'wake': {
+            const { run } = await import('./wake.js');
+            return run(rest, io);
+        }
+        case 'recall': {
+            const { run } = await import('./recall.js');
+            return run(rest, io);
+        }
+        case 'memory': {
+            const { run } = await import('./memory.js');
+            return run(rest, io);
+        }
+        case 'knowledge': {
+            const { run } = await import('./knowledge.js');
+            return run(rest, io);
+        }
+        case 'forget': {
+            const { run } = await import('./forget.js');
+            return run(rest, io);
+        }
+        case 'remember': {
+            const { run } = await import('./remember.js');
+            return run(rest, io);
+        }
+        case 'update': {
+            const { run } = await import('./update.js');
+            return run(rest, io);
+        }
+        case 'bootstrap': {
+            const { run } = await import('./bootstrap.js');
+            return run(rest, io);
+        }
+        case 'serve': {
+            const { run } = await import('./serve.js');
+            return run(rest, io);
+        }
+        case 'update-identity': {
+            const { run } = await import('./update-identity.js');
+            return run(rest, io);
+        }
+        case 'inject': {
+            const { run } = await import('./inject.js');
+            return run(rest, io);
+        }
+        case 'harness': {
+            const { run } = await import('./harness.js');
+            return run(rest, io);
+        }
+        case 'install': {
+            const { run } = await import('./install.js');
+            return run(rest, io);
+        }
+        case 'doctor': {
+            const { run } = await import('./doctor.js');
+            return run(rest, io);
+        }
+        case 'migrate': {
+            const { run } = await import('./migrate.js');
+            return run(rest, io);
+        }
+        default:
+            io.stderr(`Subcommand not implemented yet: ${sub}\n`);
+            return 2;
+    }
+}

package/dist/cli/inject.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;