@cmodjs/core 0.1.14 → 0.2.1

package/src/mod.ts

@@ -21,13 +21,15 @@ import type {
   ProcessSpawnRequest,
   ProcessSpawnResult,
   RenderElement,
-  Settings,
-  SettingsReadArgs,
+  SessionMessage,
   Timer,
   ToastOptions,
   UiScrollArgs,
   UiScrollResult,
 } from 'claude-code'
+import type { Step } from './installer.js'
+import { checkOptions, type Option, type Options, type OptionValues } from './options.js'
+import type { FlagPermission, ListPermission } from './records.js'
 import type { Claude } from './runtime/claude.js'
 import type { RoutedEvent } from './runtime/hooks.js'
 import type { RoutedHook } from './runtime/router.js'
@@ -125,9 +127,30 @@ export type HookOptions = {
   readonly timeoutMs?: number
 }
 
-export type Mod<State extends object = Record<never, never>> = {
+export type ScrollArgs = Omit<UiScrollArgs, 'to'> & { readonly to: Exclude<UiScrollArgs['to'], { requestId: string }> }
+
+export type ModClaude = Claude & {
+  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
+}
+
+export type Metadata = Readonly<Record<string, string>>
+
+export type FileMatch = {
+  readonly path: string
+  readonly name?: string
+  readonly metadata: Metadata
+  readonly error?: string
+}
+
+type SessionMessages = {
+  (): Promise<SessionMessage[]>
+  (args: { readonly agentId: string }): Promise<SessionMessage[] | { readonly deny: string }>
+}
+
+export type Mod<State extends object = Record<never, never>, Declared extends Options = Options> = {
   readonly name: string
   readonly state: Readonly<State>
+  readonly options: OptionValues<Declared>
   readonly dataFolder: string
   on<E extends ModEvent>(event: E, hook: ModHook<E>, options?: HookOptions): void
   use<Handle>(job: Job<Handle, State>): Handle
@@ -138,7 +161,7 @@ export type Mod<State extends object = Record<never, never>> = {
     toast(text: string, options?: ToastOptions): void
     progress<T>(title: string, task: (report: (step: ProgressStep) => void) => Promise<T>): Promise<T>
     ask(question: string, options?: readonly string[] | AskOptions): Promise<string>
-    scroll(args: UiScrollArgs): Promise<UiScrollResult>
+    scroll(args: ScrollArgs): Promise<UiScrollResult>
   }
   readonly process: {
     run(argv: readonly string[], init?: ProcessRunInit): Promise<ProcessRunResult>
@@ -150,15 +173,21 @@ export type Mod<State extends object = Record<never, never>> = {
     list(path?: string): Promise<FsEntry[]>
     exists(path: string): Promise<boolean>
     stat(path: string, options?: FsStatOptions): Promise<FsStat>
+    find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
+  }
+  readonly metadata: {
+    read(path: string): Promise<Metadata>
+    update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>
   }
   readonly http: {
     fetch(url: string, init?: HttpInit): Promise<HttpResponse>
   }
   readonly settings: {
-    read(args?: SettingsReadArgs): Promise<Settings>
+    page(page: Pane<State>): void
+    open(pageId?: string): Promise<void>
   }
   readonly session: {
-    messages: Claude['session']['messages']
+    messages: SessionMessages
     append(text: string): Promise<void>
     submit(text: string): Promise<void>
   }
@@ -168,9 +197,14 @@ export type Mod<State extends object = Record<never, never>> = {
   readonly model: {
     complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult>
   }
+  readonly permissions: {
+    has(name: ListPermission, value: string): boolean
+    has(name: FlagPermission): boolean
+  }
   readonly projectRoot: string
   readonly cwd: string
   readonly dependencies: CmodDependencies
+  readonly claude: ModClaude
 }
 
 type StateGroups = {
@@ -184,17 +218,17 @@ type Api<Contract, State extends object> = {
   readonly [Method in keyof Contract]: Contract[Method] extends (input: infer Input) => infer Result ? (input: Input, mod: Mod<State>) => Result | Awaited<Result> : never
 }
 
-export type ModDefinition<State extends StateGroups = Record<never, never>, Name extends string = string> = {
+export type ModDefinition<State extends StateGroups = Record<never, never>, Name extends string = string, Declared extends Options = Record<never, Option>> = {
   readonly name: Name
   readonly state?: State
+  readonly options?: Declared
   readonly api?: Name extends keyof CmodDependencies ? Api<CmodDependencies[Name], State> : { readonly [method: string]: (input: never, mod: Mod<State>) => unknown }
-  setup(mod: Mod<State>): void | Promise<void>
+  readonly installer?: readonly Step<State>[]
+  setup(mod: Mod<State, Declared>): void | Promise<void>
 }
 
 export type JobContext<State extends object = Record<never, never>> = {
   readonly mod: Mod<State>
-  readonly claude: Claude
-  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
   announce(feature: string): void
   reserveName(kind: string, name: string, taken: string): void
   readonly toolCalls: ToolCalls
@@ -202,7 +236,8 @@ export type JobContext<State extends object = Record<never, never>> = {
 
 export type Job<Handle, State extends object = Record<never, never>> = (context: JobContext<State>) => Handle
 
-export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string>(definition: ModDefinition<State, Name>): ModDefinition<State, Name> {
+export function defineMod<State extends StateGroups = Record<never, never>, Name extends string = string, const Declared extends Options = Record<never, Option>>(definition: ModDefinition<State, Name, Declared>): ModDefinition<State, Name, Declared> {
   if (definition.name.trim() === '') throw new Error('defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.')
+  if (definition.options !== undefined) checkOptions(definition.name, definition.options)
   return definition
 }

package/src/options.ts

@@ -0,0 +1,91 @@
+export type OptionKind = 'text' | 'secret' | 'number' | 'toggle' | 'choice' | 'folder' | 'file' | 'list'
+
+export type OptionValue = string | number | boolean | readonly string[]
+
+type Described = { readonly title: string; readonly description: string }
+
+export type Option<Value extends OptionValue = OptionValue> = Described & {
+  readonly kind: OptionKind
+  readonly default?: Value
+  readonly min?: number
+  readonly max?: number
+  readonly choices?: readonly string[]
+}
+
+export type Options = Readonly<Record<string, Option>>
+
+export type OptionValues<Declared extends Options> = { readonly [Key in keyof Declared]: Declared[Key] extends Option<infer Value> ? Value : never }
+
+export type UserConfigField = Described & {
+  readonly type: 'string' | 'number' | 'boolean' | 'directory' | 'file'
+  readonly sensitive?: true
+  readonly multiple?: true
+  readonly default?: OptionValue
+  readonly min?: number
+  readonly max?: number
+  readonly options?: readonly string[]
+}
+
+export const option = {
+  text: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, kind: 'text' }),
+  secret: (field: Described): Option<string> => ({ ...field, kind: 'secret' }),
+  number: (field: Described & { readonly default?: number; readonly min?: number; readonly max?: number }): Option<number> => ({ ...field, kind: 'number' }),
+  toggle: (field: Described & { readonly default?: boolean }): Option<boolean> => ({ ...field, kind: 'toggle', default: field.default ?? false }),
+  choice: <const Choice extends string>(choices: readonly Choice[], field: Described & { readonly default?: Choice }): Option<Choice> => ({ ...field, kind: 'choice', choices }),
+  folder: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, kind: 'folder' }),
+  file: (field: Described & { readonly default?: string }): Option<string> => ({ ...field, kind: 'file' }),
+  list: (field: Described & { readonly default?: readonly string[] }): Option<readonly string[]> => ({ ...field, kind: 'list' }),
+}
+
+const types: Readonly<Record<OptionKind, UserConfigField['type']>> = { text: 'string', secret: 'string', number: 'number', toggle: 'boolean', choice: 'string', folder: 'directory', file: 'file', list: 'string' }
+
+const optionKey = /^[A-Za-z_]\w*$/
+
+export function checkOptions(name: string, options: Options): Options {
+  for (const [key, declared] of Object.entries(options)) {
+    const at = `${name}: options.${key}`
+    if (!optionKey.test(key)) throw new Error(`${at} is not an option name. Use letters, digits, and _, starting with a letter, as Claude Code passes each option on as CLAUDE_PLUGIN_OPTION_${key.toUpperCase()}.`)
+    if (declared.title.trim() === '') throw new Error(`${at} needs a title, the label /config shows.`)
+    if (declared.kind === 'choice' && (declared.choices ?? []).length === 0) throw new Error(`${at} is a choice with no choices. Give option.choice(['a', 'b'], { ... }).`)
+    if (declared.kind === 'choice' && declared.default !== undefined && !(declared.choices ?? []).includes(declared.default as string)) throw new Error(`${at} defaults to ${String(declared.default)}, which is not one of its choices: ${(declared.choices ?? []).join(', ')}.`)
+  }
+  return options
+}
+
+export function userConfigOf(options: Options): Record<string, UserConfigField> {
+  return Object.fromEntries(
+    Object.entries(options).map(([key, declared]) => [
+      key,
+      {
+        type: types[declared.kind],
+        title: declared.title,
+        description: declared.description,
+        ...(declared.kind === 'secret' ? { sensitive: true } : {}),
+        ...(declared.kind === 'list' ? { multiple: true } : {}),
+        ...(declared.kind === 'choice' ? { options: declared.choices } : {}),
+        ...(declared.default === undefined ? {} : { default: declared.default }),
+        ...(declared.min === undefined ? {} : { min: declared.min }),
+        ...(declared.max === undefined ? {} : { max: declared.max }),
+      } satisfies UserConfigField,
+    ]),
+  )
+}
+
+export function isUnset(value: unknown): boolean {
+  return value === undefined || value === '' || (Array.isArray(value) && value.length === 0)
+}
+
+export function fitsOption(declared: Option, value: unknown): string | undefined {
+  const kind = declared.kind
+  if (kind === 'toggle') return typeof value === 'boolean' ? undefined : 'takes true or false'
+  if (kind === 'number') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return 'takes a number'
+    if (declared.min !== undefined && value < declared.min) return `takes ${declared.min} or more`
+    if (declared.max !== undefined && value > declared.max) return `takes ${declared.max} or less`
+    return undefined
+  }
+  if (kind === 'list') return Array.isArray(value) && value.every((item) => typeof item === 'string') ? undefined : 'takes a list of text'
+  if (typeof value !== 'string') return 'takes text'
+  if (kind === 'choice' && !(declared.choices ?? []).includes(value)) return `takes one of: ${(declared.choices ?? []).join(', ')}`
+  return undefined
+}

package/src/records.ts

@@ -11,14 +11,28 @@ export type InstallRecord = {
   keys: Readonly<Record<string, string>>
 }
 
-export type Steps = { install?: string; uninstall?: string; program?: string; keys?: Readonly<Record<string, string>> }
+export type Steps = {
+  install?: string
+  uninstall?: string
+  program?: string
+  keys?: Readonly<Record<string, string>>
+  permissions?: readonly string[]
+}
+
+export const listPermissions = ['network', 'run', 'files'] as const
+export const flagPermissions = ['conversation', 'prompt', 'model', 'agents', 'tools', 'config', 'approve'] as const
+export type ListPermission = (typeof listPermissions)[number]
+export type FlagPermission = (typeof flagPermissions)[number]
+const permissionNames: readonly string[] = [...listPermissions, ...flagPermissions]
+const hostName = /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$/
+const programName = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/
 
 export type ReadFile = (path: string) => Promise<string | undefined>
 
 export type RunnerEvent =
   | { kind: 'progress'; done: number; total: number; label: string }
   | { kind: 'log'; text: string }
-  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string }
+  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string; permissions: readonly string[] }
   | { kind: 'done'; name: string; version?: string }
   | { kind: 'missing'; name: string }
   | { kind: 'failed'; code: number; message: string }
@@ -112,7 +126,106 @@ export function readSteps(pkg: unknown): Steps | undefined {
   if (!isObject(steps)) throw new Error('package.json has a "cmod" key that is not an object. Write "cmod": { "install": "./setup/install.sh", "uninstall": "./setup/uninstall.sh" }.')
   const program = steps['program']
   if (program !== undefined && (typeof program !== 'string' || !pluginName.test(program))) throw new Error('package.json "cmod.program" must be the program\'s command, such as "hello".')
-  return { ...readCommand(steps, 'install'), ...readCommand(steps, 'uninstall'), ...(program === undefined ? {} : { program }), ...readKeys(steps['keys']) }
+  const permissions = readPermissions(steps)
+  return {
+    ...readCommand(steps, 'install'),
+    ...readCommand(steps, 'uninstall'),
+    ...(program === undefined ? {} : { program }),
+    ...readKeys(steps['keys']),
+    ...(permissions.length === 0 ? {} : { permissions }),
+  }
+}
+
+function readPermissions(steps: Record<string, unknown>): string[] {
+  const declared = steps['permissions']
+  if (declared === undefined) return []
+  const at = 'package.json "cmod.permissions"'
+  if (!isObject(declared)) throw new Error(`${at} must be an object, such as { "network": ["api.github.com"], "prompt": true }.`)
+  const items: string[] = []
+  for (const [name, value] of Object.entries(declared)) {
+    if (!permissionNames.includes(name)) throw new Error(`${at} names "${name}", which is not a permission. Use ${listed(permissionNames.map((each) => `"${each}"`))}.`)
+    if ((flagPermissions as readonly string[]).includes(name)) {
+      if (value !== true) throw new Error(`${at} sets "${name}" to ${JSON.stringify(value)}. Write "${name}": true, or leave it out.`)
+      items.push(name)
+      continue
+    }
+    if (name === 'run' && value === '*') {
+      items.push('run:*')
+      continue
+    }
+    const example = name === 'network' ? '["api.github.com"]' : name === 'run' ? '["gh"], or "*" for any program' : '["~/.zshrc"]'
+    if (!Array.isArray(value) || value.length === 0 || !value.every((each) => typeof each === 'string')) throw new Error(`${at} sets "${name}" to ${JSON.stringify(value)}. Write a list, such as "${name}": ${example}.`)
+    for (const each of value as string[]) {
+      const isPath = /^(~\/|\/)/.test(each) && !each.split('/').includes('..')
+      const isValid = name === 'network' ? hostName.test(each) || isPath : name === 'run' ? programName.test(each) : isPath
+      if (!isValid) throw new Error(`${at} lists "${each}" under "${name}". Write ${name === 'network' ? 'a host alone, such as "api.github.com", or a socket path, such as "/var/run/docker.sock"' : name === 'run' ? 'a program\'s command, such as "gh"' : 'a path that starts with ~/ or /, such as "~/.zshrc"'}.`)
+      items.push(`${name}:${each}`)
+    }
+  }
+  return items
+}
+
+export function permissionWords(item: string): string {
+  const split = item.indexOf(':')
+  const target = item.slice(split + 1)
+  switch (split === -1 ? item : item.slice(0, split)) {
+    case 'network':
+      return `Connect to ${target}`
+    case 'run':
+      return target === '*' ? 'Run any program on your computer' : `Run ${target} on your computer`
+    case 'files':
+      return `Change ${target}`
+    case 'conversation':
+      return 'Read this conversation'
+    case 'prompt':
+      return 'Add text Claude reads and start turns'
+    case 'model':
+      return 'Ask a model, which uses your plan'
+    case 'agents':
+      return 'Start agents'
+    case 'tools':
+      return "Use and change Claude's tool calls"
+    case 'config':
+      return 'Change your Claude Code settings'
+    case 'approve':
+      return "Approve Claude's tool calls for you"
+    default:
+      return item
+  }
+}
+
+export const settingsPagesMethod = 'cmod:settingsPages'
+
+export const openPageMethod = 'cmod:openPage'
+
+export const pendingStepsMethod = 'cmod:pendingSteps'
+
+export const finishStepsMethod = 'cmod:finishSteps'
+
+export function marketplaceOf(root: string, name: string): string | undefined {
+  const installed = /\/cache\/([^/]+)\/([^/]+)\/[^/]+\/?$/.exec(root)
+  return installed?.[2] === name ? installed[1] : undefined
+}
+
+export function updatesToTurnOn(marketplace: string | undefined, settings: unknown, known: unknown): string | undefined {
+  if (marketplace === undefined) return undefined
+  const declared = isObject(settings) && isObject(settings['extraKnownMarketplaces']) ? settings['extraKnownMarketplaces'][marketplace] : undefined
+  const fetched = isObject(known) ? known[marketplace] : undefined
+  const isDecided = [declared, fetched].some((entry) => isObject(entry) && typeof entry['autoUpdate'] === 'boolean')
+  const hasSource = [declared, fetched].some((entry) => isObject(entry) && isObject(entry['source']))
+  return isDecided || !hasSource ? undefined : marketplace
+}
+
+export function consentPath(store: string): string {
+  return `${store}/consent.json`
+}
+
+export function parseConsent(value: unknown, path: string): Record<string, string[]> {
+  if (value === undefined) return Object.create(null)
+  if (!isObject(value) || Object.values(value).some((items) => !Array.isArray(items) || items.some((item) => typeof item !== 'string'))) {
+    throw new Error(`${path} is not a map of plugin names to what each was approved for. Delete it, and cmod asks again.`)
+  }
+  return Object.assign(Object.create(null), value) as Record<string, string[]>
 }
 
 function readKeys(keys: unknown): Steps {
@@ -127,8 +240,9 @@ function readKeys(keys: unknown): Steps {
   return { keys: commands }
 }
 
-export function oldestCmodFor(keys: Readonly<Record<string, string>>): string {
-  return Object.keys(keys).length > 0 ? '0.1.12' : '0.0.0'
+export function oldestCmodFor(steps: Steps): string {
+  if (steps.permissions !== undefined) return '0.2.0'
+  return Object.keys(steps.keys ?? {}).length > 0 ? '0.1.12' : '0.0.0'
 }
 
 export function keyWords(keys: Readonly<Record<string, string>> | undefined): string {
@@ -169,7 +283,13 @@ export async function scriptsSha256(steps: Steps, files: { read: ReadFile; list:
     if (scriptFolders.length === 0) throw new Error(`package.json "cmod.${key}" runs "${command}", which names no script file in the mod, so consent cannot cover what it runs. Put the commands in a script, such as ./setup/${key}.sh.`)
     for (const folder of scriptFolders) folders.add(folder)
   }
-  let text = [steps.install ?? '', steps.uninstall ?? '', steps.program ?? '', ...(steps.keys === undefined ? [] : [JSON.stringify(Object.entries(steps.keys).sort())])].join('\0')
+  let text = [
+    steps.install ?? '',
+    steps.uninstall ?? '',
+    steps.program ?? '',
+    ...(steps.keys === undefined ? [] : [JSON.stringify(Object.entries(steps.keys).sort())]),
+    ...(steps.permissions === undefined ? [] : [JSON.stringify([...steps.permissions].sort())]),
+  ].join('\0')
   for (const folder of [...folders].sort()) {
     for (const name of (await files.list(folder)).sort()) {
       const path = `${folder}/${name}`
@@ -189,7 +309,7 @@ export function formatEvent(event: RunnerEvent): string {
     case 'log':
       return `log ${event.text}`
     case 'needs-consent':
-      return `needs-consent ${event.sha256}\t${event.install}\t${event.uninstall}\t${event.keys}`
+      return `needs-consent ${[event.sha256, event.install, event.uninstall, event.keys, ...event.permissions].join('\t')}`
     case 'done':
       return event.version === undefined ? `done ${event.name}` : `done ${event.name} ${event.version}`
     case 'missing':
@@ -203,7 +323,10 @@ export function parseEvent(line: string): RunnerEvent {
   const progress = /^progress (\d+) (\d+)(?: (.*))?$/.exec(line)
   if (progress !== null) return { kind: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
   const consent = /^needs-consent (\S+)\t([^\t]*)\t([^\t]*)(?:\t(.*))?$/.exec(line)
-  if (consent !== null) return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys: consent[4] ?? '' }
+  if (consent !== null) {
+    const [keys = '', ...permissions] = (consent[4] ?? '').split('\t')
+    return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys, permissions: permissions.filter((item) => item !== '') }
+  }
   const done = /^done (\S+)(?: (\S+))?$/.exec(line)
   if (done !== null) return { kind: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
   const missing = /^missing (\S+)$/.exec(line)

package/src/register.ts

@@ -1,5 +1,6 @@
-import type { Args, EngineInterface, EventResult, Frozen, Next, On, ToolCallArgs } from 'claude-code'
+import type { Args, EngineInterface, EventResult, Frozen, Next, On, PluginOptions, ToolCallArgs } from 'claude-code'
 import type { ModDefinition } from './mod.js'
+import type { Options } from './options.js'
 import type { Claude } from './runtime/claude.js'
 import type { RoutedEvent } from './runtime/hooks.js'
 import { createLifecycle, readPlugin, type Lifecycle } from './runtime/lifecycle.js'
@@ -8,6 +9,12 @@ let lifecycle: Lifecycle<object>
 
 let checksPermissions = false
 
+let registered: ModDefinition<object> | undefined
+
+export function registeredMod(): ModDefinition<object> | undefined {
+  return registered
+}
+
 async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.start'>>, passOn: Next<'session.start'>): Promise<EventResult<'session.start'>> {
   const claude: Claude = {
     plugin: { name: $.plugin.name, root: $.plugin.root },
@@ -37,6 +44,7 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
     },
     http: { fetch: (url, init) => $.http.fetch(url, init) },
     settings: { read: (args) => $.settings.read(args) },
+    config: { list: () => $.config.list(), set: (args) => $.config.set(args) },
     store: {
       get: (key) => $.store.get(key),
       set: (key, value) => $.store.set(key, value),
@@ -81,9 +89,10 @@ function routeToMod<N extends RoutedEvent>(_$: EngineInterface, eventInput: Froz
   return lifecycle.route(passOn.event, eventInput, (passed: unknown) => passOn(passed as Args<N>) as Promise<EventResult<N>>)
 }
 
-export function registerMod<State extends object>(addHook: On, definition: ModDefinition<State>): void {
+export function registerMod<State extends object, Declared extends Options>(addHook: On, definition: ModDefinition<State, string, Declared>, options: PluginOptions): void {
   checksPermissions = false
-  lifecycle = createLifecycle(definition, () => checksPermissions)
+  registered = definition as ModDefinition<object>
+  lifecycle = createLifecycle(definition, () => checksPermissions, options)
   addHook('session.start', startMod)
   addHook('classic.SessionStart', routeToMod)
   addHook('classic.SessionEnd', routeToMod)

package/src/runtime/claude.ts

@@ -6,6 +6,7 @@ import type {
   EngineInterface,
   AskOptions,
   CommandSpec,
+  ConfigRow,
   ElementTable,
   FsEntry,
   FsStat,
@@ -64,6 +65,7 @@ export type Claude = {
   }
   readonly http: { fetch(url: string, init?: HttpInit): Promise<HttpResponse> }
   readonly settings: { read(args?: SettingsReadArgs): Promise<Settings> }
+  readonly config: { list(): Promise<ConfigRow[]>; set: EngineInterface['config']['set'] }
   readonly store: {
     get(key: string): Promise<unknown>
     set(key: string, value: unknown): Promise<void>