typeclaw 0.3.1 → 0.5.0

package/src/cli/model.ts

@@ -57,7 +57,8 @@ const setSub = defineCommand({
       process.exit(1)
     }
     done({
-      title: c.green(`Profile "${profile}" set to ${ref}.`),
+      title: c.green(`Profile "${profile}" set.`),
+      details: `${profile} → ${ref}`,
       hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
     })
   },
@@ -97,7 +98,8 @@ const addSub = defineCommand({
       process.exit(1)
     }
     done({
-      title: c.green(`Profile "${args.profile}" → ${ref}.`),
+      title: c.green(`Profile "${args.profile}" added.`),
+      details: `${args.profile} → ${ref}`,
       hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
     })
   },
@@ -155,15 +157,23 @@ const listSub = defineCommand({
     }
 
     const profileWidth = Math.max(7, ...entries.map((e) => e.profile.length))
-    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length))
+    const refDisplay = (e: (typeof entries)[number]): string =>
+      e.refs.length > 1 ? `${e.ref} ${c.dim(`(+${e.refs.length - 1} fallback)`)}` : e.ref
+    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length + (e.refs.length > 1 ? 14 : 0)))
 
     const header = `${'PROFILE'.padEnd(profileWidth)}  ${'REF'.padEnd(refWidth)}  PROVIDER  STATUS`
     console.log(c.dim(header))
     for (const e of entries) {
       const star = e.isDefault ? c.cyan('*') : ' '
       const status = e.credentialStatus === 'available' ? c.green('ok') : c.yellow('missing-credentials')
-      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${e.ref.padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
+      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${refDisplay(e).padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
       console.log(line)
+      if (e.refs.length > 1) {
+        for (let i = 1; i < e.refs.length; i++) {
+          const fb = e.refs[i]!
+          console.log(`${' '.padEnd(profileWidth + 2)}↳ ${c.dim(fb)}`)
+        }
+      }
     }
   },
 })

package/src/cli/oauth-callbacks.ts

@@ -0,0 +1,49 @@
+import { isCancel, log, note, text } from '@clack/prompts'
+
+import type { OAuthCallbacks } from '@/init/oauth-login'
+
+// Shared between `typeclaw init` (src/cli/init.ts) and `typeclaw provider
+// add/set` (src/cli/provider.ts). Both call into the same OAuth runner, so
+// they need to render the same UX: a note() box with the URL + cross-device
+// guidance, a `text()` prompt for the post-callback manual fallback, and a
+// concurrent `onManualCodeInput` prompt for users whose browser is on a
+// different host than the CLI. See src/init/oauth-login.ts for the contract
+// on each callback and why onManualCodeInput is required for cross-device.
+export function buildOAuthCallbacks(providerName: string): OAuthCallbacks {
+  return {
+    onAuth: (url, instructions) => {
+      // Don't put the URL inside note(): clack wraps long lines with the box
+      // border `│` on each wrapped segment, which corrupts the URL when the
+      // user copy-pastes it. Keep instructional text in the box, but print
+      // the URL itself as a bare console.log line that any terminal will
+      // hyperlink intact.
+      const preamble = [
+        `Open this URL in your browser to sign in to ${providerName}.`,
+        '',
+        'If your browser shows "this site can\'t be reached" after you sign in,',
+        'copy the full address from the top of the browser and paste it below.',
+      ]
+      if (instructions) preamble.push('', instructions)
+      note(preamble.join('\n'), 'Browser login')
+      console.log(url)
+      console.log('')
+    },
+    onProgress: (message) => {
+      log.info(message)
+    },
+    onPrompt: async (message, placeholder) => {
+      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
+      if (isCancel(value)) return null
+      return value
+    },
+    onManualCodeInput: async () => {
+      const value = await text({
+        message:
+          'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
+        placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
+      })
+      if (isCancel(value)) throw new Error('Login cancelled by user')
+      return value
+    },
+  }
+}

package/src/cli/plugin-command-help.ts

@@ -0,0 +1,49 @@
+import type { z } from 'zod'
+
+import { describeLeaf } from '@/plugin/zod-introspect'
+
+import type { DiscoveredCommand } from './plugin-commands'
+
+export function renderPluginCommandsSection(commands: readonly DiscoveredCommand[]): string | null {
+  if (commands.length === 0) return null
+  const lines: string[] = ['Plugin commands:']
+  const namePad = Math.max(...commands.map((c) => c.commandName.length))
+  for (const c of commands) {
+    lines.push(`  ${c.commandName.padEnd(namePad)}    ${c.command.description}`)
+  }
+  return lines.join('\n')
+}
+
+export function renderCommandHelp(c: DiscoveredCommand): string {
+  const lines: string[] = []
+  lines.push(`typeclaw ${c.commandName} — ${c.command.description}`)
+  lines.push('')
+  lines.push(`  Plugin: ${c.pluginName}${c.pluginVersion !== undefined ? ` v${c.pluginVersion}` : ''}`)
+  lines.push(`  Surface: ${c.command.surface}`)
+  lines.push('')
+
+  if (c.command.args === undefined) {
+    lines.push('  Options:')
+    lines.push('    (no options)')
+    return lines.join('\n')
+  }
+
+  lines.push('  Options:')
+  for (const line of renderFlags(c.command.args)) {
+    lines.push(`    ${line}`)
+  }
+  return lines.join('\n')
+}
+
+export function renderFlags(schema: z.ZodObject<z.ZodRawShape>): string[] {
+  const out: string[] = []
+  const shape = schema.shape as Record<string, unknown>
+  for (const [field, leaf] of Object.entries(shape)) {
+    const info = describeLeaf(leaf)
+    const required = info.required ? ' (required)' : ''
+    const defaultPart = info.defaultValue !== undefined ? ` (default: ${info.defaultValue})` : ''
+    const descPart = info.description !== undefined ? `  ${info.description}` : ''
+    out.push(`--${field}=<${info.kind}>${descPart}${required}${defaultPart}`)
+  }
+  return out
+}

package/src/cli/plugin-commands-dispatch.ts

@@ -0,0 +1,112 @@
+import { proxyContainerCommand } from './container-command-client'
+import { parseArgs, runHostCommand } from './host-command-runner'
+import { renderCommandHelp } from './plugin-command-help'
+import { discoverCommands } from './plugin-commands'
+
+export type PluginCommandDispatchOutcome =
+  | { kind: 'not-found' }
+  | { kind: 'dispatched'; exitCode: number }
+  | { kind: 'error'; exitCode: number; message: string }
+
+export type DispatchOptions = {
+  name: string
+  rawArgs: readonly string[]
+  cwd: string
+  stdin?: ReadableStream<Uint8Array>
+  stdout?: WritableStream<Uint8Array>
+  stderr?: WritableStream<Uint8Array>
+  signal?: AbortSignal
+}
+
+export async function dispatchPluginCommand(opts: DispatchOptions): Promise<PluginCommandDispatchOutcome> {
+  const discovery = await discoverCommands({ cwd: opts.cwd })
+  const match = discovery.commands.find((c) => c.commandName === opts.name)
+  if (match === undefined) {
+    // Surface plugin load failures so a user typing `typeclaw <cmd>` sees why
+    // their plugin's command isn't listed, instead of a generic "not found".
+    if (discovery.loadErrors.length > 0) {
+      const stderr = opts.stderr ?? defaultStderr()
+      const writer = stderr.getWriter()
+      const encoder = new TextEncoder()
+      for (const e of discovery.loadErrors) {
+        await writer.write(encoder.encode(`[plugin-commands] ${e.entry}: ${e.error}\n`))
+      }
+      writer.releaseLock()
+    }
+    return { kind: 'not-found' }
+  }
+
+  const stdin = opts.stdin ?? defaultStdin()
+  const stdout = opts.stdout ?? defaultStdout()
+  const stderr = opts.stderr ?? defaultStderr()
+  const signal = opts.signal ?? new AbortController().signal
+
+  if (opts.rawArgs.includes('--help') || opts.rawArgs.includes('-h')) {
+    const help = renderCommandHelp(match)
+    const writer = stdout.getWriter()
+    await writer.write(new TextEncoder().encode(`${help}\n`))
+    writer.releaseLock()
+    return { kind: 'dispatched', exitCode: 0 }
+  }
+
+  if (match.command.surface === 'container') {
+    const parsed = parseArgs(match.command, opts.rawArgs)
+    if (!parsed.ok) {
+      return { kind: 'error', exitCode: 2, message: parsed.message }
+    }
+    const containerResult = await proxyContainerCommand({
+      agentDir: discovery.agentDir,
+      commandName: match.commandName,
+      args: parsed.value,
+      stdin,
+      stdout,
+      stderr,
+      abortSignal: signal,
+    })
+    if (!containerResult.ok) {
+      return { kind: 'error', exitCode: containerResult.exitCode, message: containerResult.message }
+    }
+    return { kind: 'dispatched', exitCode: containerResult.exitCode }
+  }
+
+  const result = await runHostCommand({
+    agentDir: discovery.agentDir,
+    pluginName: match.pluginName,
+    pluginVersion: match.pluginVersion,
+    command: match.command,
+    rawArgs: opts.rawArgs,
+    signal,
+    stdin,
+    stdout,
+    stderr,
+  })
+
+  if (!result.ok) {
+    return { kind: 'error', exitCode: result.exitCode, message: result.message }
+  }
+  return { kind: 'dispatched', exitCode: result.exitCode }
+}
+
+function defaultStdin(): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.close()
+    },
+  })
+}
+
+function defaultStdout(): WritableStream<Uint8Array> {
+  return new WritableStream<Uint8Array>({
+    write(chunk) {
+      process.stdout.write(chunk)
+    },
+  })
+}
+
+function defaultStderr(): WritableStream<Uint8Array> {
+  return new WritableStream<Uint8Array>({
+    write(chunk) {
+      process.stderr.write(chunk)
+    },
+  })
+}

package/src/cli/plugin-commands.ts

@@ -0,0 +1,118 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { loadConfigSync } from '@/config/config'
+import {
+  loadPluginEntry,
+  type LoadPluginEntryFn,
+  type PluginCommand,
+  type ResolvedPlugin,
+  validateCommandDeclaration,
+} from '@/plugin'
+
+export type DiscoveredCommand = {
+  pluginName: string
+  pluginVersion: string | undefined
+  commandName: string
+  command: PluginCommand
+}
+
+export type DiscoveryResult = {
+  agentDir: string
+  commands: DiscoveredCommand[]
+  loadErrors: { entry: string; error: string }[]
+}
+
+export type DiscoverOptions = {
+  cwd: string
+  loadEntry?: LoadPluginEntryFn
+}
+
+// Resolves the agent folder by walking up from cwd until typeclaw.json is
+// found. Returns null when no agent folder is reachable (e.g. typeclaw run
+// from a random shell prompt without an agent).
+export function resolveAgentDir(cwd: string): string | null {
+  let cur = cwd
+  while (true) {
+    if (existsSync(join(cur, 'typeclaw.json'))) return cur
+    const parent = join(cur, '..')
+    const resolved = normalize(parent)
+    if (resolved === cur) return null
+    cur = resolved
+  }
+}
+
+function normalize(p: string): string {
+  return p.replace(/\/+$/, '') || '/'
+}
+
+// Discovers plugin commands available to the agent at `cwd`. Loads each
+// plugin module to read its static `defined.commands`, but NEVER invokes
+// the plugin factory — that's a runtime concern reserved for `typeclaw run`.
+//
+// Returns an empty result (no error) when no agent folder is resolvable, so
+// `typeclaw --help` outside any agent prints just built-ins.
+//
+// Side effects: `loadConfigSync(agentDir)` may rewrite `typeclaw.json` and
+// commit the result when the on-disk shape is a legacy schema needing
+// migration. This is by design — running ANY typeclaw subcommand should
+// converge the config on the canonical shape. The migration is idempotent
+// (running twice is a no-op).
+export async function discoverCommands(opts: DiscoverOptions): Promise<DiscoveryResult> {
+  const agentDir = resolveAgentDir(opts.cwd)
+  if (agentDir === null) {
+    return { agentDir: opts.cwd, commands: [], loadErrors: [] }
+  }
+
+  let config
+  try {
+    config = loadConfigSync(agentDir)
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { agentDir, commands: [], loadErrors: [{ entry: '<config>', error: detail }] }
+  }
+
+  const loadEntry = opts.loadEntry ?? loadPluginEntry
+  const commands: DiscoveredCommand[] = []
+  const loadErrors: { entry: string; error: string }[] = []
+  const seenNames = new Set<string>()
+
+  for (const entry of config.plugins) {
+    let resolved: ResolvedPlugin
+    try {
+      resolved = await loadEntry(entry, agentDir)
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err)
+      loadErrors.push({ entry, error: detail })
+      continue
+    }
+
+    const declared = resolved.defined.commands
+    if (declared === undefined) continue
+
+    for (const [commandName, command] of Object.entries(declared)) {
+      try {
+        validateCommandDeclaration(resolved.name, commandName, command)
+      } catch (err) {
+        loadErrors.push({ entry, error: err instanceof Error ? err.message : String(err) })
+        continue
+      }
+      if (seenNames.has(commandName)) {
+        loadErrors.push({
+          entry,
+          error: `command "${commandName}" already declared by another plugin; ignoring`,
+        })
+        continue
+      }
+      seenNames.add(commandName)
+      commands.push({
+        pluginName: resolved.name,
+        pluginVersion: resolved.version,
+        commandName,
+        command,
+      })
+    }
+  }
+
+  return { agentDir, commands, loadErrors }
+}

package/src/cli/provider.ts

@@ -1,4 +1,4 @@
-import { cancel, intro, isCancel, log, note, password, select, text } from '@clack/prompts'
+import { cancel, intro, isCancel, log, password, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
@@ -17,6 +17,7 @@ import {
 import { findAgentDir, isInitialized } from '@/init'
 import { makeOAuthLoginRunner } from '@/init/oauth-login'
 
+import { buildOAuthCallbacks } from './oauth-callbacks'
 import { c, done, errorLine } from './ui'
 
 const addSub = defineCommand({
@@ -366,25 +367,7 @@ async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<
   }
   const modelRef = `${providerId}/${ref}` as const
 
-  const callbacks = {
-    onAuth: (url: string, instructions?: string) => {
-      const preamble = [`Open this URL in your browser to authorize ${provider.name}.`]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message: string) => {
-      log.info(message)
-    },
-    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-  }
-
-  const runner = makeOAuthLoginRunner(callbacks)
+  const runner = makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))
   const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
   if (!result.ok) return { ok: false, reason: result.reason }
   return { ok: true }

package/src/cli/tui.ts

@@ -2,7 +2,8 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { createTui } from '@/tui'
+import { CLI_VERSION } from '@/init/cli-version'
+import { createTui, formatVersionMismatchWarning } from '@/tui'
 
 import { errorLine } from './ui'
 
@@ -25,7 +26,14 @@ export const tui = defineCommand({
   },
   async run({ args }) {
     const url = args.url ?? (await defaultUrl())
-    const tui = createTui({ url, initialPrompt: args.prompt })
+    const tui = createTui({
+      url,
+      ...(args.prompt !== undefined ? { initialPrompt: args.prompt } : {}),
+      expectedVersion: CLI_VERSION,
+      onVersionMismatch: (info) => {
+        process.stderr.write(`${formatVersionMismatchWarning(info)}\n`)
+      },
+    })
     await tui.run()
   },
 })