@cmodjs/core 0.1.14 → 0.2.1

package/runtime/installer.js

@@ -0,0 +1,118 @@
+import { permissionWords } from '../records.js';
+import { Box, Button, drawWith, Input, Text } from '../ui/elements.js';
+import { messageOf } from '../utils/text.js';
+export const installerPaneId = 'cmod-installer';
+export function createInstaller(name, claude) {
+    let page;
+    let isOpen = false;
+    const show = async (build, cancelled) => {
+        page?.cancel();
+        const answer = new Promise((resolve) => {
+            const done = (value) => {
+                if (page === shown)
+                    page = undefined;
+                resolve(value);
+            };
+            const shown = { ...build(done), cancel: () => done(cancelled) };
+            page = shown;
+        });
+        if (!isOpen) {
+            isOpen = true;
+            await claude().ui.open({ id: installerPaneId, title: `Install ${name}`, focus: true, holdToasts: true, closeOnEscape: true });
+        }
+        claude().ui.invalidate('ui.render');
+        return answer;
+    };
+    const frame = (title, body, actions) => Box({ flexDirection: 'column', gap: 1, paddingX: 1, children: [Text({ bold: true, children: title }), ...body, Box({ gap: 3, children: actions })] });
+    const bullet = (text) => Text({ children: [Text({ color: 'claude', children: '◆ ' }), text] });
+    return {
+        draws: (e) => e.component === 'Pane' && e.requestId === installerPaneId,
+        draw(e) {
+            return drawWith(claude().ui.resolve(e), () => page?.draw(e.props) ?? Text({ dimColor: true, children: `${name} is installing.` }));
+        },
+        closed(id) {
+            if (id !== installerPaneId)
+                return;
+            isOpen = false;
+            page?.cancel();
+        },
+        consent({ install, uninstall, keys, permissions, updates }) {
+            const changes = [
+                ...(install === '' ? [] : [`Run ${install} now${uninstall === '' ? '' : `, and ${uninstall} when you remove it`}`]),
+                ...(install === '' && uninstall !== '' ? [`Run ${uninstall} when you remove it`] : []),
+                ...(keys === '' ? [] : [`Bind ${keys}`]),
+                ...(updates === undefined ? [] : [`Update ${name} automatically from the ${updates} marketplace`]),
+            ];
+            return show((answer) => ({
+                draw: () => frame(`${name} wants to:`, [
+                    ...(permissions.length === 0 ? [] : [Box({ flexDirection: 'column', children: permissions.map((item) => bullet(permissionWords(item))) })]),
+                    ...(changes.length === 0 ? [] : [Text({ children: permissions.length === 0 ? 'Change your computer:' : 'and change your computer:' }), Box({ flexDirection: 'column', children: changes.map(bullet) })]),
+                    Text({ dimColor: true, children: 'You can turn each permission off later in /mods.' }),
+                ], [Button({ key: 'not-now', hotkey: 'n', label: 'Not now', onPress: () => answer(false) }), Button({ key: 'accept', hotkey: 'a', label: 'Accept', onPress: () => answer(true) })]),
+            }), false);
+        },
+        options(missing, save) {
+            const saved = new Map();
+            const failures = new Map();
+            return show((answer) => ({
+                draw: () => frame(`${name} needs ${missing.length === 1 ? 'one setting' : `${missing.length} settings`}:`, missing.map(([key, option]) => {
+                    const label = Text({ children: [Text({ bold: true, children: option.title }), option.description === '' ? '' : Text({ dimColor: true, children: `  ${option.description}` })] });
+                    if (option.kind === 'secret')
+                        return Box({ flexDirection: 'column', children: [label, Text({ dimColor: true, children: `Set it in /config, where Claude Code keeps it in your keychain, then press Next.` })] });
+                    const failure = failures.get(key);
+                    const field = Input({
+                        key: `option:${key}`,
+                        label: '› ',
+                        placeholder: option.kind === 'choice' ? (option.choices ?? []).join(', ') : option.kind === 'toggle' ? 'true or false' : option.kind === 'list' ? 'comma-separated' : '',
+                        value: saved.get(key) ?? '',
+                        submitLabel: 'save',
+                        onSubmit: (value) => void save(key, value)
+                            .then((refused) => {
+                            if (refused === undefined) {
+                                saved.set(key, value);
+                                failures.delete(key);
+                            }
+                            else
+                                failures.set(key, refused);
+                        })
+                            .catch((error) => failures.set(key, messageOf(error)))
+                            .finally(() => claude().ui.invalidate('ui.render')),
+                    });
+                    const status = failure !== undefined ? Text({ color: 'error', children: failure }) : saved.has(key) ? Text({ color: 'success', children: '✔ saved' }) : Text({ children: '' });
+                    return Box({ flexDirection: 'column', children: [label, field, status] });
+                }), [Button({ key: 'not-now', hotkey: 'n', label: 'Not now', onPress: () => answer(false) }), Button({ key: 'next', hotkey: 'x', label: 'Next', onPress: () => answer(true) })]),
+            }), false);
+        },
+        step(mod, step, index, total) {
+            let notice;
+            return show((answer) => ({
+                draw: (props) => {
+                    let body;
+                    try {
+                        body = step.render(mod, props);
+                    }
+                    catch (error) {
+                        body = Text({ color: 'error', children: `The ${step.title} step could not draw: ${messageOf(error)}` });
+                    }
+                    const next = async () => {
+                        const isDone = await Promise.resolve(step.isDone(mod)).catch(() => false);
+                        if (isDone)
+                            answer(true);
+                        else {
+                            notice = `Finish ${step.title} first.`;
+                            claude().ui.invalidate('ui.render');
+                        }
+                    };
+                    return frame(`${step.title}  (${index} of ${total})`, [body, ...(notice === undefined ? [] : [Text({ color: 'warning', children: notice })])], [Button({ key: 'not-now', hotkey: 'n', label: 'Not now', onPress: () => answer(false) }), Button({ key: 'next', hotkey: 'x', label: index === total ? 'Finish' : 'Next', onPress: () => void next() })]);
+                },
+            }), false);
+        },
+        async close() {
+            page = undefined;
+            if (!isOpen)
+                return;
+            isOpen = false;
+            await claude().ui.close({ id: installerPaneId });
+        },
+    };
+}

package/runtime/lifecycle.d.ts

@@ -1,5 +1,7 @@
-import type { Args, EventResult, Frozen } from 'claude-code';
+import type { Args, EventResult, Frozen, PluginOptions } from 'claude-code';
 import type { Mod, ModDefinition } from '../mod.js';
+import type { Options } from '../options.js';
+import { type Steps } from '../records.js';
 import type { Claude } from './claude.js';
 import { type RoutedEvent } from './hooks.js';
 import { type RouterNext } from './router.js';
@@ -10,7 +12,8 @@ export type Plugin = {
     readonly store: string;
     readonly isInstalled: boolean;
     readonly shouldRecord: boolean;
-    readonly keys: Readonly<Record<string, string>>;
+    readonly steps: Steps;
+    readonly granted: readonly string[];
 };
 export type Phase = 'starting' | 'installing' | 'waiting' | 'declined' | 'failed' | 'ready' | 'active';
 export type Lifecycle<State extends object> = {
@@ -21,5 +24,5 @@ export type Lifecycle<State extends object> = {
     route<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>;
 };
 export declare function readPlugin(claude: Claude): Promise<Plugin>;
-export declare function createLifecycle<State extends object>(definition: ModDefinition<State>, checksPermissions?: () => boolean): Lifecycle<State>;
+export declare function createLifecycle<State extends object, Declared extends Options = Options>(definition: ModDefinition<State, string, Declared>, checksPermissions?: () => boolean, options?: PluginOptions, asksPerson?: boolean): Lifecycle<State>;
 //# sourceMappingURL=lifecycle.d.ts.map

package/runtime/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/runtime/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAiE,MAAM,aAAa,CAAA;AAC3H,OAAO,KAAK,EAAa,GAAG,EAAE,aAAa,EAAqB,MAAM,WAAW,CAAA;AAIjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGzC,OAAO,EAAsG,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AACjJ,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAKxE,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD,CAAA;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtG,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,IAAI;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/E,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;CACzG,CAAA;AAkCD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBhE;AAkCD,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAE,MAAM,OAAoB,GAAG,SAAS,CAAC,KAAK,CAAC,CAiPvJ"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/runtime/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAA0B,aAAa,EAAyC,MAAM,aAAa,CAAA;AAC1I,OAAO,KAAK,EAAa,GAAG,EAAE,aAAa,EAAiC,MAAM,WAAW,CAAA;AAC7F,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAgS,KAAK,KAAK,EAAE,MAAM,eAAe,CAAA;AAGxU,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGzC,OAAO,EAAsG,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAMjJ,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAKxE,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtG,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,IAAI;IAC5C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/E,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;CACzG,CAAA;AAqCD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BhE;AAkCD,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,OAAO,GAAG,OAAO,EACtF,UAAU,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAClD,iBAAiB,GAAE,MAAM,OAAoB,EAC7C,OAAO,GAAE,aAAkB,EAC3B,UAAU,UAAO,GAChB,SAAS,CAAC,KAAK,CAAC,CA0VlB"}

package/runtime/lifecycle.js

@@ -1,9 +1,14 @@
-import { dataFolder, isAtLeast, oldestCmodFor, parseEvent, readRecord, readSteps, scriptsSha256, storeFolder } from '../records.js';
+import { consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn } from '../records.js';
 import { relativePath } from '../utils/paths.js';
 import { formatExit, listed, messageOf } from '../utils/text.js';
 import { beforeDeadline } from './deadline.js';
 import { answerCall, dependencyCalls, notInstalled } from './dependencies.js';
 import { classicHook, heldDecisionHook, permissionEvents, preToolUseHook, userSkillHook } from './hooks.js';
+import { checkedAnswer, checkingGrants, checksAnswers, checkWrite, isCovered, itemOf, passedDown } from './grants.js';
+import { createModFiles } from './metadata.js';
+import { fitsOption } from '../options.js';
+import { createInstaller } from './installer.js';
+import { createOptions, MissingOptions } from './options.js';
 import { createRouter } from './router.js';
 import { createState } from './state.js';
 import { toolCalls } from './tool-calls.js';
@@ -30,12 +35,14 @@ export async function readPlugin(claude) {
     const manifest = (await readJson(read, `${root}/.claude-plugin/plugin.json`));
     const version = typeof manifest?.version === 'string' ? manifest.version : undefined;
     const store = storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() });
+    const steps = readSteps(await readJson(read, `${root}/package.json`)) ?? {};
+    const declared = steps.permissions ?? [];
     if (name === cmodPluginName) {
         const installed = await cmodVersion(claude);
-        return { name, root, version, store, keys: {}, isInstalled: version !== undefined && installed !== undefined && isAtLeast(installed, version), shouldRecord: false };
+        return { name, root, version, store, steps, granted: declared, isInstalled: version !== undefined && installed !== undefined && isAtLeast(installed, version), shouldRecord: false };
     }
-    const steps = readSteps(await readJson(read, `${root}/package.json`)) ?? {};
-    const plugin = { name, root, version, store, keys: steps.keys ?? {} };
+    const approved = parseConsent(await readJson(read, consentPath(store)), consentPath(store))[name] ?? [];
+    const plugin = { name, root, version, store, steps, granted: declared.filter((item) => approved.includes(item)) };
     const record = await readRecord(read, store, name);
     if (Object.keys(steps).length === 0)
         return { ...plugin, isInstalled: true, shouldRecord: record?.version !== version };
@@ -79,15 +86,18 @@ async function cmodVersion(claude) {
         throw new Error(`cmod --version ${formatExit(result.exitCode, lastLineOf(result.stderr) ?? '')}`);
     return result.stdout.trim().split(/\s+/).at(-1);
 }
-export function createLifecycle(definition, checksPermissions = () => true) {
+export function createLifecycle(definition, checksPermissions = () => true, options = {}, asksPerson = true) {
     let router = createRouter();
     let phase = 'starting';
     let runtime;
     let plugin;
+    const granted = new Set();
     let line;
     let activation;
     let mod;
     let failure;
+    let pluginOptions = options;
+    const installer = createInstaller(definition.name, () => claude());
     let shouldRecord = false;
     let recording;
     let missedSessionStart;
@@ -95,7 +105,7 @@ export function createLifecycle(definition, checksPermissions = () => true) {
     const startSettled = new Promise((resolve) => (settleStart = resolve));
     const claude = () => {
         if (runtime === undefined)
-            throw new Error(`${definition.name}: the lifecycle has not started. registerMod(addHook, mod) starts it at session.start.`);
+            throw new Error(`${definition.name}: the lifecycle has not started. registerMod(addHook, mod, options) starts it at session.start.`);
         return runtime.claude;
     };
     const showLine = () => {
@@ -132,20 +142,71 @@ export function createLifecycle(definition, checksPermissions = () => true) {
             recording = undefined;
         });
     };
+    const saveOption = async (key, text) => {
+        const option = definition.options?.[key];
+        if (option === undefined || plugin === undefined)
+            return `${definition.name} has no option ${key}.`;
+        const value = option.kind === 'number' ? Number(text) : option.kind === 'toggle' ? text.trim() === 'true' : option.kind === 'list' ? text.split(',').map((item) => item.trim()).filter((item) => item !== '') : text;
+        const misfit = option.kind === 'toggle' && !['true', 'false'].includes(text.trim()) ? 'takes true or false' : fitsOption(option, value);
+        if (misfit !== undefined)
+            return `${option.title} ${misfit}.`;
+        const saved = await claude().config.set({ key: `${plugin.name}.${key}`, value });
+        return saved.deny;
+    };
+    const askOptions = async (missing) => {
+        if (!asksPerson || plugin === undefined || (await claude().session.surfaces()).length === 0)
+            return false;
+        const declared = definition.options ?? {};
+        const asked = missing.keys.flatMap((key) => {
+            const option = declared[key];
+            return option === undefined ? [] : [[key, option]];
+        });
+        if (!(await installer.options(asked, saveOption)))
+            return false;
+        const prefix = `${plugin.name}.`;
+        const rows = await claude().config.list();
+        pluginOptions = { ...pluginOptions, ...Object.fromEntries(rows.filter((row) => row.key.startsWith(prefix)).map((row) => [row.key.slice(prefix.length), row.value])) };
+        return true;
+    };
+    const pendingSteps = async (active) => {
+        const pending = [];
+        for (const step of definition.installer ?? [])
+            if (!(await Promise.resolve(step.isDone(active)).catch(() => false)))
+                pending.push(step.title);
+        return pending;
+    };
+    const runSteps = async (active) => {
+        const steps = asksPerson ? (definition.installer ?? []) : [];
+        for (const [index, step] of steps.entries()) {
+            if (await Promise.resolve(step.isDone(active)).catch(() => false))
+                continue;
+            const isAnswered = (await claude().session.surfaces()).length > 0 && (await installer.step(active, step, index + 1, steps.length));
+            if (!isAnswered) {
+                claude().ui.log(`${definition.name} needs ${steps.length - index === 1 ? 'one more step' : `${steps.length - index} more steps`}, starting with ${step.title}. Run /mods ${definition.name} to finish.`);
+                break;
+            }
+        }
+        await installer.close();
+    };
     const activate = async () => {
         if (runtime === undefined || plugin === undefined)
             return;
         const activeRouter = createRouter();
-        const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), keys: plugin.keys, checksPermissions }).catch((error) => {
-            fail(messageOf(error), 'Fix it, then run /reload-plugins.');
+        const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), steps: plugin.steps, granted, refreshGrants, checksPermissions, options: pluginOptions }).catch(async (error) => {
+            if (error instanceof MissingOptions && (await askOptions(error)))
+                return undefined;
+            fail(messageOf(error), error instanceof MissingOptions ? `Set ${error.keys.length === 1 ? 'it' : 'them'} in /config.` : 'Fix it, then run /reload-plugins.');
             throw error;
         });
+        if (active === undefined)
+            return activate();
         const { added } = active;
         mod = active.mod;
         router = activeRouter;
         phase = 'active';
         runtime.claude.ui.invalidate('ui.render');
         endLine();
+        void runSteps(active.mod).catch((error) => claude().ui.log(`${definition.name}: its installer stopped: ${messageOf(error)}`));
         const missed = missedSessionStart;
         missedSessionStart = undefined;
         const lateAnswer = missed === undefined ? {} : await activeRouter.dispatch('classic.SessionStart', missed, async () => ({})).catch((error) => {
@@ -163,6 +224,12 @@ export function createLifecycle(definition, checksPermissions = () => true) {
         if (added.length > 0)
             runtime.claude.ui.log(`${definition.name} added ${listed(added)}.`);
     };
+    const updatesToShow = async () => {
+        const [home, configHome] = await Promise.all([claude().env.home(), claude().env.configHome()]);
+        const configRoot = configHome ?? `${home ?? ''}/.claude`;
+        const known = await claude().fs.read(`${configRoot}/plugins/known_marketplaces.json`).then((text) => JSON.parse(text), () => undefined);
+        return updatesToTurnOn(marketplaceOf(claude().plugin.root, claude().plugin.name), await claude().settings.read({ source: 'user' }), known);
+    };
     const askConsent = async (event) => {
         const name = definition.name;
         if ((await claude().session.surfaces()).length === 0) {
@@ -171,14 +238,9 @@ export function createLifecycle(definition, checksPermissions = () => true) {
             return;
         }
         showLine().wait('Waiting for your answer');
-        const actions = [
-            ...(event.install === '' ? [] : [`runs ${event.install} to install`]),
-            ...(event.uninstall === '' ? [] : [`runs ${event.uninstall} when you remove it`]),
-            ...(event.keys === '' ? [] : [`binds ${event.keys}`]),
-        ];
-        const answer = await claude().ui.ask(`${name} ${listed(actions)}. Install it now?`, { options: ['Install', 'Not now'], header: 'Install' });
-        if (answer === 'Install')
+        if (await installer.consent({ ...event, updates: await updatesToShow().catch(() => undefined) }))
             return install(event.sha256);
+        await installer.close();
         phase = 'declined';
         endLine();
         claude().ui.log(`${name} is not installed. Run cmod install ${name} to install it.`);
@@ -203,14 +265,17 @@ export function createLifecycle(definition, checksPermissions = () => true) {
             if (event.kind === 'done' || event.kind === 'failed' || event.kind === 'needs-consent')
                 outcome = event;
         });
-        if (outcome?.kind === 'done')
+        if (outcome?.kind === 'done') {
+            for (const item of plugin.steps.permissions ?? [])
+                granted.add(item);
             return finish();
+        }
         if (outcome?.kind === 'needs-consent')
             return askConsent(outcome);
         const reason = outcome?.kind === 'failed' ? outcome.message : `cmod setup ${formatExit(code, lastError)}`;
         fail(reason, `Fix the cause, then run: cmod install ${definition.name}`);
     };
-    const fits = (found) => found !== undefined && isAtLeast(found, oldestCmodFor(plugin?.keys ?? {}));
+    const fits = (found) => found !== undefined && isAtLeast(found, oldestCmodFor(plugin?.steps ?? {}));
     const waitForcmod = (found) => {
         phase = 'waiting';
         showLine().wait('Waiting for cmod');
@@ -237,7 +302,7 @@ export function createLifecycle(definition, checksPermissions = () => true) {
         });
         const longWait = claude().clock.after(cmodWaitMs, () => showLine().wait(latest === undefined
             ? "Still waiting for cmod to download cmod. See cmod's own line."
-            : `PATH finds cmod ${latest}, and ${definition.name} needs cmod ${oldestCmodFor(plugin?.keys ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`));
+            : `PATH finds cmod ${latest}, and ${definition.name} needs cmod ${oldestCmodFor(plugin?.steps ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`));
     };
     const bootstrap = async (root) => {
         const progress = showLine();
@@ -256,6 +321,47 @@ export function createLifecycle(definition, checksPermissions = () => true) {
         if (phase !== 'failed')
             fail(messageOf(error), `Run cmod install ${definition.name} in a terminal to see the whole log.`);
     };
+    let consentMs = 0;
+    const consentStamp = async (path) => {
+        const stat = await claude().fs.stat(path).catch(() => undefined);
+        return stat?.kind === 'file' ? stat.mtimeMs : 0;
+    };
+    const refreshGrants = async () => {
+        if (plugin === undefined || plugin.name === cmodPluginName)
+            return;
+        const path = consentPath(plugin.store);
+        const modifiedMs = await consentStamp(path);
+        if (modifiedMs === consentMs)
+            return;
+        consentMs = modifiedMs;
+        const approved = modifiedMs === 0 ? [] : (parseConsent(JSON.parse(await claude().fs.read(path)), path)[plugin.name] ?? []);
+        granted.clear();
+        for (const item of plugin.steps.permissions ?? []) {
+            if (approved.includes(item))
+                granted.add(item);
+        }
+    };
+    const droppedParts = new Set();
+    const answerCheck = {
+        get plugin() {
+            return plugin?.name ?? definition.name;
+        },
+        isGranted: (item) => isCovered(granted, item, undefined),
+        dropped(item, part) {
+            if (droppedParts.has(item))
+                return;
+            droppedParts.add(item);
+            const declared = plugin?.steps.permissions ?? [];
+            const fix = declared.includes(item) ? `Turn it on in /mods ${definition.name}.` : `It needs "permissions": { "${item}": true } in package.json "cmod".`;
+            claude().ui.log(`${definition.name} answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it. ${fix}`);
+        },
+    };
+    const checkedRoute = async (event, e, next) => {
+        let below;
+        const passOn = (passed) => (below ??= next(passedDown(event, e, passed, answerCheck)));
+        const answer = await router.dispatch(event, e, passOn);
+        return (await checkedAnswer(event, e, answer, () => passOn(e), answerCheck));
+    };
     const whenActive = async () => {
         if (phase === 'ready')
             activation ??= activate().catch(report);
@@ -291,6 +397,9 @@ export function createLifecycle(definition, checksPermissions = () => true) {
                 if (started === undefined)
                     return;
                 plugin = started;
+                for (const item of started.granted)
+                    granted.add(item);
+                consentMs = await consentStamp(consentPath(started.store));
                 if (started.isInstalled) {
                     shouldRecord = started.shouldRecord;
                     if (shouldRecord)
@@ -306,6 +415,10 @@ export function createLifecycle(definition, checksPermissions = () => true) {
             }
         },
         async route(event, e, next) {
+            if (event === 'ui.render' && installer.draws(e))
+                return installer.draw(e);
+            if (event === 'ui.close')
+                installer.closed(e.id);
             if (event === 'classic.SessionStart')
                 missedSessionStart = undefined;
             if (event === 'classic.SessionStart' && runtime === undefined) {
@@ -321,6 +434,17 @@ export function createLifecycle(definition, checksPermissions = () => true) {
                 const isStopped = phase === 'declined' || phase === 'failed';
                 return { deny: isStopped ? notInstalled(definition.name) : `${definition.name} is installing. Try again when it's ready.` };
             }
+            const call = e;
+            if (event === 'cmod.call' && call.to === definition.name && mod !== undefined) {
+                if (call.method === pendingStepsMethod)
+                    return { value: await pendingSteps(mod) };
+                if (call.method === finishStepsMethod)
+                    return (await runSteps(mod), { value: null });
+            }
+            if (event === 'classic.UserPromptSubmit' || event === 'classic.SessionStart')
+                await refreshGrants().catch((error) => claude().ui.log(`${definition.name} keeps its grants from before: ${messageOf(error)}`, { to: 'debug' }));
+            if (checksAnswers(event) && phase === 'active')
+                return checkedRoute(event, e, next);
             const answer = router.dispatch(event, e, next);
             const render = e;
             if (event !== 'ui.render' || render.component !== 'AbovePrompt' || runtime === undefined || !runtime.progress.isShown)
@@ -331,22 +455,63 @@ export function createLifecycle(definition, checksPermissions = () => true) {
 }
 async function createMod(definition, runtime) {
     const { router, progress } = runtime;
-    const claude = checkingKeys(runtime.claude, definition.name, runtime.keys);
+    const claude = checkingKeys(runtime.claude, definition.name, runtime.steps.keys ?? {});
     const added = [];
     const hookEvents = [];
     const announce = (feature) => {
         added.push(feature);
     };
-    const [session, root, startCwd] = await Promise.all([claude.session.id(), claude.session.root(), claude.session.cwd()]);
+    const [session, root, startCwd, home, configHome] = await Promise.all([claude.session.id(), claude.session.root(), claude.session.cwd(), claude.env.home(), claude.env.configHome()]);
+    const { granted } = runtime;
+    const configRoot = configHome ?? (home === undefined ? undefined : `${home}/.claude`);
+    const grants = {
+        name: definition.name,
+        declared: runtime.steps.permissions ?? [],
+        granted: () => granted,
+        refresh: runtime.refreshGrants,
+        home,
+        configRoot,
+        projectRoot: () => modState.root,
+        freeFolders: () => [modState.root, runtime.dataFolder],
+    };
+    const checked = checkingGrants(claude, grants);
+    const files = createModFiles({
+        name: definition.name,
+        claude,
+        places: { home, configRoot, projectRoot: () => modState.root },
+        checkWrite: (path) => checkWrite(grants, `metadata.update(${path})`, path),
+    });
+    const pages = new Map();
+    const settingsPages = {
+        page(page) {
+            if (pages.has(page.id))
+                throw new Error(`${definition.name}: the settings page "${page.id}" is already added. Give each page its own id.`);
+            pages.set(page.id, { title: page.title, handle: area.ui.pane(page) });
+        },
+        async open(pageId) {
+            if (pageId === undefined) {
+                await claude.cmod.call({ to: cmodPluginName, method: 'openSettings', input: { mod: definition.name } });
+                return;
+            }
+            const page = pages.get(pageId);
+            if (page === undefined)
+                throw new Error(`${definition.name} has no settings page "${pageId}". It has: ${[...pages.keys()].join(', ') || 'none'}.`);
+            await page.handle.open({ focus: true });
+        },
+    };
     let cwd = startCwd;
     let loadedCwd = startCwd;
     let staleCwd;
     const area = createUi({ name: definition.name, claude, router, progress, announce, mod: () => mod });
     const modState = createState({ name: definition.name, initial: definition.state ?? {}, session, root, claude, changed: area.changed });
+    const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, changed: modState.changed });
     const held = runtime.checksPermissions() ? new Map() : undefined;
     const mod = {
         name: definition.name,
         state: modState.state,
+        get options() {
+            return modOptions.values;
+        },
         dataFolder: runtime.dataFolder,
         on(event, hook, options) {
             const bounded = options?.timeoutMs === undefined ? hook : timedHook(definition.name, event, hook, checkedMs(definition.name, `the ${event} hook's timeoutMs`, options.timeoutMs), claude);
@@ -357,7 +522,7 @@ async function createMod(definition, runtime) {
             else
                 router.add(`classic.${event}`, classicHook(definition.name, event, bounded, claude, agents));
         },
-        use: (job) => job({ mod, claude, on: (event, hook) => router.add(event, hook), announce, reserveName, toolCalls: agents }),
+        use: (job) => job({ mod, announce, reserveName, toolCalls: agents }),
         every(ms, hook) {
             let isRunning = false;
             return claude.clock.every(checkedMs(definition.name, 'mod.every', ms), () => {
@@ -374,33 +539,42 @@ async function createMod(definition, runtime) {
         },
         ui: area.ui,
         process: {
-            run: (argv, init) => claude.process.run(argv, init),
-            spawn: (argv, init) => claude.process.spawn({ ...init, argv }),
+            run: (argv, init) => checked.process.run(argv, init),
+            spawn: (argv, init) => checked.process.spawn({ ...init, argv }),
         },
         fs: {
-            read: (path) => claude.fs.read(path),
-            write: (path, text) => claude.fs.write(path, text),
-            list: (path) => claude.fs.list(path),
-            exists: (path) => claude.fs.exists(path),
-            stat: (path, options) => claude.fs.stat(path, options),
+            read: (path) => checked.fs.read(path),
+            write: (path, text) => checked.fs.write(path, text),
+            list: (path) => checked.fs.list(path),
+            exists: (path) => checked.fs.exists(path),
+            stat: (path, options) => checked.fs.stat(path, options),
+            find: (glob) => files.find(glob),
+        },
+        metadata: {
+            read: (path) => files.read(path),
+            update: (path, change) => files.update(path, change),
         },
-        http: { fetch: (url, init) => claude.http.fetch(url, init) },
-        settings: { read: (args) => claude.settings.read(args) },
+        http: { fetch: (url, init) => checked.http.fetch(url, init) },
+        settings: settingsPages,
         session: {
-            messages: claude.session.messages,
+            messages: ((args) => (args === undefined ? checked.session.messages() : checked.session.messages({ agentId: args.agentId }))),
             async append(text) {
-                const added = await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } });
+                const added = await checked.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } });
                 if (added.deny !== undefined)
                     throw new Error(`${definition.name}: Claude Code refused the note: ${added.deny}`);
             },
             async submit(text) {
-                const submitted = await claude.prompt.submit({ text });
+                const submitted = await checked.prompt.submit({ text });
                 if ('drop' in submitted && typeof submitted.drop === 'string')
                     throw new Error(`${definition.name}: Claude Code dropped the prompt: ${submitted.drop}`);
             },
         },
-        agent: { spawn: (args) => claude.agent.spawn(args) },
-        model: { complete: (request, options) => claude.model.complete(request, options) },
+        agent: { spawn: (args) => checked.agent.spawn(args) },
+        model: { complete: (completion, options) => checked.model.complete(completion, options) },
+        permissions: {
+            has: (name, value) => isCovered(granted, itemOf(name, value), home),
+        },
+        claude: { ...checked, on: (event, hook) => router.add(event, hook) },
         get projectRoot() {
             return modState.root;
         },
@@ -427,6 +601,8 @@ async function createMod(definition, runtime) {
                     cwd = loadedCwd;
                 throw error;
             });
+            if (hasMovedRoot)
+                await modOptions.load(nextRoot);
             loadedCwd = nextCwd;
             if (!hasMovedRoot)
                 area.changed();
@@ -465,7 +641,17 @@ async function createMod(definition, runtime) {
     });
     router.add('skill.prompt', userSkillHook(claude));
     const api = Object.fromEntries(Object.entries(definition.api ?? {}).map(([method, run]) => [method, (input) => run(input, mod)]));
-    router.add('cmod.call', (e, next) => (e.to === definition.name ? answerCall(definition.name, api, e) : next(e)));
+    router.add('cmod.call', async (e, next) => {
+        if (e.to !== definition.name)
+            return next(e);
+        if (e.method === settingsPagesMethod)
+            return { value: [...pages].map(([id, { title }]) => ({ id, title })) };
+        if (e.method === openPageMethod) {
+            await settingsPages.open(String(e.input));
+            return { value: null };
+        }
+        return answerCall(definition.name, api, e);
+    });
     const agents = toolCalls(claude, router);
     const names = new Set();
     const reserveName = (kind, name, taken) => {
@@ -475,6 +661,10 @@ async function createMod(definition, runtime) {
         names.add(key);
     };
     await failsAs('its state did not load', () => modState.load());
+    await failsAs('its options did not load', () => modOptions.load(root));
+    const missing = modOptions.missing;
+    if (missing.length > 0)
+        throw new MissingOptions(missing, missing.map((key) => definition.options?.[key]?.title ?? key));
     await failsAs('its setup function threw', () => definition.setup(mod));
     const permissionHooks = permissionEvents.filter((event) => router.has(event));
     if (permissionHooks.length > 0 && !runtime.checksPermissions()) {

package/runtime/metadata.d.ts

@@ -0,0 +1,20 @@
+import type { FileMatch, Metadata } from '../mod.js';
+import type { Claude } from './claude.js';
+export type Places = {
+    readonly home: string | undefined;
+    readonly configRoot: string | undefined;
+    readonly projectRoot: () => string;
+};
+export type ModFiles = {
+    find(glob: string | readonly string[]): Promise<readonly FileMatch[]>;
+    read(path: string): Promise<Metadata>;
+    update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>;
+};
+export declare function resolvedPath(path: string, places: Places): string;
+export declare function createModFiles({ name, claude, places, checkWrite }: {
+    readonly name: string;
+    readonly claude: Claude;
+    readonly places: Places;
+    readonly checkWrite: (path: string) => Promise<void>;
+}): ModFiles;
+//# sourceMappingURL=metadata.d.ts.map

package/runtime/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/runtime/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAIpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAA;IACrE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxF,CAAA;AAUD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAAG,QAAQ,CAoHhN"}