@cmodjs/core 0.1.14 → 0.2.1

package/runtime/metadata.js

@@ -0,0 +1,143 @@
+import { formatOf, MetadataError, readMetadata, sidecarSuffix, writeMetadata } from '../utils/metadata.js';
+import { messageOf } from '../utils/text.js';
+import { picomatch, resolve } from '../vendor.js';
+const skippedFolders = ['.git', 'node_modules'];
+const ownKey = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+export function resolvedPath(path, places) {
+    const configured = /^~\/\.claude(?=\/|$)/.exec(path);
+    if (configured !== null && places.configRoot !== undefined)
+        return resolve(`${places.configRoot}${path.slice(configured[0].length)}`);
+    if (path === '~' || path.startsWith('~/')) {
+        if (places.home === undefined)
+            throw new Error(`${path} starts with ~, and HOME is not set. Start Claude Code with HOME set.`);
+        return resolve(`${places.home}${path.slice(1)}`);
+    }
+    return path.startsWith('/') ? resolve(path) : resolve(places.projectRoot(), path);
+}
+export function createModFiles({ name, claude, places, checkWrite }) {
+    const prefix = `${name}.`;
+    const cache = new Map();
+    const logged = new Set();
+    const own = (all) => Object.freeze(Object.fromEntries(Object.entries(all).flatMap(([key, value]) => (key.startsWith(prefix) ? [[key.slice(prefix.length), value]] : []))));
+    const locate = async (path) => {
+        const stat = await claude.fs.stat(path, { resolve: true });
+        if (stat.kind !== 'file')
+            throw new Error(`${path} is not a file, so it holds no metadata.`);
+        const realPath = stat.realPath ?? path;
+        const extensionless = !realPath.slice(realPath.lastIndexOf('/') + 1).includes('.');
+        const firstLine = extensionless ? (await claude.fs.read(realPath)).split('\n', 1)[0] : undefined;
+        const format = formatOf(realPath, firstLine);
+        const holder = format.kind === 'sidecar' ? `${realPath}${sidecarSuffix}` : realPath;
+        const sidecar = format.kind === 'sidecar' ? await claude.fs.stat(holder).catch(() => undefined) : undefined;
+        return { realPath, format, holder, signature: `${stat.mtimeMs}:${stat.size}:${sidecar?.kind === 'file' ? `${sidecar.mtimeMs}:${sidecar.size}` : ''}` };
+    };
+    const textOf = async (holder) => ((await claude.fs.stat(holder).catch(() => undefined))?.kind === 'file' ? claude.fs.read(holder) : '');
+    const readEntry = async (path) => {
+        const located = await locate(path);
+        const cached = cache.get(path);
+        if (cached?.signature === located.signature)
+            return cached.read;
+        let read;
+        try {
+            const { metadata, name: declared } = readMetadata(await textOf(located.holder), located.format);
+            read = { metadata, ...(declared === undefined ? {} : { name: declared }) };
+        }
+        catch (error) {
+            if (!(error instanceof MetadataError))
+                throw error;
+            const failure = `${located.holder} ${error.message}`;
+            read = { metadata: {}, error: failure };
+            if (!logged.has(failure))
+                claude.ui.log(`${name}: ${failure}`);
+            logged.add(failure);
+        }
+        cache.set(path, { signature: located.signature, read });
+        return read;
+    };
+    const matchesOf = async (pattern) => {
+        const absolute = resolvedPath(pattern, places);
+        const scanned = picomatch.scan(absolute);
+        if (!scanned.isGlob)
+            return (await claude.fs.stat(absolute).catch(() => undefined))?.kind === 'file' ? [absolute] : [];
+        const isMatch = picomatch(absolute, { dot: true });
+        const entersSkipped = skippedFolders.filter((folder) => scanned.glob.split('/').includes(folder));
+        const maxDepth = scanned.glob.includes('**') ? Number.POSITIVE_INFINITY : scanned.glob.split('/').length;
+        const found = [];
+        const visited = new Set();
+        const walk = async (folder, depth) => {
+            const real = (await claude.fs.stat(folder, { resolve: true }).catch(() => undefined))?.realPath ?? folder;
+            if (visited.has(real))
+                return;
+            visited.add(real);
+            const entries = await claude.fs.list(folder).catch(() => []);
+            await Promise.all(entries.map(async (entry) => {
+                const path = `${folder}/${entry.name}`;
+                const kind = entry.isLink === true ? (await claude.fs.stat(path).catch(() => undefined))?.kind : entry.kind;
+                if (kind === 'file' && isMatch(path))
+                    found.push(path);
+                if (kind !== 'dir' || depth + 1 >= maxDepth)
+                    return;
+                if (skippedFolders.includes(entry.name) && !entersSkipped.includes(entry.name))
+                    return;
+                await walk(path, depth + 1);
+            }));
+        };
+        const base = scanned.base === '' ? '/' : scanned.base;
+        if ((await claude.fs.stat(base).catch(() => undefined))?.kind === 'dir')
+            await walk(base, 0);
+        return found;
+    };
+    return {
+        async find(glob) {
+            const patterns = typeof glob === 'string' ? [glob] : glob;
+            const paths = [...new Set((await Promise.all(patterns.map(matchesOf))).flat())].sort();
+            const kept = paths.filter((path) => !(path.endsWith(sidecarSuffix) && paths.includes(path.slice(0, -sidecarSuffix.length))));
+            return Promise.all(kept.map(async (path) => {
+                const read = await readEntry(path);
+                return { path, ...(read.name === undefined ? {} : { name: read.name }), metadata: own(read.metadata), ...(read.error === undefined ? {} : { error: read.error }) };
+            }));
+        },
+        async read(path) {
+            const read = await readEntry(resolvedPath(path, places));
+            if (read.error !== undefined)
+                throw new Error(`${name}: ${read.error}`);
+            return own(read.metadata);
+        },
+        async update(path, change) {
+            const given = resolvedPath(path, places);
+            await checkWrite(given);
+            const located = await locate(given);
+            const text = await textOf(located.holder);
+            let all;
+            try {
+                all = readMetadata(text, located.format).metadata;
+            }
+            catch (error) {
+                throw new Error(`${name}: ${located.holder} ${messageOf(error)}`, { cause: error });
+            }
+            const edited = { ...own(all) };
+            change(edited);
+            for (const [key, value] of Object.entries(edited)) {
+                if (!ownKey.test(key))
+                    throw new Error(`${name}: the metadata key "${key}" is not a name. Use letters, digits, "_", ".", and "-".`);
+                if (typeof value !== 'string')
+                    throw new Error(`${name}: the metadata key "${key}" holds ${JSON.stringify(value)}. Each value is text, and a list is one space-separated text.`);
+                if (value.includes('\n'))
+                    throw new Error(`${name}: the metadata key "${key}" holds a line break. Each value is one line of text.`);
+            }
+            const next = {};
+            for (const [key, value] of Object.entries(all)) {
+                if (!key.startsWith(prefix))
+                    next[key] = value;
+                else if (Object.hasOwn(edited, key.slice(prefix.length)))
+                    next[key] = edited[key.slice(prefix.length)];
+            }
+            for (const [key, value] of Object.entries(edited))
+                next[`${prefix}${key}`] = value;
+            if (JSON.stringify(next) === JSON.stringify(all))
+                return;
+            await claude.fs.write(located.holder, writeMetadata(text, located.format, next));
+            cache.delete(given);
+        },
+    };
+}

package/runtime/options.d.ts

@@ -0,0 +1,21 @@
+import type { PluginOptions } from 'claude-code';
+import { type Options } from '../options.js';
+import type { Claude } from './claude.js';
+export declare class MissingOptions extends Error {
+    readonly keys: readonly string[];
+    readonly titles: readonly string[];
+    constructor(keys: readonly string[], titles: readonly string[]);
+}
+export type ModOptions = {
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly missing: readonly string[];
+    load(root: string): Promise<void>;
+};
+export declare function createOptions({ name, declared, fromClaude, claude, changed }: {
+    readonly name: string;
+    readonly declared: Options;
+    readonly fromClaude: PluginOptions;
+    readonly claude: Claude;
+    readonly changed: () => void;
+}): ModOptions;
+//# sourceMappingURL=options.d.ts.map

package/runtime/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/runtime/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAoC,KAAK,OAAO,EAAE,MAAM,eAAe,CAAA;AAG9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAElC,YAAY,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAI7D;CACF;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC,CAAA;AAED,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,UAAU,CAmE3O"}

package/runtime/options.js

@@ -0,0 +1,100 @@
+import { fitsOption, isUnset } from '../options.js';
+import { configFolders } from '../records.js';
+import { listed, messageOf } from '../utils/text.js';
+export class MissingOptions extends Error {
+    keys;
+    titles;
+    constructor(keys, titles) {
+        super(`it needs ${listed(titles)}`);
+        this.keys = keys;
+        this.titles = titles;
+    }
+}
+export function createOptions({ name, declared, fromClaude, claude, changed }) {
+    let values = merged(declared, fromClaude, {}, new Set());
+    let locked;
+    let loadedRoot;
+    const readLocked = async () => {
+        if (Object.keys(declared).length === 0)
+            return new Set();
+        const rows = await claude.config.list().catch((error) => {
+            claude.ui.log(`${name} could not read /config, so a project's options.json may override a value your organization set: ${messageOf(error)}`, { to: 'debug' });
+            return [];
+        });
+        return new Set(rows.filter((row) => row.isLocked && row.key.startsWith(`${name}.`)).map((row) => row.key.slice(name.length + 1)));
+    };
+    const readProject = async (root) => {
+        const env = { HOME: await claude.env.home(), CLAUDE_CONFIG_DIR: await claude.env.configHome() };
+        const project = configFolders(env, name, root).find(({ tier }) => tier === 'project');
+        if (project === undefined)
+            return {};
+        const path = `${project.folder}/options.json`;
+        if (!(await claude.fs.exists(path)))
+            return {};
+        const ignore = (reason) => claude.ui.log(`${path} ${reason}`);
+        let file;
+        try {
+            file = JSON.parse(await claude.fs.read(path));
+        }
+        catch (error) {
+            ignore(`is not JSON (${messageOf(error)}). Fix the file; ${name} uses its other options until then.`);
+            return {};
+        }
+        if (typeof file !== 'object' || file === null || Array.isArray(file)) {
+            ignore('is not a JSON object. Write one, such as { "branch": "main" }.');
+            return {};
+        }
+        const kept = {};
+        for (const [key, value] of Object.entries(file)) {
+            const option = declared[key];
+            if (option === undefined)
+                ignore(`sets ${key}, which ${name} does not declare. ${Object.keys(declared).length === 0 ? 'Remove it.' : `Remove it, or use one of: ${Object.keys(declared).join(', ')}.`}`);
+            else if (option.kind === 'secret')
+                ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`);
+            else {
+                const misfit = fitsOption(option, value);
+                if (misfit === undefined)
+                    kept[key] = value;
+                else
+                    ignore(`sets ${key} to ${JSON.stringify(value)}, and ${option.title} ${misfit}.`);
+            }
+        }
+        return kept;
+    };
+    return {
+        get values() {
+            return values;
+        },
+        get missing() {
+            return Object.entries(declared)
+                .filter(([key, option]) => option.default === undefined && isUnset(values[key]))
+                .map(([key]) => key);
+        },
+        async load(root) {
+            if (Object.keys(declared).length === 0)
+                return;
+            locked ??= await readLocked();
+            const project = await readProject(root);
+            const isFirst = loadedRoot === undefined;
+            loadedRoot = root;
+            const next = merged(declared, fromClaude, project, locked);
+            if (!isFirst && JSON.stringify(next) === JSON.stringify(values))
+                return;
+            values = next;
+            if (!isFirst)
+                changed();
+        },
+    };
+}
+function merged(declared, fromClaude, project, locked) {
+    return Object.freeze(Object.fromEntries(Object.entries(declared).map(([key, option]) => [key, valueOf(key, option, fromClaude[key], project, locked)])));
+}
+function valueOf(key, option, own, project, locked) {
+    if (locked.has(key))
+        return own;
+    if (Object.hasOwn(project, key))
+        return project[key];
+    if (!isUnset(own) && fitsOption(option, own) === undefined)
+        return Array.isArray(own) ? Object.freeze([...own]) : own;
+    return option.default ?? (option.kind === 'list' ? Object.freeze([]) : option.kind === 'number' ? undefined : '');
+}

package/runtime/state.d.ts

@@ -11,6 +11,7 @@ export type StateOptions = {
 export type ModState<State extends object> = {
     readonly state: State;
     readonly root: string;
+    changed(): void;
     load(): Promise<void>;
     moveTo(root: string): Promise<void>;
     switchSession(session: string, source: ClassicHookInputs['SessionStart']['source']): Promise<void>;

package/runtime/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/runtime/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAQzC,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,IAAI;IAC3C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnG,CAAA;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAIvE;AAED,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAyI1I"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/runtime/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAQzC,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,QAAQ,CAAC,KAAK,SAAS,MAAM,IAAI;IAC3C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,IAAI,IAAI,CAAA;IACf,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnG,CAAA;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAIvE;AAED,wBAAgB,WAAW,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,CAoF1I"}

package/runtime/state.js

@@ -1,7 +1,5 @@
-import { configFolder, configFolders } from '../records.js';
 import { messageOf } from '../utils/text.js';
 const lifetimes = ['memory', 'session', 'project', 'global'];
-const savedLifetimes = ['session', 'project', 'global'];
 const keptPerValue = 20;
 const listeners = new WeakMap();
 export function onStateChange(state, listener) {
@@ -17,7 +15,6 @@ export function createState({ name, initial, session, root, claude, changed: red
     };
     const declared = declaredGroups(name, initial);
     const current = copied(declared);
-    let defaults = declared;
     let projectRoot = root;
     let sessionId = session;
     let turn = Promise.resolve();
@@ -38,62 +35,6 @@ export function createState({ name, initial, session, root, claude, changed: red
         for (const oldest of owners.slice(0, -keptPerValue))
             await claude.store.delete(oldest);
     };
-    const fileValues = (path, tier, text, systemPath) => {
-        const values = [];
-        const ignore = (reason) => claude.ui.log(`${path} ${reason}`);
-        let file;
-        try {
-            file = JSON.parse(text);
-        }
-        catch (error) {
-            ignore(`is not JSON (${messageOf(error)}). Fix the file, then run /reload-plugins.`);
-            return values;
-        }
-        if (!isPlainObject(file)) {
-            ignore('is not a JSON object. Write one, such as { "global": { "key": "value" } }.');
-            return values;
-        }
-        for (const [group, entries] of Object.entries(file)) {
-            if (!isLifetime(group)) {
-                ignore(`sets ${group}, which ${name} does not declare. Remove it, or use one of: ${savedLifetimes.join(', ')}.`);
-                continue;
-            }
-            if (group === 'memory') {
-                ignore('sets memory, and memory values are never saved, so a file cannot set them. Remove it.');
-                continue;
-            }
-            if (!isPlainObject(entries)) {
-                ignore(`sets ${group} to ${typeOf(entries)}. Write an object of values, such as { "${group}": { "key": "value" } }.`);
-                continue;
-            }
-            for (const [key, value] of Object.entries(entries)) {
-                const choices = Object.keys(declared[group]);
-                const wanted = typeOf(declared[group][key]);
-                if (!Object.hasOwn(declared[group], key))
-                    ignore(`sets ${group}.${key}, which ${name} does not declare. ${choices.length === 0 ? 'Remove it.' : `Remove it, or use one of: ${choices.join(', ')}.`}`);
-                else if (tier === 'project' && group === 'global')
-                    ignore(`sets ${group}.${key}, and one repository cannot change a value for every project. Move it to ${systemPath}.`);
-                else if (typeOf(value) !== wanted)
-                    ignore(`sets ${group}.${key} to ${typeOf(value)}, and ${name} keeps ${wanted} there. Write ${wanted}, or remove it.`);
-                else
-                    values.push([group, key, frozen(name, `${group}.${key}`, value)]);
-            }
-        }
-        return values;
-    };
-    const readDefaults = async (nextRoot) => {
-        const env = { HOME: await claude.env.home(), CLAUDE_CONFIG_DIR: await claude.env.configHome() };
-        const systemPath = `${configFolder(env, name)}/state.json`;
-        const next = copied(declared);
-        for (const { tier, folder } of configFolders(env, name, nextRoot)) {
-            const path = `${folder}/state.json`;
-            if (!(await claude.fs.exists(path)))
-                continue;
-            for (const [lifetime, key, value] of fileValues(path, tier, await claude.fs.read(path), systemPath))
-                next[lifetime][key] = value;
-        }
-        return next;
-    };
     const loadGroups = async (only, next) => {
         const loaded = [];
         for (const lifetime of only) {
@@ -102,9 +43,8 @@ export function createState({ name, initial, session, root, claude, changed: red
         }
         projectRoot = next.root;
         sessionId = next.session;
-        defaults = next.defaults;
         for (const [lifetime, key, saved] of loaded)
-            current[lifetime][key] = saved === undefined ? defaults[lifetime][key] : frozen(name, `${lifetime}.${key}`, saved);
+            current[lifetime][key] = saved === undefined ? declared[lifetime][key] : frozen(name, `${lifetime}.${key}`, saved);
         changed();
     };
     const copySession = async (nextSession) => {
@@ -139,14 +79,15 @@ export function createState({ name, initial, session, root, claude, changed: red
         get root() {
             return projectRoot;
         },
-        load: () => inTurn(async () => loadGroups(lifetimes, { root: projectRoot, session: sessionId, defaults: await readDefaults(projectRoot) })),
-        moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId, defaults: await readDefaults(nextRoot) }))),
+        changed,
+        load: () => inTurn(() => loadGroups(lifetimes, { root: projectRoot, session: sessionId })),
+        moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId }))),
         switchSession: (nextSession, source) => inTurn(async () => {
             if (nextSession === sessionId)
                 return;
             if (source === 'fork')
                 await copySession(nextSession);
-            return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession, defaults });
+            return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession });
         }),
     };
 }
@@ -168,17 +109,6 @@ function copied(groups) {
 function isLifetime(group) {
     return lifetimes.includes(group);
 }
-function typeOf(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'an array';
-    if (typeof value === 'object')
-        return 'an object';
-    if (value === undefined)
-        return 'nothing';
-    return `a ${typeof value}`;
-}
 function frozen(name, path, value) {
     const isArray = Array.isArray(value);
     if (!isArray && !isPlainObject(value))

package/src/installer.ts

@@ -0,0 +1,17 @@
+import type { Frozen, RenderElement, RenderPropsOf } from 'claude-code'
+import type { Mod } from './mod.js'
+
+export type Step<State extends object = Record<never, never>> = {
+  readonly id: string
+  readonly title: string
+  render(mod: Mod<State>, props: Frozen<RenderPropsOf['Pane']>): RenderElement
+  isDone(mod: Mod<State>): boolean | Promise<boolean>
+}
+
+const stepId = /^[A-Za-z0-9_-]{1,64}$/
+
+export function defineStep<State extends object = Record<never, never>>(step: Step<State>): Step<State> {
+  if (!stepId.test(step.id)) throw new Error(`defineStep: "${step.id}" is not a step id. Use 1 to 64 letters, digits, "_", or "-".`)
+  if (step.title.trim() === '') throw new Error(`defineStep: the step "${step.id}" needs a title, the line the installer shows above it.`)
+  return step
+}

package/src/jobs/context.ts

@@ -14,7 +14,7 @@ type Session = Omit<Workspace, 'projectRoot' | 'cwd'>
 
 type Stream = HookStream<ProcessSpawnChunk, ProcessSpawnResult>
 
-export function workspaceReader({ claude }: JobContext): () => Promise<Workspace> {
+export function workspaceReader({ mod: { claude } }: JobContext): () => Promise<Workspace> {
   let session: Promise<Session> | undefined
   return async () => {
     session ??= readSession(claude)
@@ -40,7 +40,7 @@ export function afterCall<State extends object>(
   failed: (error: unknown) => readonly string[],
 ): void {
   const readWorkspace = workspaceReader(job)
-  job.on('tool.call', async (e, next) => {
+  job.mod.claude.on('tool.call', async (e, next) => {
     const before = Promise.all([useOf(job, e), readWorkspace()])
     await before.catch(() => undefined)
     const result = await next(e)
@@ -58,7 +58,8 @@ export function modOf<State extends object>(job: JobContext<State>, { call, fold
   return modWithin(job, deadline, async () => workspace.scope?.workTreeOf(call !== undefined && 'path' in call ? call.path : folder))
 }
 
-export function modWithin<State extends object>({ mod, claude }: JobContext<State>, deadline: Deadline, workTree: () => Promise<string | undefined> = async () => undefined): Mod<State> {
+export function modWithin<State extends object>({ mod }: JobContext<State>, deadline: Deadline, workTree: () => Promise<string | undefined> = async () => undefined): Mod<State> {
+  const { claude } = mod
   const within = <Value>(call: string, task: Promise<Value>) => beforeDeadline(claude, deadline, call, task)
   const folderOf = async (cwd: string | undefined) => {
     const folder = cwd ?? (await workTree())
@@ -79,6 +80,7 @@ export function modWithin<State extends object>({ mod, claude }: JobContext<Stat
       list: (path) => within('mod.fs.list', mod.fs.list(path)),
       exists: (path) => within('mod.fs.exists', mod.fs.exists(path)),
       stat: (path, options) => within('mod.fs.stat', mod.fs.stat(path, options)),
+      find: (glob) => within('mod.fs.find', mod.fs.find(glob)),
     },
     http: { fetch: (url, init) => within('mod.http.fetch', mod.http.fetch(url, init)) },
     dependencies: dependencyCalls(claude, within),

package/src/jobs/permissions.ts

@@ -37,7 +37,7 @@ export function permissions<State extends object = Record<never, never>>(rules:
       }
     }
 
-    job.on('tool.check', async (e, next) => {
+    job.mod.claude.on('tool.check', async (e, next) => {
       const [below, ours] = await Promise.all([next(e), verdictOf(e)])
       return ours === undefined ? below : stricterVerdict<Verdict>(below, ours)
     })

package/src/jobs/program.ts

@@ -1,4 +1,5 @@
 import type { Job } from '../mod.js'
+import { PermissionRefused } from '../runtime/grants.js'
 import { messageOf } from '../utils/text.js'
 
 export type Program = {
@@ -12,7 +13,8 @@ const backoffSeconds = [1, 2, 4, 8, 16] as const
 
 export function program(options: { readonly command: readonly string[]; readonly environment?: Record<string, string> }): Job<Program> {
   const { command, environment } = options
-  return ({ mod, claude, announce }) => {
+  return ({ mod, announce }) => {
+    const { claude } = mod
     const [executable] = command
     if (executable === undefined) throw new Error(`${mod.name}: the program has no command. Name the program on PATH and its arguments, such as ['preview-server', '--port', '0'].`)
     let state: Program['state'] = 'stopped'
@@ -53,6 +55,7 @@ export function program(options: { readonly command: readonly string[]; readonly
           for (const waiter of waiting.splice(0)) waiter.resolve(address)
         }
       } catch (error) {
+        if (error instanceof PermissionRefused) return stop(`${messageOf(error)} Add it, then run /reload-plugins.`)
         lastError = messageOf(error)
       }
       address = undefined

package/src/jobs/prompt.ts

@@ -26,7 +26,7 @@ export function prompt<State extends object = Record<never, never>>({ name, prom
   return (job) => {
     job.reserveName('prompt', name, `prompt: ${job.mod.name} adds the name "${name}" two times. Give each prompt its own name.`)
 
-    const log = (reason: string) => job.claude.ui.log(`prompt "${name}" added nothing: ${reason}`, { to: 'debug' })
+    const log = (reason: string) => job.mod.claude.ui.log(`prompt "${name}" added nothing: ${reason}`, { to: 'debug' })
     const textFor = async (input: PromptInput, mod: Mod<State>) => {
       try {
         const value = typeof text === 'string' ? text : await text(input, mod)
@@ -61,12 +61,12 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
   let isQueued = false
   let updates = Promise.resolve()
 
-  job.on('classic.SessionStart', (e, next) => {
+  job.mod.claude.on('classic.SessionStart', (e, next) => {
     hasStarted = e.source === 'resume' || e.source === 'compact'
     if (!hasStarted) given = undefined
     return next(e)
   })
-  job.on('prompt.context', async (e, next) => {
+  job.mod.claude.on('prompt.context', async (e, next) => {
     const below = await next(e)
     hasStarted = true
     if (below.blocks.some((block) => block.name === name)) {
@@ -83,7 +83,7 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
     const value = await textFor()
     if (value === undefined || value === given) return
     given = value
-    await job.claude.session.append({ message: { type: 'user', content: [{ type: 'text', text: `# ${name}\n${value}` }] } }).then((added) => {
+    await job.mod.claude.session.append({ message: { type: 'user', content: [{ type: 'text', text: `# ${name}\n${value}` }] } }).then((added) => {
       if (added.deny !== undefined) log(`Claude Code refused the new text: ${added.deny}`)
     })
   }
@@ -95,7 +95,7 @@ function addKeptCurrent<State extends object>(job: JobContext<State>, name: stri
 }
 
 function addAfterUserPrompts(job: JobContext, when: RegExp | ((userPrompt: string) => boolean), textFor: (userPrompt: string) => Promise<string | undefined>, log: (reason: string) => void): void {
-  job.on('prompt.submit', async (e, next) => {
+  job.mod.claude.on('prompt.submit', async (e, next) => {
     let value: string | undefined
     try {
       if (typeof when === 'function' ? when(e.text) : e.text.search(when) >= 0) value = await textFor(e.text)

package/src/jobs/schedule.ts

@@ -10,7 +10,8 @@ export function schedule<State extends object = Record<never, never>>(entry: Sch
   if (typeof entry !== 'function') checked(entry)
 
   return (job) => {
-    const { mod, claude } = job
+    const { mod } = job
+    const { claude } = mod
     const order = scheduleCounts.get(mod) ?? 0
     scheduleCounts.set(mod, order + 1)
     const storeKey = `cmod:schedule:${order}`

package/src/jobs/slash-command.ts

@@ -20,7 +20,8 @@ export function slashCommand<State extends object = Record<never, never>>(option
 }): Job<void, State> {
   const { name, description, argumentHint, immediate, reply } = options
   return (job) => {
-    const { mod, claude, announce, reserveName } = job
+    const { mod, announce, reserveName } = job
+    const { claude } = mod
     if (!commandName.test(name)) throw new Error(`${mod.name}: "${name}" is not a slash command name. Use 1 to 64 letters, digits, "_", or "-", without the slash.`)
     reserveName('slashCommand', name, `${mod.name}: the slash command /${name} is already added. Give each slashCommand its own name.`)
 
@@ -36,7 +37,7 @@ export function slashCommand<State extends object = Record<never, never>>(option
     announce(`/${name}`)
 
     const replyMod = modWithin(job, deadline)
-    job.on('command.run', async (e, next) => {
+    claude.on('command.run', async (e, next) => {
       if (e.command !== registered) return next(e)
       try {
         return answerOf(await reply({ args: e.args, positionals: splitWords(e.args) }, replyMod))

package/src/jobs/status-line.ts

@@ -17,7 +17,8 @@ export function statusLine<State extends object = Record<never, never>>(options:
 }): Job<void, State> {
   const { text, interval = 10000 } = options
   return (job) => {
-    const { mod, claude, announce, reserveName } = job
+    const { mod, announce, reserveName } = job
+    const { claude } = mod
     if (!(interval >= 1)) throw new Error(`${mod.name}: the status line interval is ${interval}. Give it in milliseconds, 1 or more.`)
     reserveName('statusLine', '', `${mod.name}: a status line is already added. A mod has one status line: join the texts in one statusLine.`)
 
@@ -48,7 +49,7 @@ export function statusLine<State extends object = Record<never, never>>(options:
     }
 
     announce('a status line')
-    job.on('session.measure', (e, next) => {
+    claude.on('session.measure', (e, next) => {
       refresh()
       return next(e)
     })

package/src/jobs/tool.ts

@@ -16,7 +16,8 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
 }): Job<{ readonly name: string }, State> {
   const { name, description, inputSchema, execute } = options
   return (job) => {
-    const { mod, claude, announce, reserveName } = job
+    const { mod, announce, reserveName } = job
+    const { claude } = mod
     if (!toolName.test(name)) throw new Error(`${mod.name}: "${name}" is not a tool name. Use 1 to 64 letters, digits, "_", or "-".`)
     const properties = (inputSchema as { properties?: object } | undefined)?.properties ?? {}
     const reserved = reservedKeys.filter((key) => Object.hasOwn(properties, key))
@@ -36,7 +37,7 @@ export function tool<const Schema extends object = { type: 'object' }, State ext
     announce(`the ${name} tool`)
 
     const executeMod = modWithin(job, toolDeadline)
-    job.on('tool.call', async (e, next) => {
+    claude.on('tool.call', async (e, next) => {
       if (e.tool !== registered) return next(e)
       const input = toolInputOf(e)
       const { valid, errors } = validator.validate(input)