@cmodjs/core 0.3.0 → 1.5.0

package/src/runtime/metadata.ts

@@ -1,8 +1,10 @@
 import type { FileMatch, Metadata } from '../mod.js'
 import { formatOf, MetadataError, readMetadata, sidecarSuffix, writeMetadata, type MetadataFormat } from '../utils/metadata.js'
+import { expandHome, homePrefix, ifMissing, isMissing } from '../utils/paths.js'
 import { messageOf } from '../utils/text.js'
 import { picomatch, resolve } from '../vendor.js'
 import type { Claude } from './claude.js'
+import type { Failure } from './toaster.js'
 
 export type Places = {
   readonly home: string | undefined
@@ -27,14 +29,27 @@ const ownKey = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/
 export function resolvedPath(path: string, places: Places): string {
   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)}`)
+  const prefix = homePrefix.exec(path)?.[0]
+  if (prefix !== undefined) {
+    if (places.home === undefined) throw new Error(`${path} starts with ${prefix}, and HOME is not set. Start Claude Code with HOME set.`)
+    return resolve(expandHome(path, places.home, places.configRoot))
   }
   return path.startsWith('/') ? resolve(path) : resolve(places.projectRoot(), path)
 }
 
-export function createModFiles({ name, claude, places, checkWrite }: { readonly name: string; readonly claude: Claude; readonly places: Places; readonly checkWrite: (path: string) => Promise<void> }): ModFiles {
+export function createModFiles({
+  name,
+  claude,
+  places,
+  checkWrite,
+  report,
+}: {
+  readonly name: string
+  readonly claude: Claude
+  readonly places: Places
+  readonly checkWrite: (path: string) => Promise<void>
+  readonly report: (failure: Failure) => void
+}): ModFiles {
   const prefix = `${name}.`
   const cache = new Map<string, { readonly signature: string; readonly read: Read }>()
   const logged = new Set<string>()
@@ -48,12 +63,20 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
     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
+    const holder = format.type === 'sidecar' ? `${realPath}${sidecarSuffix}` : realPath
+    const sidecar = format.type === 'sidecar' ? await claude.fs.stat(holder).catch(ifMissing(undefined)) : undefined
     return { realPath, format, holder, signature: `${stat.mtimeMs}:${stat.size}:${sidecar?.kind === 'file' ? `${sidecar.mtimeMs}:${sidecar.size}` : ''}` }
   }
 
-  const textOf = async (holder: string): Promise<string> => ((await claude.fs.stat(holder).catch(() => undefined))?.kind === 'file' ? claude.fs.read(holder) : '')
+  const textOf = async (holder: string): Promise<string> => ((await claude.fs.stat(holder).catch(ifMissing(undefined)))?.kind === 'file' ? claude.fs.read(holder) : '')
+
+  const skipped = <Value>(path: string, value: Value) => (error: unknown): Value => {
+    if (isMissing(error)) return value
+    const reason = `${name}: fs.find skipped ${path}: ${messageOf(error)}`
+    if (!logged.has(reason)) claude.ui.log(reason, { to: 'debug' })
+    logged.add(reason)
+    return value
+  }
 
   const readEntry = async (path: string): Promise<Read> => {
     const located = await locate(path)
@@ -67,7 +90,7 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
       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}`)
+      if (!logged.has(failure)) report({ id: `metadata:${located.holder}`, message: `Skips the metadata of ${located.holder}`, description: failure })
       logged.add(failure)
     }
     cache.set(path, { signature: located.signature, read })
@@ -77,21 +100,21 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
   const matchesOf = async (pattern: string): Promise<string[]> => {
     const absolute = resolvedPath(pattern, places)
     const scanned = picomatch.scan(absolute)
-    if (!scanned.isGlob) return (await claude.fs.stat(absolute).catch(() => undefined))?.kind === 'file' ? [absolute] : []
+    if (!scanned.isGlob) return (await claude.fs.stat(absolute).catch(skipped(absolute, 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: string[] = []
     const visited = new Set<string>()
     const walk = async (folder: string, depth: number): Promise<void> => {
-      const real = (await claude.fs.stat(folder, { resolve: true }).catch(() => undefined))?.realPath ?? folder
+      const real = (await claude.fs.stat(folder, { resolve: true }).catch(skipped(folder, undefined)))?.realPath ?? folder
       if (visited.has(real)) return
       visited.add(real)
-      const entries = await claude.fs.list(folder).catch(() => [])
+      const entries = await claude.fs.list(folder).catch(skipped(folder, []))
       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
+          const kind = entry.isLink === true ? (await claude.fs.stat(path).catch(skipped(path, 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
@@ -100,7 +123,7 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
       )
     }
     const base = scanned.base === '' ? '/' : scanned.base
-    if ((await claude.fs.stat(base).catch(() => undefined))?.kind === 'dir') await walk(base, 0)
+    if ((await claude.fs.stat(base).catch(skipped(base, undefined)))?.kind === 'dir') await walk(base, 0)
     return found
   }
 
@@ -111,7 +134,7 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
       const kept = paths.filter((path) => !(path.endsWith(sidecarSuffix) && paths.includes(path.slice(0, -sidecarSuffix.length))))
       return Promise.all(
         kept.map(async (path): Promise<FileMatch> => {
-          const read = await readEntry(path)
+          const read = await readEntry(path).catch((error: unknown): Read => ({ metadata: {}, error: `${path} ${messageOf(error)}` }))
           return { path, ...(read.name === undefined ? {} : { name: read.name }), metadata: own(read.metadata), ...(read.error === undefined ? {} : { error: read.error }) }
         }),
       )

package/src/runtime/options.ts

@@ -3,6 +3,7 @@ import { fitsOption, isUnset, type Option, type Options } from '../options.js'
 import { configFolders } from '../records.js'
 import { listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
+import type { Failure } from './toaster.js'
 
 export class MissingOptions extends Error {
   readonly keys: readonly string[]
@@ -21,7 +22,21 @@ export type ModOptions = {
   load(root: string): Promise<void>
 }
 
-export function createOptions({ name, declared, fromClaude, claude, changed }: { readonly name: string; readonly declared: Options; readonly fromClaude: PluginOptions; readonly claude: Claude; readonly changed: () => void }): ModOptions {
+export function createOptions({
+  name,
+  declared,
+  fromClaude,
+  claude,
+  report,
+  changed,
+}: {
+  readonly name: string
+  readonly declared: Options
+  readonly fromClaude: PluginOptions
+  readonly claude: Claude
+  readonly report: (failure: Failure) => void
+  readonly changed: () => void
+}): ModOptions {
   let values: Readonly<Record<string, unknown>> = merged(declared, fromClaude, {}, new Set())
   let locked: Set<string> | undefined
   let loadedRoot: string | undefined
@@ -41,7 +56,7 @@ export function createOptions({ name, declared, fromClaude, claude, changed }: {
     if (project === undefined) return {}
     const path = `${project.folder}/options.json`
     if (!(await claude.fs.exists(path))) return {}
-    const ignore = (reason: string) => claude.ui.log(`${path} ${reason}`)
+    const ignore = (reason: string) => report({ id: `options:${path} ${reason}`, message: `Ignores part of ${path}`, description: `${path} ${reason}` })
     let file: unknown
     try {
       file = JSON.parse(await claude.fs.read(path))
@@ -57,7 +72,7 @@ export function createOptions({ name, declared, fromClaude, claude, changed }: {
     for (const [key, value] of Object.entries(file)) {
       const option = declared[key]
       if (option === undefined) ignore(`sets ${key}, which ${name} does not declare. ${Object.keys(declared).length === 0 ? 'Remove it.' : `Remove it, or use one of: ${Object.keys(declared).join(', ')}.`}`)
-      else if (option.kind === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`)
+      else if (option.type === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`)
       else {
         const misfit = fitsOption(option, value)
         if (misfit === undefined) kept[key] = value
@@ -98,5 +113,5 @@ function valueOf(key: string, option: Option, own: unknown, project: Readonly<Re
   if (locked.has(key)) return own
   if (Object.hasOwn(project, key)) return project[key]
   if (!isUnset(own) && fitsOption(option, own) === undefined) return Array.isArray(own) ? Object.freeze([...own]) : own
-  return option.default ?? (option.kind === 'list' ? Object.freeze([]) : option.kind === 'number' ? undefined : '')
+  return option.default ?? (option.type === 'list' ? Object.freeze([]) : option.type === 'number' ? undefined : '')
 }

package/src/runtime/programs.ts

@@ -1,8 +1,47 @@
+import type { HookStream, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
 import { storeFolder } from '../records.js'
+import { ifMissing } from '../utils/paths.js'
+import { formatExit } from '../utils/text.js'
 import type { Claude } from './claude.js'
 
 export type Programs = { readonly claude: Claude; refresh(): Promise<void> }
 
+export function lastLineOf(text: string): string | undefined {
+  const trimmed = text.trim()
+  return trimmed === '' ? undefined : trimmed.slice(trimmed.lastIndexOf('\n') + 1).trim()
+}
+
+export function cmodError(stderr: string, command: string | undefined): string {
+  const line = lastLineOf(stderr) ?? ''
+  const prefix = `cmod ${command}: `
+  return line.startsWith(prefix) ? line.slice(prefix.length) : line
+}
+
+export async function readLines(stream: HookStream<ProcessSpawnChunk, ProcessSpawnResult>, onLine: (text: string) => void): Promise<{ code: number | null; lastError: string }> {
+  let pending = ''
+  let lastError = ''
+  let piece = await stream.next()
+  while (piece.done !== true) {
+    if (piece.value.stream === 'stderr') {
+      lastError = lastLineOf(piece.value.text) ?? lastError
+    } else {
+      const lines = `${pending}${piece.value.text}`.split('\n')
+      pending = lines.pop() ?? ''
+      for (const text of lines) onLine(text)
+    }
+    piece = await stream.next()
+  }
+  if (pending !== '') onLine(pending)
+  return { code: piece.value.code, lastError }
+}
+
+export async function runCmod(claude: Claude, args: readonly string[], session: string): Promise<string> {
+  const lines: string[] = []
+  const { code, lastError } = await readLines(claude.process.spawn({ argv: ['cmod', ...args], env: { CLAUDE_CODE_SESSION_ID: session } }), (line) => void lines.push(line))
+  if (code !== 0) throw new Error(cmodError(lastError, args[0]) || `cmod ${args.slice(0, 2).join(' ')} ${formatExit(code, '')}.`)
+  return lines.join('\n')
+}
+
 export function locatingPrograms(claude: Claude): Programs {
   let folder: string | undefined
   let names: ReadonlySet<string> = new Set()
@@ -21,7 +60,7 @@ export function locatingPrograms(claude: Claude): Programs {
     async refresh() {
       const [home, dataHome] = await Promise.all([claude.env.home(), claude.env.dataHome()])
       const programs = `${storeFolder({ HOME: home, XDG_DATA_HOME: dataHome })}/programs`
-      names = new Set((await claude.fs.list(programs).catch(() => [])).map((entry) => entry.name))
+      names = new Set((await claude.fs.list(programs).catch(ifMissing([]))).map((entry) => entry.name))
       folder = programs
     },
   }

package/src/runtime/router.ts

@@ -1,4 +1,5 @@
 import type { Args, EventResult, Frozen } from 'claude-code'
+import type { Disposable } from '../mod.js'
 import type { RoutedEvent } from './hooks.js'
 
 export type RouterNext<N extends RoutedEvent> = (e: Frozen<Args<N>>) => Promise<EventResult<N>>
@@ -6,7 +7,7 @@ export type RouterNext<N extends RoutedEvent> = (e: Frozen<Args<N>>) => Promise<
 export type RoutedHook<N extends RoutedEvent> = (e: Frozen<Args<N>>, next: RouterNext<N>) => EventResult<N> | Promise<EventResult<N>>
 
 export type Router = {
-  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
+  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): Disposable
   has(event: RoutedEvent): boolean
   dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
 }
@@ -18,9 +19,15 @@ export function createRouter(): Router {
 
   return {
     add(event, hook) {
-      const chain = hooks.get(event) ?? []
-      chain.push(hook as unknown as ErasedHook)
-      hooks.set(event, chain)
+      const erased = hook as unknown as ErasedHook
+      hooks.set(event, [...(hooks.get(event) ?? []), erased])
+      return {
+        dispose() {
+          const chain = (hooks.get(event) ?? []).filter((each) => each !== erased)
+          if (chain.length === 0) hooks.delete(event)
+          else hooks.set(event, chain)
+        },
+      }
     },
     has: (event) => hooks.has(event),
     dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>> {