@siddicky/oh-my-musecode 0.1.0

package/dist/paths.js

@@ -0,0 +1,167 @@
+/**
+ * State-root resolution and protected-path enforcement.
+ *
+ * muse protects `.agents/` and `.muse/` with two independent layers: a mediated
+ * `edit_file` write is held for human review with no standing grant, and a shell
+ * write fails read-only at the sandbox. Runtime state therefore cannot live in
+ * either, so oh-my-musecode keeps its own root at `.omm/`.
+ *
+ * This module is the single place that decides whether a path is writable, so the
+ * hooks and the MCP state server cannot drift apart on it.
+ */
+import { existsSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+/** Directory name of the oh-my-musecode state root, relative to the workspace. */
+export const STATE_ROOT_DIRNAME = '.omm';
+/**
+ * Path prefixes muse protects. A write that resolves inside any of these is
+ * refused before it reaches the filesystem, so the failure is a clear error
+ * rather than an opaque read-only sandbox rejection mid-run.
+ */
+export const PROTECTED_DIRNAMES = Object.freeze(['.agents', '.muse', '.git']);
+export class ProtectedPathError extends Error {
+    path;
+    protectedSegment;
+    constructor(path, protectedSegment) {
+        super(`Refusing to write ${path}: \`${protectedSegment}/\` is a muse-protected path. ` +
+            `State belongs under ${STATE_ROOT_DIRNAME}/.`);
+        this.name = 'ProtectedPathError';
+        this.path = path;
+        this.protectedSegment = protectedSegment;
+    }
+}
+export class EscapedStateRootError extends Error {
+    path;
+    constructor(path, stateRoot) {
+        super(`Refusing to write ${path}: resolved outside the state root ${stateRoot}.`);
+        this.name = 'EscapedStateRootError';
+        this.path = path;
+    }
+}
+/** Absolute path of the state root for a workspace. */
+export function stateRoot(workspaceRoot) {
+    return join(resolve(workspaceRoot), STATE_ROOT_DIRNAME);
+}
+/**
+ * Creates the state root if absent. Returns its absolute path.
+ *
+ * Called by the SessionStart hook. Deliberately does not touch `.agents/` or
+ * `.muse/`, which the harness owns.
+ */
+export function ensureStateRoot(workspaceRoot) {
+    const root = stateRoot(workspaceRoot);
+    if (!existsSync(root)) {
+        mkdirSync(join(root, 'state'), { recursive: true });
+    }
+    return root;
+}
+/** True when `candidate` is inside `parent` (or is `parent` itself). */
+function isInside(parent, candidate) {
+    const rel = relative(parent, candidate);
+    // `rel.startsWith('..')` alone would also reject a legitimate in-root name like
+    // `..notes`, so require the `..` to be a whole segment.
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+export class SymlinkedStateRootError extends Error {
+    path;
+    constructor(root) {
+        super(`Refusing to use ${root}: the state root itself is a symbolic link. ` +
+            `Resolving it would relocate every state operation to its target, which is ` +
+            `exactly the escape the traversal check exists to prevent.`);
+        this.name = 'SymlinkedStateRootError';
+        this.path = root;
+    }
+}
+export class SymlinkTraversalError extends Error {
+    path;
+    constructor(path, linkPath) {
+        super(`Refusing to write ${path}: the path crosses a symbolic link (${linkPath}). ` +
+            `Symlinks can point outside the state root, so they are not followed.`);
+        this.name = 'SymlinkTraversalError';
+        this.path = path;
+    }
+}
+/**
+ * Refuses any path that traverses a symbolic link between the state root and the
+ * target.
+ *
+ * Lexical containment is not sufficient on its own: `.omm/link -> /etc` passes
+ * every string check while resolving outside the root. Walking the existing
+ * prefix and rejecting symlinks closes that escape for both the final component
+ * and every intermediate directory.
+ *
+ * A residual TOCTOU window remains — the path is checked, then opened — because
+ * Node exposes no `openat`-style confined traversal. Narrowing it further would
+ * need a native binding; callers should not treat this as a boundary against a
+ * local attacker who can create symlinks inside `.omm/` concurrently.
+ */
+function assertNoSymlinkTraversal(root, resolved) {
+    const rel = relative(root, resolved);
+    if (rel === '')
+        return;
+    let current = root;
+    for (const segment of rel.split(sep)) {
+        current = join(current, segment);
+        let stats;
+        try {
+            stats = lstatSync(current);
+        }
+        catch {
+            // Does not exist yet: nothing below it can be a link either.
+            return;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new SymlinkTraversalError(resolved, current);
+        }
+    }
+}
+/**
+ * Resolves a caller-supplied path against the state root and refuses anything
+ * that escapes it or lands in a muse-protected directory.
+ *
+ * Both checks are needed and neither subsumes the other: the protected-path check
+ * gives an accurate message for the common mistake (`../../.agents/AGENTS.md`),
+ * while the containment check is the actual security boundary and catches every
+ * other escape.
+ *
+ * @throws {ProtectedPathError} when the path resolves into `.agents/`, `.muse/` or `.git/`
+ * @throws {EscapedStateRootError} when the path resolves outside the state root
+ */
+export function resolveWritablePath(workspaceRoot, requestedPath) {
+    const workspace = resolve(workspaceRoot);
+    const root = stateRoot(workspace);
+    const resolved = isAbsolute(requestedPath)
+        ? resolve(requestedPath)
+        : resolve(root, requestedPath);
+    // Report a protected hit specifically, even when the path also escaped the
+    // state root — `../../.agents/AGENTS.md` is a more useful error than "escaped".
+    const segments = relative(workspace, resolved).split(sep);
+    for (const protectedName of PROTECTED_DIRNAMES) {
+        if (segments.includes(protectedName)) {
+            throw new ProtectedPathError(requestedPath, protectedName);
+        }
+    }
+    if (!isInside(root, resolved)) {
+        throw new EscapedStateRootError(requestedPath, root);
+    }
+    // Lexical containment passed; now make sure the path does not reach outside the
+    // root through a link.
+    //
+    // The root itself is checked FIRST and separately. Resolving it with realpath
+    // before checking would silently relocate every subsequent operation: with
+    // `.omm -> /somewhere/else`, the traversal walk starts inside the target and
+    // finds nothing wrong, handing out a complete external read/write/delete
+    // primitive. The root link must be refused, not followed.
+    if (existsSync(root)) {
+        if (lstatSync(root).isSymbolicLink()) {
+            throw new SymlinkedStateRootError(root);
+        }
+        // Safe now that the root is known to be a real directory: realpath only
+        // normalises symlinked ancestors of the workspace (on macOS /tmp is a link
+        // to /private/tmp), so containment comparisons still line up.
+        const realRoot = realpathSync(root);
+        assertNoSymlinkTraversal(realRoot, resolve(realRoot, relative(root, resolved)));
+    }
+    return resolved;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/personas.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Persona loading and prompt rendering.
+ *
+ * muse 1.0.3 rejects `agents` as a plugin capability entirely: a Claude-family
+ * plugin that declares it still loads, but the definitions are reported
+ * `agent-overlay-inactive` and never activate (see scripts/verify-manifest.mjs).
+ * So personas here are not muse agent definitions — they are plain data (a SOUL.md
+ * body plus a routing description and a narrowed toolset) that skills read and
+ * interpolate into a `subagent_spawn(role, objective)` prompt at call time. This
+ * module is the single place that resolves that data off disk.
+ *
+ * Each persona is a SOUL: the agent's "who," never the project's "what." Workspace
+ * paths, stack choices, and handoff formats belong in AGENTS.md / a runbook, not here.
+ */
+export interface Persona {
+    /** Matches the persona's directory name under personas/. */
+    readonly id: string;
+    /** Routing surface: what another agent reads to decide whether this persona fits. */
+    readonly description: string;
+    /** Narrowed toolset. Never widens whatever the spawning context already grants. */
+    readonly tools: readonly string[];
+    /** Full SOUL.md body: the persona's "who". */
+    readonly soul: string;
+}
+/**
+ * Loads every persona declared in personas/manifest.json, reading its SOUL.md
+ * from disk. Throws if the manifest and the SOUL.md files on disk disagree, or
+ * if any persona's `tools` array is empty (muse semantics: a child's tools may
+ * only narrow the inherited grant, never widen it — an empty toolset is a
+ * persona that can be spawned but can do nothing, which is never intended here).
+ */
+export declare function loadPersonas(): Persona[];
+/**
+ * Renders a persona's prompt for interpolation into a `subagent_spawn(role,
+ * objective)` call: the SOUL body, followed by its routing description as
+ * additional framing context.
+ *
+ * @throws {Error} naming the valid ids, if `id` does not match a loaded persona
+ */
+export declare function renderPersonaPrompt(id: string): string;

package/dist/personas.js

@@ -0,0 +1,93 @@
+/**
+ * Persona loading and prompt rendering.
+ *
+ * muse 1.0.3 rejects `agents` as a plugin capability entirely: a Claude-family
+ * plugin that declares it still loads, but the definitions are reported
+ * `agent-overlay-inactive` and never activate (see scripts/verify-manifest.mjs).
+ * So personas here are not muse agent definitions — they are plain data (a SOUL.md
+ * body plus a routing description and a narrowed toolset) that skills read and
+ * interpolate into a `subagent_spawn(role, objective)` prompt at call time. This
+ * module is the single place that resolves that data off disk.
+ *
+ * Each persona is a SOUL: the agent's "who," never the project's "what." Workspace
+ * paths, stack choices, and handoff formats belong in AGENTS.md / a runbook, not here.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+/**
+ * Personas directory, resolved relative to this module rather than the process
+ * cwd, so loading works the same whether this runs from src/ under ts-node or
+ * from the compiled dist/ output.
+ */
+const PERSONAS_DIR = join(MODULE_DIR, '..', 'personas');
+function readManifest() {
+    const manifestPath = join(PERSONAS_DIR, 'manifest.json');
+    const raw = readFileSync(manifestPath, 'utf8');
+    return JSON.parse(raw);
+}
+function readSoul(id) {
+    const soulPath = join(PERSONAS_DIR, id, 'SOUL.md');
+    try {
+        return readFileSync(soulPath, 'utf8').trim();
+    }
+    catch (err) {
+        throw new Error(`Persona "${id}" is listed in manifest.json but has no SOUL.md at ${soulPath}.`, { cause: err });
+    }
+}
+let cachedPersonas;
+/**
+ * Loads every persona declared in personas/manifest.json, reading its SOUL.md
+ * from disk. Throws if the manifest and the SOUL.md files on disk disagree, or
+ * if any persona's `tools` array is empty (muse semantics: a child's tools may
+ * only narrow the inherited grant, never widen it — an empty toolset is a
+ * persona that can be spawned but can do nothing, which is never intended here).
+ */
+export function loadPersonas() {
+    if (cachedPersonas)
+        return cachedPersonas;
+    const manifest = readManifest();
+    if (!Array.isArray(manifest.personas) || manifest.personas.length === 0) {
+        throw new Error(`personas/manifest.json must declare a non-empty "personas" array.`);
+    }
+    const seenIds = new Set();
+    const personas = manifest.personas.map((entry) => {
+        if (!entry.id || typeof entry.id !== 'string') {
+            throw new Error(`personas/manifest.json has an entry with a missing or invalid "id".`);
+        }
+        if (!entry.description || typeof entry.description !== 'string') {
+            throw new Error(`Persona "${entry.id}" is missing a "description" in manifest.json.`);
+        }
+        if (!Array.isArray(entry.tools) || entry.tools.length === 0) {
+            throw new Error(`Persona "${entry.id}" has an empty "tools" array in manifest.json. ` +
+                `Every persona must declare at least one narrowed tool.`);
+        }
+        seenIds.add(entry.id);
+        return {
+            id: entry.id,
+            description: entry.description,
+            tools: Object.freeze([...entry.tools]),
+            soul: readSoul(entry.id),
+        };
+    });
+    cachedPersonas = personas;
+    return personas;
+}
+/**
+ * Renders a persona's prompt for interpolation into a `subagent_spawn(role,
+ * objective)` call: the SOUL body, followed by its routing description as
+ * additional framing context.
+ *
+ * @throws {Error} naming the valid ids, if `id` does not match a loaded persona
+ */
+export function renderPersonaPrompt(id) {
+    const personas = loadPersonas();
+    const persona = personas.find((p) => p.id === id);
+    if (!persona) {
+        const validIds = personas.map((p) => p.id).join(', ');
+        throw new Error(`Unknown persona "${id}". Valid persona ids are: ${validIds}.`);
+    }
+    return `${persona.soul}\n\n## Role in this task\n\n${persona.description}`;
+}
+//# sourceMappingURL=personas.js.map

package/dist/personas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personas.js","sourceRoot":"","sources":["../src/personas.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The .omm/ state store.
+ *
+ * Every path that reaches the filesystem goes through `resolveWritablePath`, which
+ * refuses anything landing in a muse-protected directory or escaping the state
+ * root. Keeping that policy in one module means the MCP tool surface cannot
+ * accidentally grow a path that skips the check.
+ */
+export interface StateStoreOptions {
+    /** Workspace root the store is anchored to. */
+    workspaceRoot: string;
+}
+export declare class StateStore {
+    readonly workspaceRoot: string;
+    constructor({ workspaceRoot }: StateStoreOptions);
+    /** Absolute path of this store's state root. */
+    get root(): string;
+    /**
+     * Reads a state file. Returns null when absent, so callers can distinguish
+     * "nothing stored yet" from an error without a try/catch.
+     *
+     * @throws {ProtectedPathError | EscapedStateRootError} when the path is not readable-in-scope
+     */
+    read(relativePath: string): string | null;
+    /**
+     * Writes a state file, creating parent directories inside the state root.
+     *
+     * @throws {ProtectedPathError | EscapedStateRootError} when the path is out of scope
+     */
+    write(relativePath: string, contents: string): string;
+    /**
+     * Removes a state file or directory. Absent targets are a no-op so callers can
+     * clear unconditionally.
+     *
+     * @throws {ProtectedPathError | EscapedStateRootError} when the path is out of scope
+     */
+    clear(relativePath: string): boolean;
+}

package/dist/state.js

@@ -0,0 +1,59 @@
+/**
+ * The .omm/ state store.
+ *
+ * Every path that reaches the filesystem goes through `resolveWritablePath`, which
+ * refuses anything landing in a muse-protected directory or escaping the state
+ * root. Keeping that policy in one module means the MCP tool surface cannot
+ * accidentally grow a path that skips the check.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ensureStateRoot, resolveWritablePath, stateRoot } from './paths.js';
+export class StateStore {
+    workspaceRoot;
+    constructor({ workspaceRoot }) {
+        this.workspaceRoot = workspaceRoot;
+    }
+    /** Absolute path of this store's state root. */
+    get root() {
+        return stateRoot(this.workspaceRoot);
+    }
+    /**
+     * Reads a state file. Returns null when absent, so callers can distinguish
+     * "nothing stored yet" from an error without a try/catch.
+     *
+     * @throws {ProtectedPathError | EscapedStateRootError} when the path is not readable-in-scope
+     */
+    read(relativePath) {
+        const resolved = resolveWritablePath(this.workspaceRoot, relativePath);
+        if (!existsSync(resolved))
+            return null;
+        return readFileSync(resolved, 'utf8');
+    }
+    /**
+     * Writes a state file, creating parent directories inside the state root.
+     *
+     * @throws {ProtectedPathError | EscapedStateRootError} when the path is out of scope
+     */
+    write(relativePath, contents) {
+        const resolved = resolveWritablePath(this.workspaceRoot, relativePath);
+        ensureStateRoot(this.workspaceRoot);
+        mkdirSync(dirname(resolved), { recursive: true });
+        writeFileSync(resolved, contents, 'utf8');
+        return resolved;
+    }
+    /**
+     * Removes a state file or directory. Absent targets are a no-op so callers can
+     * clear unconditionally.
+     *
+     * @throws {ProtectedPathError | EscapedStateRootError} when the path is out of scope
+     */
+    clear(relativePath) {
+        const resolved = resolveWritablePath(this.workspaceRoot, relativePath);
+        if (!existsSync(resolved))
+            return false;
+        rmSync(resolved, { recursive: true, force: true });
+        return true;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO7E,MAAM,OAAO,UAAU;IACZ,aAAa,CAAS;IAE/B,YAAY,EAAE,aAAa,EAAqB;QAC9C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED,gDAAgD;IAChD,IAAI,IAAI;QACN,OAAO,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,YAAoB;QACvB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;QACvE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,OAAO,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAoB,EAAE,QAAgB;QAC1C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;QACvE,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACpC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAoB;QACxB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;QACvE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}