@cmodjs/core 0.1.14 → 0.2.0

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, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, scriptsSha256, settingsPagesMethod, storeFolder } 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) => {
@@ -171,14 +232,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))
             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 +259,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 +296,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 +315,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 +391,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 +409,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 +428,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 +449,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 +516,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 +533,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 +595,8 @@ async function createMod(definition, runtime) {
                     cwd = loadedCwd;
                 throw error;
             });
+            if (hasMovedRoot)
+                await modOptions.load(nextRoot);
             loadedCwd = nextCwd;
             if (!hasMovedRoot)
                 area.changed();
@@ -465,7 +635,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 +655,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"}

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"}