@jbarket/loomai 0.5.0

package/dist/injection/writer.d.ts

@@ -0,0 +1,25 @@
+export type WriteAction = 'created' | 'appended' | 'updated' | 'no-change';
+export interface WriteResult {
+    action: WriteAction;
+    path: string;
+    bytesWritten: number;
+}
+export type PreviewAction = WriteAction;
+export declare class MalformedMarkersError extends Error {
+    readonly path: string;
+    readonly reason: string;
+    constructor(path: string, reason: string);
+}
+export interface MarkerBounds {
+    startIdx: number;
+    endTerminusIdx: number;
+}
+export declare function findMarkers(text: string, path: string): MarkerBounds | null;
+export declare function normalizeLF(s: string): string;
+export declare function atomicWrite(path: string, content: string, preserveModeFrom: string | null): Promise<number>;
+export declare function buildContent(existing: string | null, block: string, markers: MarkerBounds | null): {
+    next: string;
+    action: WriteAction;
+};
+export declare function writeManagedBlock(path: string, block: string): Promise<WriteResult>;
+export declare function previewWrite(path: string, block: string): Promise<PreviewAction>;

package/dist/injection/writer.js

@@ -0,0 +1,118 @@
+/**
+ * Marker-aware file writer for `loom inject`. Reads the target file,
+ * decides between create / append / replace / no-change, writes
+ * atomically via tmp-file + rename.
+ *
+ * The managed region is bounded by two HTML comments:
+ *   <!-- loom:start v1 harness=<key> -->
+ *   <!-- loom:end -->
+ * Only "loom:start" / "loom:end" literals are matched; the metadata
+ * (v1, harness=...) is informational for humans and is allowed to
+ * differ between on-disk markers and the new block.
+ */
+import { readFile, writeFile, rename, mkdir, stat, chmod } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class MalformedMarkersError extends Error {
+    path;
+    reason;
+    constructor(path, reason) {
+        super(`inject: malformed loom markers in ${path}: ${reason}; fix manually or delete markers and retry`);
+        this.path = path;
+        this.reason = reason;
+        this.name = 'MalformedMarkersError';
+    }
+}
+const START_RE = /<!--\s*loom:start(\s[^>]*)?-->/g;
+const END_RE = /<!--\s*loom:end\s*-->/g;
+export function findMarkers(text, path) {
+    const starts = [...text.matchAll(START_RE)];
+    const ends = [...text.matchAll(END_RE)];
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    if (starts.length > 1) {
+        throw new MalformedMarkersError(path, `${starts.length} start markers found, expected 1`);
+    }
+    if (ends.length > 1) {
+        throw new MalformedMarkersError(path, `${ends.length} end markers found, expected 1`);
+    }
+    if (starts.length !== ends.length) {
+        throw new MalformedMarkersError(path, `mismatched markers (start=${starts.length}, end=${ends.length})`);
+    }
+    const s = starts[0];
+    const e = ends[0];
+    const startIdx = s.index;
+    const endBegin = e.index;
+    const endTerminusIdx = endBegin + e[0].length;
+    if (endBegin < startIdx) {
+        throw new MalformedMarkersError(path, 'end marker appears before start marker');
+    }
+    return { startIdx, endTerminusIdx };
+}
+export function normalizeLF(s) {
+    return s.replace(/\r\n/g, '\n');
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith('\n') ? s : s + '\n';
+}
+async function readIfExists(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function atomicWrite(path, content, preserveModeFrom) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.loom.tmp`;
+    const buf = Buffer.from(content, 'utf-8');
+    await writeFile(tmp, buf);
+    if (preserveModeFrom) {
+        try {
+            const s = await stat(preserveModeFrom);
+            await chmod(tmp, s.mode & 0o777);
+        }
+        catch {
+            /* preserveModeFrom vanished between read and stat; leave tmp at default mode */
+        }
+    }
+    await rename(tmp, path);
+    return buf.byteLength;
+}
+export function buildContent(existing, block, markers) {
+    const blockLF = ensureTrailingNewline(block);
+    if (existing === null) {
+        return { next: blockLF, action: 'created' };
+    }
+    const norm = normalizeLF(existing);
+    if (markers === null) {
+        const withGap = norm.endsWith('\n') ? norm : norm + '\n';
+        const combined = ensureTrailingNewline(`${withGap}\n${blockLF}`);
+        return { next: combined, action: 'appended' };
+    }
+    const before = norm.slice(0, markers.startIdx);
+    const after = norm.slice(markers.endTerminusIdx);
+    const afterTrimmed = after.startsWith('\n') ? after.slice(1) : after;
+    const combined = ensureTrailingNewline(`${before}${blockLF.replace(/\n$/, '')}\n${afterTrimmed}`);
+    if (combined === norm) {
+        return { next: combined, action: 'no-change' };
+    }
+    return { next: combined, action: 'updated' };
+}
+export async function writeManagedBlock(path, block) {
+    const existing = await readIfExists(path);
+    const markers = existing !== null ? findMarkers(normalizeLF(existing), path) : null;
+    const { next, action } = buildContent(existing, block, markers);
+    if (action === 'no-change') {
+        return { action, path, bytesWritten: 0 };
+    }
+    const bytesWritten = await atomicWrite(path, next, existing !== null ? path : null);
+    return { action, path, bytesWritten };
+}
+export async function previewWrite(path, block) {
+    const existing = await readIfExists(path);
+    const markers = existing !== null ? findMarkers(normalizeLF(existing), path) : null;
+    return buildContent(existing, block, markers).action;
+}

package/dist/install/harnesses.d.ts

@@ -0,0 +1,26 @@
+export type InstallTargetKey = 'claude-code' | 'codex' | 'gemini-cli' | 'opencode' | 'other';
+export type ToolPrefix = 'mcp__loom__' | 'mcp_loom_' | 'loom_';
+export interface InstallTarget {
+    readonly key: InstallTargetKey;
+    readonly label: string;
+    /** Canonical skill directory. `null` for `other` (caller picks a path). */
+    readonly skillDir: string | null;
+    /** Hint for the skill prose — where this harness's MCP config lives. */
+    readonly mcpConfigHint: string | null;
+    /** How the user invokes the skill inside the harness. */
+    readonly invoke: string;
+    /** Short human-readable restart instruction. */
+    readonly restart: string;
+    readonly toolPrefix: ToolPrefix;
+}
+export declare const SKILL_FILENAME = "loom-setup.md";
+export declare const INSTALL_TARGETS: Readonly<Record<InstallTargetKey, InstallTarget>>;
+export declare const INSTALL_TARGET_KEYS: readonly InstallTargetKey[];
+export declare function isInstallTargetKey(s: string): s is InstallTargetKey;
+export declare function getInstallTarget(key: InstallTargetKey): InstallTarget;
+/**
+ * Resolve the skill file path for a target. Returns `null` for `other`
+ * (caller handles the dump-to-cwd branch). `home` overrides `homedir()`
+ * for tests.
+ */
+export declare function resolveSkillPath(t: InstallTarget, home?: string): string | null;

package/dist/install/harnesses.js

@@ -0,0 +1,90 @@
+/**
+ * Registry of install targets for `loom install`. Separate from
+ * `src/injection/harnesses.ts` (dotfile injection paths) because the
+ * skill-install convention differs per vendor: Claude Code uses
+ * `~/.claude/skills/`, other harnesses converge on `~/.agents/skills/`.
+ *
+ * See stack spec v1 §11 (Adapters) and the alpha.6 design doc.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const SKILL_FILENAME = 'loom-setup.md';
+const HOME = homedir();
+export const INSTALL_TARGETS = {
+    'claude-code': {
+        key: 'claude-code',
+        label: 'Claude Code',
+        skillDir: join(HOME, '.claude', 'skills'),
+        mcpConfigHint: '~/.claude.json or .mcp.json in the project root',
+        invoke: '/loom-setup',
+        restart: 'restart Claude Code (close and reopen)',
+        toolPrefix: 'mcp__loom__',
+    },
+    'codex': {
+        key: 'codex',
+        label: 'Codex',
+        skillDir: join(HOME, '.agents', 'skills'),
+        mcpConfigHint: '~/.codex/config.toml',
+        invoke: 'use the loom-setup skill',
+        restart: 'restart the Codex session',
+        toolPrefix: 'mcp_loom_',
+    },
+    'gemini-cli': {
+        key: 'gemini-cli',
+        label: 'Gemini CLI',
+        skillDir: join(HOME, '.agents', 'skills'),
+        mcpConfigHint: '~/.gemini/settings.json',
+        invoke: 'use the loom-setup skill',
+        restart: 'exit and restart Gemini CLI',
+        toolPrefix: 'mcp_loom_',
+    },
+    'opencode': {
+        key: 'opencode',
+        label: 'OpenCode',
+        skillDir: join(HOME, '.agents', 'skills'),
+        mcpConfigHint: '~/.config/opencode/config.json',
+        invoke: 'use the loom-setup skill',
+        restart: 'restart OpenCode',
+        toolPrefix: 'loom_',
+    },
+    'other': {
+        key: 'other',
+        label: 'Other (dump skill file to cwd)',
+        skillDir: null,
+        mcpConfigHint: null,
+        invoke: 'tell your agent to read loom-setup-skill.md and follow it',
+        restart: 'restart your harness after it finishes setup',
+        toolPrefix: 'mcp_loom_',
+    },
+};
+export const INSTALL_TARGET_KEYS = [
+    'claude-code',
+    'codex',
+    'gemini-cli',
+    'opencode',
+    'other',
+];
+export function isInstallTargetKey(s) {
+    return INSTALL_TARGET_KEYS.includes(s);
+}
+export function getInstallTarget(key) {
+    return INSTALL_TARGETS[key];
+}
+/**
+ * Resolve the skill file path for a target. Returns `null` for `other`
+ * (caller handles the dump-to-cwd branch). `home` overrides `homedir()`
+ * for tests.
+ */
+export function resolveSkillPath(t, home) {
+    if (t.skillDir === null)
+        return null;
+    if (home === undefined)
+        return join(t.skillDir, SKILL_FILENAME);
+    switch (t.key) {
+        case 'claude-code': return join(home, '.claude', 'skills', SKILL_FILENAME);
+        case 'codex':
+        case 'gemini-cli':
+        case 'opencode': return join(home, '.agents', 'skills', SKILL_FILENAME);
+        case 'other': return null;
+    }
+}

package/dist/install/names.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical agent-name validation. Used by `loom doctor`, `loom
+ * bootstrap` (tightening pending), and the install skill's interview.
+ * Reserved names anticipate the alpha.7+ `agents switch` pointer slot
+ * plus snapshot/export storage adjacent to agent dirs.
+ *
+ * See stack spec v1 §13 (Multi-agent layout).
+ */
+export declare const RESERVED_AGENT_NAMES: ReadonlySet<string>;
+export type NameCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateAgentName(name: string): NameCheck;

package/dist/install/names.js

@@ -0,0 +1,36 @@
+/**
+ * Canonical agent-name validation. Used by `loom doctor`, `loom
+ * bootstrap` (tightening pending), and the install skill's interview.
+ * Reserved names anticipate the alpha.7+ `agents switch` pointer slot
+ * plus snapshot/export storage adjacent to agent dirs.
+ *
+ * See stack spec v1 §13 (Multi-agent layout).
+ */
+export const RESERVED_AGENT_NAMES = new Set([
+    'current',
+    'default',
+    'config',
+    'backups',
+    'cache',
+    'tmp',
+    'shared',
+]);
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_LEN = 64;
+export function validateAgentName(name) {
+    if (name.length === 0)
+        return { ok: false, reason: 'Name is empty.' };
+    if (name.length > MAX_LEN) {
+        return { ok: false, reason: `Name is longer than ${MAX_LEN} characters.` };
+    }
+    if (!NAME_RE.test(name)) {
+        return {
+            ok: false,
+            reason: 'Name must be lowercase alphanumeric plus hyphens, starting with a letter or digit.',
+        };
+    }
+    if (RESERVED_AGENT_NAMES.has(name)) {
+        return { ok: false, reason: `"${name}" is reserved.` };
+    }
+    return { ok: true };
+}

package/dist/install/render.d.ts

@@ -0,0 +1,18 @@
+export type WriteAction = 'created' | 'skipped-exists' | 'skipped-stale' | 'overwritten';
+export interface WriteSkillResult {
+    path: string;
+    action: WriteAction;
+}
+export interface WriteSkillOpts {
+    force?: boolean;
+    dryRun?: boolean;
+}
+/**
+ * Write the bundled SKILL.md to `dest`. Idempotent: returns
+ * `skipped-exists` when destination already matches source,
+ * `skipped-stale` when content differs and `force` is unset (signals
+ * the on-disk copy is out of date), `overwritten` with `force: true`.
+ * `dryRun: true` short-circuits all writes but still reports the
+ * action that would have been taken.
+ */
+export declare function writeSkill(dest: string, opts?: WriteSkillOpts): Promise<WriteSkillResult>;

package/dist/install/render.js

@@ -0,0 +1,42 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { resolveSkillSourcePath } from './skill-source.js';
+async function pathExists(p) {
+    try {
+        await readFile(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write the bundled SKILL.md to `dest`. Idempotent: returns
+ * `skipped-exists` when destination already matches source,
+ * `skipped-stale` when content differs and `force` is unset (signals
+ * the on-disk copy is out of date), `overwritten` with `force: true`.
+ * `dryRun: true` short-circuits all writes but still reports the
+ * action that would have been taken.
+ */
+export async function writeSkill(dest, opts = {}) {
+    const source = await readFile(resolveSkillSourcePath(), 'utf-8');
+    const exists = await pathExists(dest);
+    if (!exists) {
+        if (!opts.dryRun) {
+            await mkdir(dirname(dest), { recursive: true });
+            await writeFile(dest, source, 'utf-8');
+        }
+        return { path: dest, action: 'created' };
+    }
+    const current = await readFile(dest, 'utf-8');
+    if (current === source) {
+        return { path: dest, action: 'skipped-exists' };
+    }
+    if (!opts.force) {
+        return { path: dest, action: 'skipped-stale' };
+    }
+    if (!opts.dryRun) {
+        await writeFile(dest, source, 'utf-8');
+    }
+    return { path: dest, action: 'overwritten' };
+}

package/dist/install/skill-source.d.ts

@@ -0,0 +1 @@
+export declare function resolveSkillSourcePath(): string;

package/dist/install/skill-source.js

@@ -0,0 +1,11 @@
+/**
+ * Resolve the bundled SKILL.md path. Works from both `src/` (dev via
+ * tsx) and `dist/` (published via `npx loom`) because
+ * `resolveRepoRoot()` walks one level up from the running module and
+ * both `src/` and `dist/` sit alongside `assets/` at the project root.
+ */
+import { join } from 'node:path';
+import { resolveRepoRoot } from '../config.js';
+export function resolveSkillSourcePath() {
+    return join(resolveRepoRoot(), 'assets', 'skill', 'SKILL.md');
+}

package/dist/path-safety.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns a human-readable error string when `value` cannot be used as a
+ * single path segment, or null when it is safe. Rejects empty strings,
+ * '.', '..', path separators (both / and \), and null bytes.
+ */
+export declare function pathSegmentError(value: string, paramName: string): string | null;
+/**
+ * Throwing variant of pathSegmentError — for block-level readers whose
+ * contract is to throw. Tool-layer functions that return error strings
+ * should call pathSegmentError directly instead.
+ */
+export declare function assertSafePathSegment(value: string, paramName: string): void;
+/**
+ * Write an identity-tier file atomically (tmp + rename). When the file
+ * already exists, its prior content is preserved as `<path>.bak` first —
+ * single generation, overwriting any older .bak. First-ever writes
+ * produce no .bak.
+ */
+export declare function atomicWriteWithBackup(path: string, content: string): Promise<void>;

package/dist/path-safety.js

@@ -0,0 +1,62 @@
+/**
+ * Path-segment validation and atomic identity writes.
+ *
+ * Boundary discipline (store-convergence spec): any param that becomes a
+ * file path segment (role, project, client, model, harness/model key)
+ * validates non-empty and separator-free at every reader, not just some
+ * writers. Without this, a value like "../../../home/user/secrets" walks
+ * out of the context directory and reads arbitrary .md files into agent
+ * context.
+ *
+ * Atomic identity writes (same spec): anything under the identity tier
+ * (IDENTITY.md, preferences.md, self-model.md) writes via tmp+rename with
+ * a single-generation `.bak` of the prior version. A crash mid-write must
+ * never truncate the creed.
+ */
+import { copyFile } from 'node:fs/promises';
+import { atomicWrite } from './injection/writer.js';
+/**
+ * Returns a human-readable error string when `value` cannot be used as a
+ * single path segment, or null when it is safe. Rejects empty strings,
+ * '.', '..', path separators (both / and \), and null bytes.
+ */
+export function pathSegmentError(value, paramName) {
+    if (value === '' ||
+        value === '.' ||
+        value === '..' ||
+        value.includes('/') ||
+        value.includes('\\') ||
+        value.includes('\0')) {
+        return (`Invalid ${paramName} ${JSON.stringify(value)}: ` +
+            'must be a non-empty name with no path separators.');
+    }
+    return null;
+}
+/**
+ * Throwing variant of pathSegmentError — for block-level readers whose
+ * contract is to throw. Tool-layer functions that return error strings
+ * should call pathSegmentError directly instead.
+ */
+export function assertSafePathSegment(value, paramName) {
+    const error = pathSegmentError(value, paramName);
+    if (error)
+        throw new Error(error);
+}
+/**
+ * Write an identity-tier file atomically (tmp + rename). When the file
+ * already exists, its prior content is preserved as `<path>.bak` first —
+ * single generation, overwriting any older .bak. First-ever writes
+ * produce no .bak.
+ */
+export async function atomicWriteWithBackup(path, content) {
+    let existed = true;
+    try {
+        await copyFile(path, `${path}.bak`);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        existed = false;
+    }
+    await atomicWrite(path, content, existed ? path : null);
+}

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface LoomServerConfig {
+    contextDir: string;
+}
+export interface LoomServerInstance {
+    server: McpServer;
+}
+export declare function createLoomServer(config: LoomServerConfig): LoomServerInstance;