@cmodjs/core 0.1.14 → 0.2.0

package/runtime/grants.d.ts

@@ -0,0 +1,28 @@
+import type { Claude } from './claude.js';
+import type { RoutedEvent } from './hooks.js';
+export type Grants = {
+    readonly name: string;
+    readonly declared: readonly string[];
+    readonly granted: () => ReadonlySet<string>;
+    readonly refresh: () => Promise<void>;
+    readonly home: string | undefined;
+    readonly configRoot: string | undefined;
+    readonly projectRoot: () => string;
+    readonly freeFolders: () => readonly string[];
+};
+export declare class PermissionRefused extends Error {
+}
+export declare function checkWrite(grants: Grants, call: string, path: string): Promise<void>;
+export declare function checkingGrants(claude: Claude, grants: Grants): Claude;
+export declare function itemOf(name: string, value?: string): string;
+export declare function isCovered(granted: ReadonlySet<string>, item: string, home: string | undefined): boolean;
+export declare function refusal(grants: Pick<Grants, 'name' | 'declared' | 'home'>, call: string, item: string): string;
+export type AnswerCheck = {
+    readonly plugin: string;
+    isGranted(item: string): boolean;
+    dropped(item: string, part: string): void;
+};
+export declare function checksAnswers(event: RoutedEvent): boolean;
+export declare function passedDown(event: RoutedEvent, original: unknown, passed: unknown, check: AnswerCheck): unknown;
+export declare function checkedAnswer(event: RoutedEvent, e: unknown, answer: unknown, below: () => Promise<unknown>, check: AnswerCheck): Promise<unknown>;
+//# sourceMappingURL=grants.d.ts.map

package/runtime/grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../src/runtime/grants.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,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;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,SAAS,MAAM,EAAE,CAAA;CAC9C,CAAA;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAc/C,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpF;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA6ErE;AAmBD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAUvG;AAcD,wBAAgB,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9G;AA4BD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1C,CAAA;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAa9G;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CA+BxJ"}

package/runtime/grants.js

@@ -0,0 +1,286 @@
+import { permissionWords } from '../records.js';
+import { relativePath } from '../utils/paths.js';
+export class PermissionRefused extends Error {
+}
+const configFiles = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json'];
+const startsTurns = ['CronCreate'];
+const ownSchedule = ['CronDelete', 'CronList'];
+async function checkGrant(grants, call, item) {
+    if (item === undefined)
+        return;
+    await grants.refresh();
+    if (!isCovered(grants.granted(), item, grants.home))
+        throw new PermissionRefused(refusal(grants, call, item));
+}
+export function checkWrite(grants, call, path) {
+    return checkGrant(grants, call, writeItem(grants, path));
+}
+export function checkingGrants(claude, grants) {
+    const gate = (call, item) => checkGrant(grants, call, item);
+    return {
+        ...claude,
+        process: {
+            async run(argv, init) {
+                await gate(`process.run(${argv.join(' ')})`, `run:${programOf(argv)}`);
+                return claude.process.run(argv, init);
+            },
+            spawn(request) {
+                const started = gate(`process.spawn(${request.argv.join(' ')})`, `run:${programOf(request.argv)}`).then(() => claude.process.spawn(request));
+                return spawned(started);
+            },
+        },
+        fs: {
+            ...claude.fs,
+            async read(path) {
+                await gate(`fs.read(${path})`, readItem(grants, path));
+                return claude.fs.read(path);
+            },
+            async write(path, text) {
+                await gate(`fs.write(${path})`, writeItem(grants, path));
+                return claude.fs.write(path, text);
+            },
+        },
+        http: {
+            async fetch(url, init) {
+                await gate(`http.fetch(${url})`, `network:${init?.socketPath ?? hostOf(url)}`);
+                return claude.http.fetch(url, init);
+            },
+        },
+        config: {
+            ...claude.config,
+            set: (async (args) => {
+                await gate('config.set', 'config');
+                return claude.config.set(args);
+            }),
+        },
+        session: {
+            ...claude.session,
+            messages: (async (...args) => {
+                await gate('session.messages', 'conversation');
+                return claude.session.messages(...args);
+            }),
+            append: (async (args) => {
+                await gate('session.append', 'prompt');
+                return claude.session.append(args);
+            }),
+        },
+        prompt: {
+            submit: (async (args) => {
+                await gate('session.submit', 'prompt');
+                return claude.prompt.submit(args);
+            }),
+        },
+        model: {
+            complete: (async (...args) => {
+                await gate('model.complete', 'model');
+                return claude.model.complete(...args);
+            }),
+        },
+        agent: {
+            ...claude.agent,
+            async spawn(args) {
+                await gate('agent.spawn', 'agents');
+                return claude.agent.spawn(args);
+            },
+        },
+        tool: {
+            ...claude.tool,
+            call: (async (input) => {
+                const item = startsTurns.includes(input.tool) ? 'prompt' : ownSchedule.includes(input.tool) ? undefined : 'tools';
+                await gate(`tool.call(${input.tool})`, item);
+                return claude.tool.call(input);
+            }),
+        },
+    };
+}
+function spawned(started) {
+    const result = started.then((stream) => stream.result);
+    result.catch(() => undefined);
+    const stream = {
+        next: async () => (await started).next(),
+        async return(value) {
+            const running = await started.catch(() => undefined);
+            return (await running?.return?.(value)) ?? { done: true, value };
+        },
+        [Symbol.asyncIterator]: () => stream,
+        result,
+    };
+    return stream;
+}
+export function itemOf(name, value) {
+    return value === undefined ? name : `${name}:${value}`;
+}
+export function isCovered(granted, item, home) {
+    if (granted.has(item))
+        return true;
+    const split = item.indexOf(':');
+    if (split === -1)
+        return false;
+    const name = item.slice(0, split);
+    const target = expanded(item.slice(split + 1), home);
+    const values = [...granted].filter((each) => each.startsWith(`${name}:`)).map((each) => expanded(each.slice(name.length + 1), home));
+    if (name === 'run')
+        return values.includes('*') || values.includes(target);
+    if (name === 'files')
+        return values.some((each) => relativePath(each, target) !== undefined);
+    return values.includes(target);
+}
+function readItem(grants, path) {
+    if (grants.configRoot === undefined)
+        return undefined;
+    return relativePath(`${grants.configRoot}/projects`, path) === undefined ? undefined : 'conversation';
+}
+function writeItem(grants, path) {
+    const root = grants.projectRoot();
+    if (configFiles.some((file) => `${root}/${file}` === path))
+        return 'config';
+    if (grants.freeFolders().some((folder) => relativePath(folder, path) !== undefined))
+        return undefined;
+    return `files:${path}`;
+}
+export function refusal(grants, call, item) {
+    const { name } = grants;
+    if (isCovered(new Set(grants.declared), item, grants.home))
+        return `${name} calls ${call} without your grant to "${permissionWords(item)}". Turn it on in /mods ${name}.`;
+    return `${name} calls ${call}, which needs ${declaration(item, grants.home)} in package.json "cmod".`;
+}
+function declaration(item, home) {
+    const split = item.indexOf(':');
+    if (split === -1)
+        return `"permissions": { "${item}": true }`;
+    const name = item.slice(0, split);
+    const target = item.slice(split + 1);
+    const fromHome = home === undefined ? undefined : relativePath(home, target);
+    const shown = name !== 'run' && fromHome !== undefined ? `~/${fromHome}` : target;
+    return `"permissions": { "${name}": ["${shown}"] }`;
+}
+const classicParts = {
+    additionalContext: 'prompt',
+    initialUserMessage: 'prompt',
+    suppressOriginalPrompt: 'prompt',
+    updatedToolOutput: 'prompt',
+    updatedMCPToolOutput: 'prompt',
+    updatedInput: 'tools',
+    retry: 'approve',
+};
+const blocksKeepWorking = ['classic.Stop', 'classic.PostToolUse'];
+const reservedToolKeys = ['tool', 'tool_use_id'];
+export function checksAnswers(event) {
+    return event.startsWith('classic.') || event === 'tool.check' || event === 'tool.call' || event === 'prompt.context' || event === 'prompt.submit';
+}
+export function passedDown(event, original, passed, check) {
+    if (passed === original)
+        return passed;
+    if (event === 'tool.call') {
+        if (sameExcept(original, passed, reservedToolKeys) || check.isGranted('tools'))
+            return passed;
+        check.dropped('tools', 'a changed tool input');
+        return original;
+    }
+    if (event === 'prompt.context' || event === 'prompt.submit') {
+        if (same(original, passed) || check.isGranted('prompt'))
+            return passed;
+        check.dropped('prompt', event === 'prompt.submit' ? 'a rewritten prompt' : 'changed context');
+        return original;
+    }
+    return passed;
+}
+export async function checkedAnswer(event, e, answer, below, check) {
+    if (!isFields(answer))
+        return answer;
+    if (event === 'tool.check')
+        return decided(answer['decision'], answer, below, check);
+    if (event === 'classic.PermissionRequest') {
+        const decision = isFields(answer['decision']) ? answer['decision']['behavior'] : undefined;
+        return decided(decision, answer, below, check);
+    }
+    if (event.startsWith('classic.'))
+        return classicAnswer(event, answer, below, check);
+    if (event === 'tool.call') {
+        if (answer['deny'] !== undefined || check.isGranted('prompt'))
+            return answer;
+        const tool = isFields(e) ? e['tool'] : undefined;
+        if (typeof tool === 'string' && tool.startsWith(`mcp__${check.plugin}__`)) {
+            if (answer['context'] === undefined)
+                return answer;
+            check.dropped('prompt', 'context after a tool call');
+            const { context: _context, ...rest } = answer;
+            return rest;
+        }
+        const theirs = await below();
+        if (same(answer, theirs))
+            return answer;
+        check.dropped('prompt', same(contextOf(answer), contextOf(theirs)) ? 'a changed tool result' : 'context after a tool call');
+        return theirs;
+    }
+    if (event === 'prompt.submit' && answer['drop'] !== undefined)
+        return answer;
+    if (event === 'prompt.context' || event === 'prompt.submit') {
+        if (check.isGranted('prompt'))
+            return answer;
+        const theirs = await below();
+        if (same(answer, theirs))
+            return answer;
+        check.dropped('prompt', event === 'prompt.submit' ? 'a rewritten prompt' : 'changed context');
+        return theirs;
+    }
+    return answer;
+}
+async function decided(decision, answer, below, check) {
+    if ((decision !== 'allow' && decision !== 'ask') || check.isGranted('approve'))
+        return answer;
+    const theirs = await below();
+    if (same(answer, theirs))
+        return answer;
+    check.dropped('approve', `${decision} on a tool call`);
+    return theirs;
+}
+async function classicAnswer(event, answer, below, check) {
+    const blocks = blocksKeepWorking.includes(event) ? [['block', 'prompt']] : [];
+    const parts = [...Object.entries(classicParts), ...blocks].filter(([part, item]) => answer[part] !== undefined && !check.isGranted(item));
+    if (parts.length === 0)
+        return answer;
+    const theirs = await below();
+    const kept = { ...answer };
+    const theirFields = isFields(theirs) ? theirs : {};
+    for (const [part, item] of parts) {
+        if (same(answer[part], theirFields[part]))
+            continue;
+        check.dropped(item, part);
+        if (theirFields[part] === undefined)
+            delete kept[part];
+        else
+            kept[part] = theirFields[part];
+    }
+    return kept;
+}
+function contextOf(answer) {
+    return isFields(answer) ? answer['context'] : undefined;
+}
+function same(left, right) {
+    return left === right || JSON.stringify(left) === JSON.stringify(right);
+}
+function sameExcept(left, right, keys) {
+    if (!isFields(left) || !isFields(right))
+        return same(left, right);
+    const without = (fields) => Object.fromEntries(Object.entries(fields).filter(([key]) => !keys.includes(key)));
+    return same(without(left), without(right));
+}
+function isFields(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function programOf(argv) {
+    const command = argv[0] ?? '';
+    return command.slice(command.lastIndexOf('/') + 1);
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}
+function expanded(path, home) {
+    return path.startsWith('~/') && home !== undefined ? `${home}${path.slice(1)}` : path;
+}

package/runtime/installer.d.ts

@@ -0,0 +1,23 @@
+import type { Args, Frozen, RenderElement } from 'claude-code';
+import type { Step } from '../installer.js';
+import type { Mod } from '../mod.js';
+import type { Option } from '../options.js';
+import type { Claude } from './claude.js';
+export declare const installerPaneId = "cmod-installer";
+export type Consent = {
+    readonly install: string;
+    readonly uninstall: string;
+    readonly keys: string;
+    readonly permissions: readonly string[];
+};
+export type Installer = {
+    draws(e: Frozen<Args<'ui.render'>>): boolean;
+    draw(e: Frozen<Args<'ui.render'>>): RenderElement;
+    closed(id: string): void;
+    consent(consent: Consent): Promise<boolean>;
+    options(missing: readonly (readonly [string, Option])[], save: (key: string, value: string) => Promise<string | undefined>): Promise<boolean>;
+    step<State extends object>(mod: Mod<State>, step: Step<State>, index: number, total: number): Promise<boolean>;
+    close(): Promise<void>;
+};
+export declare function createInstaller(name: string, claude: () => Claude): Installer;
+//# sourceMappingURL=installer.d.ts.map

package/runtime/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/runtime/installer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAiB,MAAM,aAAa,CAAA;AAC7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAI3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,eAAO,MAAM,eAAe,mBAAmB,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC,CAAA;AAOD,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,OAAO,CAAA;IAC5C,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,aAAa,CAAA;IACjD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7I,IAAI,CAAC,KAAK,SAAS,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC9G,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,CAAA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM,GAAG,SAAS,CAiI7E"}

package/runtime/installer.js

@@ -0,0 +1,113 @@
+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 }) {
+            const changes = [...(install === '' ? [] : [`Run ${install} now${uninstall === '' ? '' : `, and ${uninstall} when you remove it`}`]), ...(install === '' && uninstall !== '' ? [`Run ${uninstall} when you remove it`] : []), ...(keys === '' ? [] : [`Bind ${keys}`])];
+            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,EAAgQ,KAAK,KAAK,EAAE,MAAM,eAAe,CAAA;AAGxS,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,CAmVlB"}