@jbarket/loomai 0.5.0 → 0.7.0

package/dist/cli/person.js

@@ -0,0 +1,116 @@
+/**
+ * loom person — read person cards (docs/specs/person-cards.md).
+ *
+ *   loom person show <slug> [--include-archived] [--json]
+ *   loom person list [--include-archived] [--json]
+ *
+ * Read-only: cards are written through the MCP tools. Exit codes for show:
+ * 0 found, 3 no such card, 4 archived (without --include-archived), 1 error.
+ * A bridge can splice `show` output into a prompt and treat any non-zero
+ * exit as "no card".
+ */
+import { parseArgs } from 'node:util';
+import { readPerson, listPeople } from '../tools/person.js';
+import { assertStackVersionCompatible } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+import { renderJson } from './io.js';
+const USAGE = `Usage: loom person <subcommand> [options]
+
+Subcommands:
+  show <slug>   Print the rendered card (or the person result with --json)
+  list          List cards: slug, name, freshness counts, memories since synthesis
+
+Options:
+  --include-archived   Show/list archived cards too
+  --json               Machine-readable output
+
+Exit codes (show): 0 found, 3 no such card, 4 archived, 1 error.
+`;
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    const sub = rest[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        io.stdout(USAGE);
+        return sub ? 0 : 2;
+    }
+    if (sub !== 'show' && sub !== 'list') {
+        io.stderr(`Unknown person subcommand: ${sub}\n${USAGE}`);
+        return 2;
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest.slice(1),
+            options: { 'include-archived': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+            allowPositionals: true,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    const includeArchived = Boolean(parsed.values['include-archived']);
+    if (sub === 'list') {
+        if (parsed.positionals.length) {
+            io.stderr(`person list takes no arguments.\n${USAGE}`);
+            return 2;
+        }
+        const entries = listPeople(env.contextDir, includeArchived);
+        if (env.json) {
+            renderJson(io, entries);
+            return 0;
+        }
+        io.stdout(entries.length === 0
+            ? 'no person cards\n'
+            : entries
+                .map((e) => `${e.slug}\t${e.name}${e.archived ? ' [archived]' : ''}\tupdated ${e.updated}\t` +
+                `synthesized ${e.synthesized_at ?? 'never'}\tstale ${e.stale}\tunverified ${e.unverified}\t` +
+                `memories since synthesis ${e.memories_since_synthesis}`)
+                .join('\n') + '\n');
+        return 0;
+    }
+    const slug = parsed.positionals[0];
+    if (!slug || parsed.positionals.length > 1) {
+        io.stderr(`person show takes one slug.\n${USAGE}`);
+        return 2;
+    }
+    let result;
+    try {
+        result = readPerson(env.contextDir, slug, includeArchived);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    if (!result.found) {
+        if (env.json)
+            renderJson(io, result);
+        else
+            io.stderr(`no card for ${slug}\n`);
+        return 3;
+    }
+    if (!('rendered' in result)) {
+        if (env.json)
+            renderJson(io, result);
+        else
+            io.stderr(`card for ${slug} is archived (pass --include-archived)\n`);
+        return 4;
+    }
+    if (env.json)
+        renderJson(io, result);
+    else
+        io.stdout(result.rendered + '\n');
+    return 0;
+}

package/dist/cli/pieces.d.ts

@@ -0,0 +1,24 @@
+import type { IOStreams } from './io.js';
+/** A piece name: lowercase, starts with a letter, no dots or slashes. */
+export declare const PIECE_NAME: RegExp;
+/** Whether `name` could be a piece (valid name, not a core subcommand). */
+export declare function isPieceName(name: string | undefined): name is string;
+/** The executable that answers `loom <name>`: the first `loom-<name>` on PATH. */
+export declare function findPiece(name: string, env: NodeJS.ProcessEnv): string | undefined;
+export interface InstalledPiece {
+    name: string;
+    path: string;
+}
+/** Every installed piece, first on PATH wins (the one `loom <name>` would run). */
+export declare function listPieces(env: NodeJS.ProcessEnv): InstalledPiece[];
+/**
+ * Run a piece with `args`, passing loom's env through unchanged. With the
+ * process's own streams the piece inherits the terminal (so it can prompt,
+ * e.g. for a secret's value); with captured streams (tests) its output is
+ * forwarded. Exit code: the piece's own, 128+signal if it was killed, 127 if
+ * it couldn't start.
+ */
+export declare function runPiece(path: string, args: string[], io: IOStreams): Promise<number>;
+/** `loom pieces`: list what's installed. */
+export declare function runPiecesCommand(argv: string[], io: IOStreams): number;
+export declare const PIECES_USAGE = "Usage: loom pieces [--json]\n\nList the installed pieces: every executable named loom-<name> on PATH, which\nanswers `loom <name> ...`. The first one on PATH wins; core commands can't be\nshadowed. See docs/extensions.md.\n";

package/dist/cli/pieces.js

@@ -0,0 +1,139 @@
+/**
+ * Pieces — `loom <piece> ...` runs the installed extension `loom-<piece>`
+ * (docs/extensions.md, t-1466).
+ *
+ * Git-style dispatch: an executable named `loom-tasks` on PATH answers
+ * `loom tasks list`. loom doesn't know what a piece does and never links its
+ * code: the piece is its own program, reached as its own process, so it can't
+ * reach into loom's stores and can be swapped for anything else that installs
+ * the same name and honors that piece's contract.
+ *
+ * Core subcommands always win (a `loom-recall` on PATH is never consulted),
+ * and a name must match PIECE_NAME before PATH is searched at all.
+ */
+import { accessSync, constants, readdirSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+import { SUBCOMMANDS } from './subcommands.js';
+/** A piece name: lowercase, starts with a letter, no dots or slashes. */
+export const PIECE_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+const PREFIX = 'loom-';
+const CORE = new Set(SUBCOMMANDS);
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pathDirs(env) {
+    return (env.PATH ?? '').split(delimiter).filter(Boolean);
+}
+/** Whether `name` could be a piece (valid name, not a core subcommand). */
+export function isPieceName(name) {
+    return name !== undefined && PIECE_NAME.test(name) && !CORE.has(name);
+}
+/** The executable that answers `loom <name>`: the first `loom-<name>` on PATH. */
+export function findPiece(name, env) {
+    if (!isPieceName(name))
+        return undefined;
+    for (const dir of pathDirs(env)) {
+        const candidate = join(dir, PREFIX + name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Every installed piece, first on PATH wins (the one `loom <name>` would run). */
+export function listPieces(env) {
+    const seen = new Map();
+    for (const dir of pathDirs(env)) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries.sort()) {
+            if (!entry.startsWith(PREFIX))
+                continue;
+            const name = entry.slice(PREFIX.length);
+            if (seen.has(name) || !isPieceName(name))
+                continue;
+            const path = join(dir, entry);
+            if (isExecutableFile(path))
+                seen.set(name, path);
+        }
+    }
+    return [...seen].map(([name, path]) => ({ name, path })).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Run a piece with `args`, passing loom's env through unchanged. With the
+ * process's own streams the piece inherits the terminal (so it can prompt,
+ * e.g. for a secret's value); with captured streams (tests) its output is
+ * forwarded. Exit code: the piece's own, 128+signal if it was killed, 127 if
+ * it couldn't start.
+ */
+export async function runPiece(path, args, io) {
+    const inherit = io.stdin === process.stdin;
+    const child = spawn(path, args, {
+        env: io.env,
+        stdio: inherit ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+    });
+    if (!inherit) {
+        child.stdout?.on('data', (d) => io.stdout(d.toString()));
+        child.stderr?.on('data', (d) => io.stderr(d.toString()));
+        if (child.stdin) {
+            if (io.stdinIsTTY)
+                child.stdin.end();
+            else
+                io.stdin.pipe(child.stdin);
+        }
+    }
+    return new Promise((resolve) => {
+        child.on('error', (err) => {
+            io.stderr(`loom: couldn't run ${path}: ${err.message}\n`);
+            resolve(127);
+        });
+        child.on('close', (code, signal) => {
+            if (signal)
+                resolve(128 + (osConstants.signals[signal] ?? 0));
+            else
+                resolve(code ?? 1);
+        });
+    });
+}
+/** `loom pieces`: list what's installed. */
+export function runPiecesCommand(argv, io) {
+    const json = argv.includes('--json');
+    const rest = argv.filter((a) => a !== '--json');
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.stdout(PIECES_USAGE);
+        return 0;
+    }
+    if (rest.length) {
+        io.stderr(`loom pieces takes no arguments.\n${PIECES_USAGE}`);
+        return 2;
+    }
+    const pieces = listPieces(io.env);
+    if (json) {
+        io.stdout(JSON.stringify(pieces, null, 2) + '\n');
+        return 0;
+    }
+    io.stdout(pieces.length === 0
+        ? 'no pieces installed (a piece is an executable named loom-<name> on PATH)\n'
+        : pieces.map((p) => `${p.name}\t${p.path}`).join('\n') + '\n');
+    return 0;
+}
+export const PIECES_USAGE = `Usage: loom pieces [--json]
+
+List the installed pieces: every executable named loom-<name> on PATH, which
+answers \`loom <name> ...\`. The first one on PATH wins; core commands can't be
+shadowed. See docs/extensions.md.
+`;

package/dist/cli/recall.js

@@ -13,7 +13,8 @@ Search memories semantically.
 
 Options:
   --category <name>      Filter by category
-  --project <name>       Filter by project
+  --project <name>       Scope to a project — excludes other projects' project-scoped
+                          memories (t-337); global-scoped memories still come through
   --limit <n>            Max results (default backend-specific)
   --diversity <f>        MMR diversity 0..1 (default 0.3); 0 = pure relevance order
   --json                 Emit MemoryMatch[] as JSON

package/dist/cli/remember.js

@@ -14,6 +14,9 @@ Body is read from stdin (when piped) or $EDITOR (when interactive).
 Options:
   --category <name>      Category: user|project|self|feedback|reference|pursuit (default: reference)
   --project <name>       Project tag
+  --scope <project|global>  Override recall visibility (default: category default — see
+                          backends/scope.ts; "global" for a fact that applies regardless
+                          of which project it was learned on)
   --ttl <dur>            TTL like "7d", "30d", or "permanent"
   --refs <csv>           Comma-separated reference refs stored in metadata
   --meta <json>          JSON object merged into metadata (e.g. '{"where":"voice"}')
@@ -30,6 +33,7 @@ export async function run(argv, io) {
             options: {
                 category: { type: 'string' },
                 project: { type: 'string' },
+                scope: { type: 'string' },
                 ttl: { type: 'string' },
                 refs: { type: 'string' },
                 meta: { type: 'string' },
@@ -57,6 +61,11 @@ export async function run(argv, io) {
         io.stderr(`Unknown category "${category}". Valid categories: ${MEMORY_CATEGORIES.join(', ')}.\n`);
         return 2;
     }
+    const scope = parsed.values.scope;
+    if (scope !== undefined && scope !== 'project' && scope !== 'global') {
+        io.stderr(`--scope must be "project" or "global".\n`);
+        return 2;
+    }
     const env = resolveEnv(global, io.env);
     try {
         assertStackVersionCompatible(env.contextDir);
@@ -99,6 +108,7 @@ export async function run(argv, io) {
         title,
         content: body,
         project: parsed.values.project,
+        scope,
         ttl: parsed.values.ttl,
         metadata,
     });

package/dist/cli/remote.d.ts

@@ -0,0 +1,36 @@
+import type { IOStreams } from './io.js';
+export declare const REMOTE_VERBS: ReadonlySet<string>;
+/**
+ * `memory` subcommands with no MCP equivalent: recompute-salience rewrites
+ * every row's salience, and recall-stats returns other callers' query text.
+ * The consolidation lane runs them where the stack is.
+ */
+export declare const LOCAL_MEMORY_SUBCOMMANDS: ReadonlySet<string>;
+/** POST /cli request body. */
+export interface CliRequest {
+    argv: string[];
+    /** The body for verbs that read one (remember, update). */
+    stdin?: string;
+    /** Harness hints only; the server owns everything else in its env. */
+    env?: {
+        LOOM_CLIENT?: string;
+        LOOM_MODEL?: string;
+    };
+}
+/** POST /cli 200 response body. */
+export interface CliResponse {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * The /cli endpoint beside the MCP URL: http://h:8787/mcp → http://h:8787/cli,
+ * and a proxy prefix is kept (https://h/loom/mcp → https://h/loom/cli). A URL
+ * without /mcp is taken as the server's base (http://h:8787 → /cli).
+ */
+export declare function cliEndpoint(url: string): URL;
+/**
+ * Run `sub` with `rest` (the argv minus the subcommand token, globals
+ * included) on the loom-http at `url`.
+ */
+export declare function runRemote(sub: string, rest: string[], url: string, io: IOStreams): Promise<number>;

package/dist/cli/remote.js

@@ -0,0 +1,173 @@
+/**
+ * Remote mode — run a CLI verb against a loom-http server instead of a
+ * local stack (t-1472).
+ *
+ * A body whose loom lives elsewhere (a container, another host) still has
+ * hooks and scripts that shell out to `loom recall`, `loom remember --json`,
+ * `loom person show`. With `--url` or LOOM_URL set, those verbs ship their
+ * argv (and stdin body) to loom-http's POST /cli, which runs the SAME CLI
+ * server-side against its own stack and returns stdout, stderr and the exit
+ * code. Output, --json shapes and exit codes match the local CLI by
+ * construction, not by a second implementation that could drift.
+ *
+ * The server's half is src/transport/cli-endpoint.ts. Only REMOTE_VERBS
+ * travel: the ones that read or write the stores, every one of which the
+ * MCP tools already expose under the same bearer token, so /cli grants
+ * nothing /mcp doesn't. Two `memory` subcommands have no MCP tool and stay
+ * local too (LOCAL_MEMORY_SUBCOMMANDS). Verbs about the local machine (inject, install,
+ * doctor, serve, bootstrap, migrate, harness, update-identity) always run
+ * locally.
+ *
+ * The bearer token comes from a file (LOOM_TOKEN_FILE), never argv, so it
+ * stays out of `ps` and shell history.
+ */
+import { readFile } from 'node:fs/promises';
+import { readBody } from './io.js';
+export const REMOTE_VERBS = new Set([
+    'wake', 'recall', 'remember', 'update', 'forget', 'memory', 'knowledge', 'person',
+]);
+/**
+ * `memory` subcommands with no MCP equivalent: recompute-salience rewrites
+ * every row's salience, and recall-stats returns other callers' query text.
+ * The consolidation lane runs them where the stack is.
+ */
+export const LOCAL_MEMORY_SUBCOMMANDS = new Set(['recompute-salience', 'recall-stats']);
+const REMOTE_TIMEOUT_MS = 300_000;
+/** `argv` with every `--url <value>` pair removed. */
+function withoutUrl(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--url') {
+            i++;
+            continue;
+        }
+        out.push(argv[i]);
+    }
+    return out;
+}
+/**
+ * Whether the local CLI would read a body for this call. Mirrors the verbs'
+ * own rules (remember always; update unless it's a pure --confirm or
+ * --contradict observation; neither under --help). Reading stdin for any other verb would hang a caller whose stdin
+ * is an open pipe it never writes to.
+ */
+function readsBody(sub, argv) {
+    if (argv.includes('--help') || argv.includes('-h'))
+        return false;
+    if (sub === 'remember')
+        return true;
+    if (sub === 'update')
+        return !argv.some((a) => /^--(confirm|contradict)(=|$)/.test(a));
+    return false;
+}
+/**
+ * The /cli endpoint beside the MCP URL: http://h:8787/mcp → http://h:8787/cli,
+ * and a proxy prefix is kept (https://h/loom/mcp → https://h/loom/cli). A URL
+ * without /mcp is taken as the server's base (http://h:8787 → /cli).
+ */
+export function cliEndpoint(url) {
+    const u = new URL(url);
+    const base = u.pathname.replace(/\/+$/, '').replace(/\/mcp$/, '');
+    u.pathname = `${base}/cli`;
+    u.search = '';
+    u.hash = '';
+    return u;
+}
+function isCliResponse(v) {
+    const r = v;
+    return typeof r === 'object' && r !== null &&
+        Number.isInteger(r.exitCode) && typeof r.stdout === 'string' && typeof r.stderr === 'string';
+}
+/**
+ * Run `sub` with `rest` (the argv minus the subcommand token, globals
+ * included) on the loom-http at `url`.
+ */
+export async function runRemote(sub, rest, url, io) {
+    const args = withoutUrl(rest);
+    if (args.some((a) => a === '--context-dir' || a.startsWith('--context-dir='))) {
+        io.stderr(`loom: --context-dir names a local stack, but this call goes to ${url}. ` +
+            `Drop --url / unset LOOM_URL to use the local one.\n`);
+        return 2;
+    }
+    let endpoint;
+    try {
+        endpoint = cliEndpoint(url);
+    }
+    catch {
+        io.stderr(`loom: not a URL: ${url}\n`);
+        return 2;
+    }
+    const headers = { 'content-type': 'application/json' };
+    const tokenFile = io.env.LOOM_TOKEN_FILE;
+    if (tokenFile) {
+        let token;
+        try {
+            token = (await readFile(tokenFile, 'utf-8')).trim();
+        }
+        catch (err) {
+            io.stderr(`loom: can't read LOOM_TOKEN_FILE: ${err.message}\n`);
+            return 1;
+        }
+        headers.authorization = `Bearer ${token}`;
+    }
+    const request = { argv: [sub, ...args] };
+    if (readsBody(sub, args)) {
+        // Local stdin or the local $EDITOR: an editor can't run over the wire.
+        try {
+            request.stdin = await readBody(io, sub);
+        }
+        catch (err) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+    }
+    const hints = {};
+    if (io.env.LOOM_CLIENT)
+        hints.LOOM_CLIENT = io.env.LOOM_CLIENT;
+    if (io.env.LOOM_MODEL)
+        hints.LOOM_MODEL = io.env.LOOM_MODEL;
+    if (Object.keys(hints).length)
+        request.env = hints;
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        const cause = err.cause?.message;
+        io.stderr(`loom: can't reach ${endpoint}: ${cause ?? err.message}\n`);
+        return 1;
+    }
+    const text = await res.text();
+    if (res.status !== 200) {
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch { /* not JSON */ }
+        if (res.status === 404)
+            message = `no CLI endpoint at ${endpoint} (an older loom-http, or a knowledge-only server)`;
+        io.stderr(`loom: ${endpoint} answered ${res.status}: ${message}\n`);
+        return res.status === 400 ? 2 : 1;
+    }
+    let out;
+    try {
+        out = JSON.parse(text);
+    }
+    catch {
+        io.stderr(`loom: ${endpoint} sent a response that isn't JSON\n`);
+        return 1;
+    }
+    // A malformed answer must never read as success (a missing exitCode would exit 0).
+    if (!isCliResponse(out)) {
+        io.stderr(`loom: ${endpoint} sent a malformed CLI response\n`);
+        return 1;
+    }
+    io.stdout(out.stdout);
+    io.stderr(out.stderr);
+    return out.exitCode;
+}

package/dist/cli/serve.d.ts

@@ -1,2 +1,9 @@
 import type { IOStreams } from './io.js';
+/**
+ * Parse "identity:token,identity:token" into a token → identity map ready
+ * for startHttpServer's `tokens` option (checkBearerMulti). Throws with a
+ * message naming the offending pair on malformed input — fail loud at CLI
+ * startup rather than silently dropping an identity.
+ */
+export declare function parseIdentityTokens(raw: string): Record<string, string>;
 export declare function run(argv: string[], io: IOStreams): Promise<number>;