typeclaw 0.1.0 → 0.1.2

package/src/doctor/index.ts

@@ -0,0 +1,287 @@
+import { findAgentDir } from '@/init'
+import type { DoctorCheckPayload } from '@/shared'
+
+import { buildStaticChecks } from './checks'
+import { commitAutoFixes, type SpawnGit } from './commit'
+import {
+  fetchPluginDoctorChecks as defaultFetchPluginDoctorChecks,
+  fetchPluginDoctorFix as defaultFetchPluginDoctorFix,
+  type PluginBridgeChecksResult,
+  type PluginBridgeFetchChecks,
+  type PluginBridgeFetchFix,
+  type PluginBridgeFixResult,
+} from './plugin-bridge'
+import type {
+  CheckContext,
+  CheckResult,
+  DoctorCheck,
+  DoctorReport,
+  DoctorRunResult,
+  FixAttempt,
+  ReportEntry,
+  ReportSummary,
+  Severity,
+} from './types'
+
+export * from './types'
+export { buildStaticChecks } from './checks'
+export { formatJson, formatReport } from './report'
+export { buildCommitMessage, commitAutoFixes } from './commit'
+export {
+  fetchPluginDoctorChecks,
+  fetchPluginDoctorFix,
+  type PluginBridgeChecksResult,
+  type PluginBridgeFixResult,
+} from './plugin-bridge'
+
+export type RunDoctorOptions = {
+  cwd?: string
+  only?: string[]
+  fix?: boolean
+  staticChecks?: DoctorCheck[]
+  fetchPluginChecks?: PluginBridgeFetchChecks
+  fetchPluginFix?: PluginBridgeFetchFix
+  spawnGit?: SpawnGit
+}
+
+export async function runDoctor(opts: RunDoctorOptions = {}): Promise<DoctorRunResult> {
+  const cwd = opts.cwd ?? findAgentDir(process.cwd()) ?? process.cwd()
+  const hasAgentFolder = findAgentDir(cwd) === cwd
+  const ctx: CheckContext = { cwd, hasAgentFolder }
+
+  const staticChecks = (opts.staticChecks ?? buildStaticChecks()).filter((c) => isAllowed(c, opts.only, c.category))
+  const staticResults = await runStaticChecks(staticChecks, ctx)
+
+  const fetchPluginChecks = opts.fetchPluginChecks ?? defaultFetchPluginDoctorChecks
+  const pluginResults = await collectPluginChecks(fetchPluginChecks, ctx, opts.only)
+
+  const initial = buildReport(ctx, staticResults, pluginResults)
+
+  if (opts.fix !== true || initial.ok) {
+    return { initial }
+  }
+
+  const fetchPluginFix = opts.fetchPluginFix ?? defaultFetchPluginDoctorFix
+  const attempts: FixAttempt[] = []
+  attempts.push(...(await runStaticFixes(staticResults, ctx)))
+  attempts.push(...(await runPluginFixes(pluginResults.entries, fetchPluginFix, ctx)))
+
+  const commit = hasAgentFolder
+    ? await commitAutoFixes({ cwd, attempts, ...(opts.spawnGit !== undefined ? { spawnGit: opts.spawnGit } : {}) })
+    : { kind: 'skipped' as const, reason: 'no agent folder; nothing to commit' }
+
+  const finalStaticResults = await runStaticChecks(staticChecks, ctx)
+  const finalPluginResults = await collectPluginChecks(fetchPluginChecks, ctx, opts.only)
+  const final = buildReport(ctx, finalStaticResults, finalPluginResults)
+
+  return { initial, fixAttempts: attempts, commit, final }
+}
+
+type StaticResult = {
+  check: DoctorCheck
+  result: CheckResult
+}
+
+type PluginCollect = {
+  entries: PluginEntry[]
+  reachability: PluginBridgeChecksResult
+}
+
+type PluginEntry = {
+  payload: DoctorCheckPayload
+}
+
+async function runStaticChecks(checks: DoctorCheck[], ctx: CheckContext): Promise<StaticResult[]> {
+  const out: StaticResult[] = []
+  for (const check of checks) {
+    if (check.applies && !check.applies(ctx)) {
+      out.push({ check, result: { status: 'skipped', message: 'not applicable' } })
+      continue
+    }
+    try {
+      out.push({ check, result: await check.run(ctx) })
+    } catch (err) {
+      out.push({ check, result: { status: 'error', message: err instanceof Error ? err.message : String(err) } })
+    }
+  }
+  return out
+}
+
+async function collectPluginChecks(
+  fetcher: PluginBridgeFetchChecks,
+  ctx: CheckContext,
+  only: string[] | undefined,
+): Promise<PluginCollect> {
+  if (!ctx.hasAgentFolder) {
+    return { entries: [], reachability: { kind: 'unreachable', reason: 'no agent folder' } }
+  }
+  const reachability = await fetcher({ cwd: ctx.cwd })
+  if (reachability.kind !== 'ok') return { entries: [], reachability }
+  const filtered = reachability.checks.filter((c) => isAllowed({ category: c.category }, only, c.category))
+  return { entries: filtered.map((payload) => ({ payload })), reachability }
+}
+
+function buildReport(ctx: CheckContext, staticResults: StaticResult[], plugin: PluginCollect): DoctorReport {
+  const entries: ReportEntry[] = []
+  for (const { check, result } of staticResults) {
+    const entry: ReportEntry = {
+      name: check.name,
+      category: check.category,
+      description: check.description,
+      source: 'static',
+      status: result.status,
+      message: result.message,
+    }
+    if (result.details !== undefined) entry.details = result.details
+    if (result.fix !== undefined) {
+      entry.fix = { description: result.fix.description, canAutoFix: result.fix.autoFix !== undefined }
+    }
+    entries.push(entry)
+  }
+
+  if (ctx.hasAgentFolder && plugin.reachability.kind !== 'ok') {
+    entries.push(reachabilityNote(plugin.reachability))
+  }
+
+  for (const { payload } of plugin.entries) {
+    const entry: ReportEntry = {
+      name: payload.checkName,
+      category: payload.category,
+      description: payload.description,
+      source: 'plugin',
+      pluginName: payload.pluginName,
+      status: payload.status,
+      message: payload.message,
+    }
+    if (payload.details !== undefined) entry.details = payload.details
+    if (payload.fix !== undefined) {
+      entry.fix = { description: payload.fix.description, canAutoFix: payload.fix.hasApply }
+    }
+    entries.push(entry)
+  }
+
+  const summary = summarize(entries)
+  const ok = summary.error === 0 && summary.warning === 0
+  return { cwd: ctx.cwd, hasAgentFolder: ctx.hasAgentFolder, entries, summary, ok }
+}
+
+function reachabilityNote(reach: PluginBridgeChecksResult): ReportEntry {
+  const message =
+    reach.kind === 'unreachable'
+      ? `plugin checks deferred: container not reachable (${reach.reason})`
+      : reach.kind === 'timeout'
+        ? 'plugin checks deferred: container did not respond in time'
+        : `plugin checks deferred: ${reach.kind === 'error' ? reach.reason : 'unknown reason'}`
+  return {
+    name: 'plugin-checks-deferred',
+    category: 'container',
+    description: 'plugin doctor checks require a running container',
+    source: 'static',
+    status: 'info',
+    message,
+    details: ['Run `typeclaw start` then re-run `typeclaw doctor` to include plugin checks.'],
+  }
+}
+
+function summarize(entries: ReportEntry[]): ReportSummary {
+  const summary: ReportSummary = { ok: 0, warning: 0, error: 0, info: 0, skipped: 0 }
+  for (const e of entries) {
+    summary[e.status as keyof ReportSummary]++
+  }
+  return summary
+}
+
+function isAllowed(target: { category: string }, only: string[] | undefined, category: string): boolean {
+  if (!only || only.length === 0) return true
+  if (only.includes(target.category) || only.includes(category)) return true
+  if (category.startsWith('plugin:')) return only.includes('plugin') || only.includes(category)
+  return false
+}
+
+async function runStaticFixes(results: StaticResult[], ctx: CheckContext): Promise<FixAttempt[]> {
+  const attempts: FixAttempt[] = []
+  for (const { check, result } of results) {
+    if (result.status === 'ok' || result.status === 'skipped' || result.status === 'info') continue
+    const apply = result.fix?.autoFix
+    if (!apply) continue
+    try {
+      const fix = await apply(ctx)
+      attempts.push({
+        name: check.name,
+        source: 'static',
+        ok: true,
+        summary: fix.summary,
+        changedPaths: fix.changedPaths,
+      })
+    } catch (err) {
+      attempts.push({
+        name: check.name,
+        source: 'static',
+        ok: false,
+        reason: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+  return attempts
+}
+
+async function runPluginFixes(
+  entries: PluginEntry[],
+  fetchFix: PluginBridgeFetchFix,
+  ctx: CheckContext,
+): Promise<FixAttempt[]> {
+  const attempts: FixAttempt[] = []
+  for (const { payload } of entries) {
+    if (payload.status === 'ok') continue
+    if (payload.fix === undefined || payload.fix.hasApply !== true) continue
+    const result = await fetchFix({ cwd: ctx.cwd, checkId: payload.id })
+    if (result.kind !== 'ok') {
+      attempts.push({
+        name: `${payload.pluginName}.${payload.checkName}`,
+        source: 'plugin',
+        ok: false,
+        reason:
+          result.kind === 'unreachable'
+            ? result.reason
+            : result.kind === 'timeout'
+              ? 'timeout'
+              : (result as { reason: string }).reason,
+      })
+      continue
+    }
+    if (result.payload.ok) {
+      const accepted = sanitizeChangedPathsForHost(ctx.cwd, result.payload.changedPaths)
+      attempts.push({
+        name: `${payload.pluginName}.${payload.checkName}`,
+        source: 'plugin',
+        ok: true,
+        summary: result.payload.summary,
+        changedPaths: accepted,
+      })
+    } else {
+      attempts.push({
+        name: `${payload.pluginName}.${payload.checkName}`,
+        source: 'plugin',
+        ok: false,
+        reason: result.payload.error,
+      })
+    }
+  }
+  return attempts
+}
+
+// Defense in depth: even though the container-side runner sanitizes
+// changedPaths, re-validate on the host before `git add` so a future protocol
+// change cannot bypass the security boundary by accident.
+function sanitizeChangedPathsForHost(_cwd: string, paths: readonly string[]): string[] {
+  const out: string[] = []
+  for (const raw of paths) {
+    if (typeof raw !== 'string' || raw.length === 0) continue
+    if (raw.startsWith('/') || raw.includes('\\')) continue
+    if (raw.split('/').includes('..')) continue
+    out.push(raw)
+  }
+  return out
+}
+
+export type { Severity }

package/src/doctor/plugin-bridge.ts

@@ -0,0 +1,147 @@
+import { resolveHostPort } from '@/container'
+import type { ClientMessage, DoctorCheckPayload, DoctorFixPayload, ServerMessage } from '@/shared'
+
+export type PluginBridgeOptions = {
+  cwd: string
+  url?: string
+  timeoutMs?: number
+}
+
+export type PluginBridgeFetchChecks = (opts: PluginBridgeOptions) => Promise<PluginBridgeChecksResult>
+export type PluginBridgeFetchFix = (opts: PluginBridgeOptions & { checkId: string }) => Promise<PluginBridgeFixResult>
+
+export type PluginBridgeChecksResult =
+  | { kind: 'ok'; checks: DoctorCheckPayload[] }
+  | { kind: 'unreachable'; reason: string }
+  | { kind: 'timeout' }
+  | { kind: 'error'; reason: string }
+
+export type PluginBridgeFixResult =
+  | { kind: 'ok'; payload: DoctorFixPayload }
+  | { kind: 'unreachable'; reason: string }
+  | { kind: 'timeout' }
+  | { kind: 'error'; reason: string }
+
+const DEFAULT_TIMEOUT_MS = 15_000
+
+export async function fetchPluginDoctorChecks(opts: PluginBridgeOptions): Promise<PluginBridgeChecksResult> {
+  const reach = await dial(opts)
+  if (reach.kind !== 'ok') return reach
+  const { ws, timeoutMs } = reach
+  const requestId = randomId()
+  try {
+    return await withRequest<PluginBridgeChecksResult>(
+      ws,
+      timeoutMs,
+      requestId,
+      (msg) => {
+        if (msg.type === 'doctor_result' && msg.requestId === requestId) {
+          return { kind: 'ok', checks: msg.checks }
+        }
+        return null
+      },
+      { type: 'doctor', requestId },
+    )
+  } finally {
+    ws.close()
+  }
+}
+
+export async function fetchPluginDoctorFix(
+  opts: PluginBridgeOptions & { checkId: string },
+): Promise<PluginBridgeFixResult> {
+  const reach = await dial(opts)
+  if (reach.kind !== 'ok') return reach
+  const { ws, timeoutMs } = reach
+  const requestId = randomId()
+  try {
+    return await withRequest<PluginBridgeFixResult>(
+      ws,
+      timeoutMs,
+      requestId,
+      (msg) => {
+        if (msg.type === 'doctor_fix_result' && msg.requestId === requestId) {
+          return { kind: 'ok', payload: msg.result }
+        }
+        return null
+      },
+      { type: 'doctor_fix', requestId, checkId: opts.checkId },
+    )
+  } finally {
+    ws.close()
+  }
+}
+
+type DialResult = { kind: 'ok'; ws: WebSocket; timeoutMs: number } | { kind: 'unreachable'; reason: string }
+
+async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  let url = opts.url
+  if (url === undefined) {
+    try {
+      const port = await resolveHostPort({ cwd: opts.cwd })
+      url = `ws://localhost:${port}`
+    } catch (err) {
+      return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
+    }
+  }
+  const ws = new WebSocket(url)
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => {
+        ws.removeEventListener('open', onOpen)
+        ws.removeEventListener('error', onError)
+      }
+      const onOpen = () => {
+        cleanup()
+        resolve()
+      }
+      const onError = (err: unknown) => {
+        cleanup()
+        reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+      }
+      ws.addEventListener('open', onOpen, { once: true })
+      ws.addEventListener('error', onError, { once: true })
+    })
+  } catch (err) {
+    return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
+  }
+  return { kind: 'ok', ws, timeoutMs }
+}
+
+async function withRequest<R extends { kind: string }>(
+  ws: WebSocket,
+  timeoutMs: number,
+  _requestId: string,
+  match: (msg: ServerMessage) => R | null,
+  outgoing: ClientMessage,
+): Promise<R | { kind: 'timeout' } | { kind: 'error'; reason: string }> {
+  ws.send(JSON.stringify(outgoing))
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      ws.removeEventListener('message', onMessage)
+      resolve({ kind: 'timeout' })
+    }, timeoutMs)
+    const onMessage = (event: MessageEvent) => {
+      let msg: ServerMessage
+      try {
+        msg = JSON.parse(String(event.data)) as ServerMessage
+      } catch (err) {
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve({ kind: 'error', reason: err instanceof Error ? err.message : String(err) })
+        return
+      }
+      const result = match(msg)
+      if (result === null) return
+      clearTimeout(timer)
+      ws.removeEventListener('message', onMessage)
+      resolve(result)
+    }
+    ws.addEventListener('message', onMessage)
+  })
+}
+
+function randomId(): string {
+  return `doc-${crypto.randomUUID()}`
+}

package/src/doctor/report.ts

@@ -0,0 +1,142 @@
+import { styleText } from 'node:util'
+
+import type { DoctorReport, ReportEntry, Severity } from './types'
+
+export type FormatOptions = { useColor?: boolean; verbose?: boolean }
+
+type ColorFn = (s: string) => string
+type Palette = {
+  bold: ColorFn
+  dim: ColorFn
+  green: ColorFn
+  yellow: ColorFn
+  red: ColorFn
+  cyan: ColorFn
+  gray: ColorFn
+}
+
+const identity: ColorFn = (s) => s
+const NO_PALETTE: Palette = {
+  bold: identity,
+  dim: identity,
+  green: identity,
+  yellow: identity,
+  red: identity,
+  cyan: identity,
+  gray: identity,
+}
+
+const COLOR_PALETTE: Palette = {
+  bold: (s) => styleText('bold', s),
+  dim: (s) => styleText('dim', s),
+  green: (s) => styleText('green', s),
+  yellow: (s) => styleText('yellow', s),
+  red: (s) => styleText('red', s),
+  cyan: (s) => styleText('cyan', s),
+  gray: (s) => styleText('gray', s),
+}
+
+export function formatReport(report: DoctorReport, opts: FormatOptions = {}): string {
+  const verbose = opts.verbose ?? false
+  const useColor = opts.useColor ?? false
+  const p: Palette = useColor ? COLOR_PALETTE : NO_PALETTE
+
+  const lines: string[] = []
+  lines.push(`${p.bold('typeclaw doctor')}  ${p.dim(report.cwd)}`)
+  lines.push('')
+
+  const byCategory = groupByCategory(report.entries)
+  for (const [category, entries] of byCategory) {
+    const worst = worstSeverity(entries.map((e) => e.status))
+    lines.push(`${categoryBox(worst, p)} ${p.bold(category)}`)
+    for (const entry of entries) {
+      lines.push(`    ${markerForEntry(entry, p)} ${entry.message}${describeOriginSuffix(entry, p)}`)
+      if (verbose) {
+        for (const detail of entry.details ?? []) {
+          lines.push(`      ${p.dim('•')} ${p.dim(detail)}`)
+        }
+      }
+      if (entry.fix !== undefined) {
+        const tag = entry.fix.canAutoFix ? p.cyan('→ Fix (auto):') : p.cyan('→ Fix:')
+        lines.push(`      ${tag} ${entry.fix.description}`)
+      }
+    }
+    lines.push('')
+  }
+
+  lines.push(summaryLine(report, p))
+  return lines.join('\n').replace(/\n+$/, '\n').trimEnd()
+}
+
+export function formatJson(report: DoctorReport): string {
+  return JSON.stringify(report, null, 2)
+}
+
+function groupByCategory(entries: ReportEntry[]): Map<string, ReportEntry[]> {
+  const m = new Map<string, ReportEntry[]>()
+  for (const entry of entries) {
+    const arr = m.get(entry.category)
+    if (arr) arr.push(entry)
+    else m.set(entry.category, [entry])
+  }
+  return m
+}
+
+function worstSeverity(statuses: Severity[]): Severity {
+  if (statuses.some((s) => s === 'error')) return 'error'
+  if (statuses.some((s) => s === 'warning')) return 'warning'
+  if (statuses.some((s) => s === 'info')) return 'info'
+  if (statuses.every((s) => s === 'skipped')) return 'skipped'
+  return 'ok'
+}
+
+function categoryBox(status: Severity, p: Palette): string {
+  switch (status) {
+    case 'ok':
+      return p.green('[✓]')
+    case 'warning':
+      return p.yellow('[!]')
+    case 'error':
+      return p.red('[✗]')
+    case 'skipped':
+      return p.dim('[-]')
+    case 'info':
+      return p.cyan('[i]')
+  }
+}
+
+function markerForEntry(entry: ReportEntry, p: Palette): string {
+  switch (entry.status) {
+    case 'ok':
+      return p.green('✓')
+    case 'warning':
+      return p.yellow('!')
+    case 'error':
+      return p.red('✗')
+    case 'skipped':
+      return p.dim('-')
+    case 'info':
+      return p.cyan('i')
+  }
+}
+
+function describeOriginSuffix(entry: ReportEntry, p: Palette): string {
+  const name = entry.pluginName ? `${entry.name} [plugin:${entry.pluginName}]` : entry.name
+  return ` ${p.dim(`(${name})`)}`
+}
+
+function summaryLine(report: DoctorReport, p: Palette): string {
+  const { ok, warning, error, info, skipped } = report.summary
+  const parts: string[] = []
+  parts.push(`${ok} ok`)
+  if (warning > 0) parts.push(p.yellow(`${warning} warning${warning === 1 ? '' : 's'}`))
+  if (error > 0) parts.push(p.red(`${error} error${error === 1 ? '' : 's'}`))
+  if (info > 0) parts.push(p.dim(`${info} info`))
+  if (skipped > 0) parts.push(p.dim(`${skipped} skipped`))
+
+  const headLine = `${p.bold('Summary:')} ${parts.join(', ')}`
+  if (report.ok) {
+    return `${p.green('●')} ${headLine}`
+  }
+  return `${p.red('●')} ${headLine}`
+}

package/src/doctor/types.ts

@@ -0,0 +1,87 @@
+export type Severity = 'ok' | 'warning' | 'error' | 'info' | 'skipped'
+
+export type DoctorCategory =
+  | 'docker'
+  | 'agent-folder'
+  | 'config'
+  | 'mounts'
+  | 'hostd'
+  | 'ports'
+  | 'container'
+  | 'runtime'
+  | 'compose'
+  | string
+
+export type FixResult = {
+  summary: string
+  changedPaths: string[]
+}
+
+export type FixSuggestion = {
+  description: string
+  autoFix?: (ctx: CheckContext) => Promise<FixResult>
+}
+
+export type CheckResult = {
+  status: Severity
+  message: string
+  details?: string[]
+  fix?: FixSuggestion
+}
+
+export type CheckContext = {
+  cwd: string
+  hasAgentFolder: boolean
+}
+
+export type DoctorCheck = {
+  name: string
+  category: DoctorCategory
+  description: string
+  applies?: (ctx: CheckContext) => boolean
+  run: (ctx: CheckContext) => Promise<CheckResult>
+}
+
+export type ReportEntry = {
+  name: string
+  category: DoctorCategory
+  description: string
+  source: 'static' | 'plugin'
+  pluginName?: string
+  status: Severity
+  message: string
+  details?: string[]
+  fix?: { description: string; canAutoFix: boolean }
+}
+
+export type ReportSummary = {
+  ok: number
+  warning: number
+  error: number
+  info: number
+  skipped: number
+}
+
+export type DoctorReport = {
+  cwd: string
+  hasAgentFolder: boolean
+  entries: ReportEntry[]
+  summary: ReportSummary
+  ok: boolean
+}
+
+export type FixAttempt =
+  | { name: string; source: 'static' | 'plugin'; ok: true; summary: string; changedPaths: string[] }
+  | { name: string; source: 'static' | 'plugin'; ok: false; reason: string }
+
+export type CommitOutcome =
+  | { kind: 'committed'; commitSha: string; pathsStaged: string[] }
+  | { kind: 'skipped'; reason: string }
+  | { kind: 'failed'; reason: string }
+
+export type DoctorRunResult = {
+  initial: DoctorReport
+  fixAttempts?: FixAttempt[]
+  commit?: CommitOutcome
+  final?: DoctorReport
+}