dsh-plugin-container 0.0.0-stage → 0.3.0

package/src/client/tabs/overview.jsx

@@ -0,0 +1,266 @@
+/** Docker overview: runtime, counts, recent containers, disk, quick commands. */
+import { useMemo } from 'react'
+
+import {
+  Button,
+  Chips,
+  EmptyState,
+  ErrorState,
+  LoadingSkeleton,
+  Spinner,
+  StateLabel,
+  displayValue,
+  formatBytes,
+  formatTime,
+} from '../components.jsx'
+import { useDockerList } from '../hooks.js'
+import { IconBox, IconImage, IconPlay, IconRestart, IconStop, IconTerminal } from '../icons.jsx'
+
+function Stat({ label, value, detail }) {
+  return (
+    <div className="dsh-docker-stat">
+      <div className="dsh-docker-stat-label">{label}</div>
+      <div className="dsh-docker-stat-value">{value}</div>
+      {detail !== undefined && <div className="dsh-docker-stat-detail">{detail}</div>}
+    </div>
+  )
+}
+
+function RuntimeCard({ t, provider, status, imageCount, volumeCount, networkCount, onRuntime, busy }) {
+  const runtime = status.runtime
+  const details = runtime?.details ?? {}
+  const isApple = provider === 'apple-container'
+  const rows = (isApple ? [
+    [t('providerLabel'), t('providerApple')],
+    [t('systemService'), details.status],
+    [t('client'), status.client?.version],
+    [t('server'), status.server?.version],
+    [t('containers'), status.server?.containers],
+    [t('images'), imageCount],
+    [t('volumes'), volumeCount],
+    [t('networks'), networkCount],
+    [t('cpus'), status.server?.ncpu !== undefined ? String(status.server.ncpu) : undefined],
+    [t('memory'), status.server?.memTotal !== undefined ? formatBytes(status.server.memTotal) : undefined],
+  ] : [
+    [t('endpoint'), status.context?.endpoint],
+    [t('profile'), runtime?.profile],
+    [t('driver'), runtime?.driver ?? details.driver],
+    [t('arch'), runtime?.arch ?? details.arch],
+    [t('mountType'), runtime?.mountType ?? details.mountType],
+    [t('kubernetes'), runtime?.kubernetes === undefined ? undefined : runtime.kubernetes ? t('yes') : t('no')],
+    [t('cpus'), runtime?.cpus !== undefined ? String(runtime.cpus) : undefined],
+    [t('memory'), runtime?.memory !== undefined ? formatBytes(runtime.memory) : undefined],
+    [t('disk'), runtime?.disk !== undefined ? formatBytes(runtime.disk) : undefined],
+  ]).filter(([, value]) => value !== undefined && value !== null && value !== '')
+  return (
+    <section className="dsh-docker-card">
+      <div className="dsh-docker-card-head">
+        <div>
+          <h2 className="dsh-docker-card-title">{t('runtime')}</h2>
+          <p className="dsh-docker-card-sub">{runtime?.kind ?? ''}</p>
+        </div>
+        <span className="dsh-docker-status" data-state={runtime?.running ? 'running' : 'stopped'}>
+          <span className="dsh-docker-dot" />
+          {runtime?.running ? t('statusRunning') : t('statusStopped')}
+        </span>
+      </div>
+      <div className="dsh-docker-card-body">
+        <div className="dsh-docker-runtime-head">
+          <span className="dsh-docker-mark" style={{ width: 34, height: 34 }}><IconBox size={19} /></span>
+          <div>
+            <div className="dsh-docker-runtime-name">{runtime?.label ?? t('unknownRuntime')}</div>
+            <div className="dsh-docker-muted">{isApple ? 'container · per-container VM' : runtime?.kind === 'colima' ? `colima · profile ${runtime.profile ?? 'default'}` : (runtime?.kind ?? '')}</div>
+          </div>
+        </div>
+        <div className="dsh-docker-kv">
+          {rows.map(([key, value]) => (
+            <div key={key} className="dsh-docker-kv-row" style={{ display: 'contents' }}>
+              <div className="dsh-docker-kv-key">{key}</div>
+              <div className="dsh-docker-kv-value">{displayValue(value)}</div>
+            </div>
+          ))}
+        </div>
+        <div className="dsh-docker-middle" style={{ marginTop: 14 }}>
+          {runtime?.canStart === true && (
+            <Button size="sm" variant="primary" onClick={() => onRuntime('start')} disabled={busy}>
+              {busy ? <Spinner size={13} /> : <IconPlay size={13} />} {t('start')}
+            </Button>
+          )}
+          {runtime?.canStop === true && (
+            <Button size="sm" onClick={() => onRuntime('stop')} disabled={busy}>
+              <IconStop size={13} /> {t('stop')}
+            </Button>
+          )}
+          {runtime?.canRestart === true && (
+            <Button size="sm" onClick={() => onRuntime('restart')} disabled={busy}>
+              <IconRestart size={13} /> {t('restart')}
+            </Button>
+          )}
+          {runtime?.canStart !== true && runtime?.canStop !== true && runtime?.canRestart !== true && (
+            <span className="dsh-docker-muted">{status.capabilities?.enableRuntimeControl === false ? t('runtimeControlDisabled') : runtime?.error ?? t('remoteHint')}</span>
+          )}
+        </div>
+      </div>
+    </section>
+  )
+}
+
+function RecentContainers({ t, list, onOpenTab, onInspect }) {
+  if (list.loading && list.data === null) return <LoadingSkeleton rows={4} />
+  if (list.error !== null && list.data === null) {
+    return <ErrorState title={t('listFailed')} text={list.error.message} retryLabel={t('retry')} onRetry={list.reload} />
+  }
+  const items = (list.data?.items ?? []).slice(0, 5)
+  if (items.length === 0) {
+    return <EmptyState icon={<IconBox size={19} />} title={t('emptyContainers')} />
+  }
+  return (
+    <div className="dsh-docker-table-wrap">
+      <table className="dsh-docker-table">
+        <thead>
+          <tr>
+            <th>{t('name')}</th>
+            <th>{t('image')}</th>
+            <th>{t('status')}</th>
+            <th>{t('ports')}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {items.map((item) => (
+            <tr key={item.id} onClick={() => onInspect('container', item.id)} style={{ cursor: 'pointer' }}>
+              <td><span className="dsh-docker-row-title">{item.name || item.id}</span></td>
+              <td className="dsh-docker-mono dsh-docker-truncate">{item.image}</td>
+              <td><StateLabel state={item.state} t={t} /></td>
+              <td><Chips values={item.ports.slice(0, 2)} mono /></td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      <div style={{ display: 'flex', justifyContent: 'flex-end', padding: '8px 12px' }}>
+        <Button size="sm" variant="ghost" onClick={() => onOpenTab('containers')}>{t('viewAll')}</Button>
+      </div>
+    </div>
+  )
+}
+
+function DiskCard({ t, list }) {
+  if (list.loading && list.data === null) return <LoadingSkeleton rows={3} />
+  if (list.error !== null && list.data === null) return <div className="dsh-docker-muted" style={{ padding: 16 }}>{list.error.message}</div>
+  const items = list.data?.items ?? []
+  if (items.length === 0) return <div className="dsh-docker-muted" style={{ padding: 16 }}>{t('noDiskData')}</div>
+  return (
+    <div className="dsh-docker-table-wrap">
+      <table className="dsh-docker-table">
+        <thead>
+          <tr>
+            <th>{t('status')}</th>
+            <th className="dsh-docker-col-num">{t('size')}</th>
+            <th className="dsh-docker-col-num">Reclaimable</th>
+          </tr>
+        </thead>
+        <tbody>
+          {items.map((item) => (
+            <tr key={item.type}>
+              <td>{item.type}</td>
+              <td className="dsh-docker-col-num">{displayValue(item.size)}</td>
+              <td className="dsh-docker-col-num">{displayValue(item.reclaimable)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+export default function OverviewTab({ t, api, provider, context, status, refreshToken, onRuntime, onOpenTab, onInspect, onQuickCommand, runState }) {
+  const enabled = status?.daemon?.state === 'running'
+  const containers = useDockerList(api, provider, 'containers', context, { all: true, refreshToken, enabled })
+  const images = useDockerList(api, provider, 'images', context, { refreshToken, enabled })
+  const volumes = useDockerList(api, provider, 'volumes', context, { refreshToken, enabled })
+  const networks = useDockerList(api, provider, 'networks', context, { refreshToken, enabled })
+  const disk = useDockerList(api, provider, 'disk', context, { refreshToken, enabled })
+  const busy = runState?.run !== null && runState?.run !== undefined && (runState.run.status === 'running' || runState.run.status === 'cancelling')
+  const server = status?.server
+  const isApple = provider === 'apple-container'
+  const quick = isApple ? ['ls -a', 'image ls', 'volume ls', 'network ls', 'system df', 'system version'] : ['ps -a', 'images', 'volume ls', 'network ls', 'compose ls', 'system df', 'info', 'version']
+  const commandPrefix = isApple ? 'container' : 'docker'
+  const recent = useMemo(() => (containers.data?.items ?? []).slice(0, 5), [containers.data])
+
+  const volumeCount = volumes.data?.items?.length
+  const networkCount = networks.data?.items?.length
+  const imageCount = images.data?.items?.length ?? server?.images
+
+  return (
+    <div className="dsh-docker-stack">
+      <div className="dsh-docker-stats">
+        <Stat label={t('runningContainers')} value={server?.containersRunning ?? '—'} detail={isApple ? t('providerApple') : context ?? t('noContext')} />
+        <Stat label={t('stoppedContainers')} value={server?.containersStopped ?? '—'} />
+        <Stat label={t('imageCount')} value={imageCount ?? '—'} />
+        <Stat label={t('volumeCount')} value={volumeCount ?? '—'} />
+        <Stat label={t('networkCount')} value={networkCount ?? '—'} />
+        <Stat
+          label={t('server')}
+          value={provider === 'apple-container' ? status?.client?.version ?? server?.version ?? '—' : server?.version ?? status?.client?.version ?? '—'}
+          detail={server?.ncpu !== undefined ? `${server.ncpu} CPU · ${formatBytes(server.memTotal)}` : undefined}
+        />
+      </div>
+
+      <div className="dsh-docker-grid-2">
+        <RuntimeCard t={t} provider={provider} status={status} imageCount={imageCount} volumeCount={volumeCount} networkCount={networkCount} onRuntime={onRuntime} busy={busy} />
+        <section className="dsh-docker-card">
+          <div className="dsh-docker-card-head">
+            <div>
+              <h2 className="dsh-docker-card-title">{t('quickCommands')}</h2>
+              <p className="dsh-docker-card-sub">{t('terminal')}</p>
+            </div>
+            <IconTerminal size={16} className="dsh-docker-muted" />
+          </div>
+          <div className="dsh-docker-card-body">
+            <div className="dsh-docker-chip-row">
+              {quick.map((command) => (
+                <button key={command} type="button" className="dsh-docker-quick" onClick={() => onQuickCommand(`${commandPrefix} ${command}`)}>
+                  {command}
+                </button>
+              ))}
+            </div>
+            <div className="dsh-docker-divider" />
+            <div className="dsh-docker-kv">
+              <div className="dsh-docker-kv-key">{t('client')}</div>
+              <div className="dsh-docker-kv-value">{status?.client?.version ?? '—'} {status?.cli?.path ? <span className="dsh-docker-mono dsh-docker-muted"> · {status.cli.path}</span> : null}</div>
+              <div className="dsh-docker-kv-key">{isApple ? t('providerLabel') : t('context')}</div>
+              <div className="dsh-docker-kv-value">{isApple ? t('providerApple') : context ?? status?.context?.selected ?? status?.context?.current ?? t('noContext')}</div>
+              <div className="dsh-docker-kv-key">{t('lastUpdated')}</div>
+              <div className="dsh-docker-kv-value">{formatTime(status?.fetchedAt)}</div>
+            </div>
+          </div>
+        </section>
+      </div>
+
+      <div className="dsh-docker-grid-2">
+        <section className="dsh-docker-card">
+          <div className="dsh-docker-card-head">
+            <div>
+              <h2 className="dsh-docker-card-title">{t('recentContainers')}</h2>
+            </div>
+            <Button size="sm" variant="ghost" onClick={() => onOpenTab('containers')}>{t('viewAll')}</Button>
+          </div>
+          <div className="dsh-docker-card-body dsh-docker-flush" style={{ paddingTop: 10 }}>
+            <RecentContainers t={t} list={{ ...containers, data: containers.data ?? { items: recent } }} onOpenTab={onOpenTab} onInspect={onInspect} />
+          </div>
+        </section>
+        <section className="dsh-docker-card">
+          <div className="dsh-docker-card-head">
+            <div>
+              <h2 className="dsh-docker-card-title">{t('disk')}</h2>
+              <p className="dsh-docker-card-sub">{commandPrefix} system df</p>
+            </div>
+            <IconImage size={16} className="dsh-docker-muted" />
+          </div>
+          <div className="dsh-docker-card-body dsh-docker-flush" style={{ paddingTop: 10 }}>
+            <DiskCard t={t} list={disk} />
+          </div>
+        </section>
+      </div>
+    </div>
+  )
+}

package/src/client/tabs/volumes.jsx

@@ -0,0 +1,76 @@
+/** Volumes tab. */
+import { useMemo, useState } from 'react'
+
+import { Button, EmptyState, ErrorState, IconButton, LoadingSkeleton, SearchInput, displayValue } from '../components.jsx'
+import { useDockerList } from '../hooks.js'
+import { IconAlert, IconInfo, IconTrash, IconVolume } from '../icons.jsx'
+
+export default function VolumesTab({ t, api, provider, context, status, refreshToken, onAction, onInspect }) {
+  const [search, setSearch] = useState('')
+  const enabled = status?.daemon?.state === 'running'
+  const list = useDockerList(api, provider, 'volumes', context, { refreshToken, enabled })
+  const items = list.data?.items ?? []
+  const filtered = useMemo(() => {
+    const needle = search.trim().toLowerCase()
+    return needle === '' ? items : items.filter((item) => `${item.name} ${item.driver} ${item.mountpoint}`.toLowerCase().includes(needle))
+  }, [items, search])
+
+  return (
+    <div className="dsh-docker-stack">
+      <div className="dsh-docker-toolbar">
+        <div className="dsh-docker-toolbar-left">
+          <SearchInput value={search} onChange={setSearch} placeholder={t('search')} label={t('search')} />
+        </div>
+        <div className="dsh-docker-toolbar-right">
+          <span className="dsh-docker-muted">{filtered.length} / {items.length}</span>
+          <Button size="sm" onClick={list.reload} disabled={list.loading}>{t('refresh')}</Button>
+        </div>
+      </div>
+      {!enabled && items.length === 0 ? (
+        <EmptyState icon={<IconAlert size={20} />} title={provider === 'apple-container' ? t('appleSystemStopped') : t('daemonStopped')} text={provider === 'apple-container' ? t('appleSystemStoppedBody') : t('daemonStoppedBody')} />
+      ) : list.loading && list.data === null ? (
+        <LoadingSkeleton rows={5} />
+      ) : list.error !== null && list.data === null ? (
+        <ErrorState title={t('listFailed')} text={list.error.message} retryLabel={t('retry')} onRetry={list.reload} />
+      ) : filtered.length === 0 ? (
+        <EmptyState icon={<IconVolume size={20} />} title={search === '' ? t('emptyVolumes') : t('emptySearch')} text={search === '' ? undefined : search} />
+      ) : (
+        <section className="dsh-docker-card">
+          <div className="dsh-docker-table-wrap">
+            <table className="dsh-docker-table">
+              <thead>
+                <tr>
+                  <th>{t('name')}</th>
+                  <th>{t('driver')}</th>
+                  <th>{t('scope')}</th>
+                  <th>{t('mountpoint')}</th>
+                  <th className="dsh-docker-col-actions">{t('actions')}</th>
+                </tr>
+              </thead>
+              <tbody>
+                {filtered.map((item) => (
+                  <tr key={item.name}>
+                    <td className="dsh-docker-mono dsh-docker-row-title">{item.name}</td>
+                    <td>{displayValue(item.driver)}</td>
+                    <td>{displayValue(item.scope)}</td>
+                    <td className="dsh-docker-mono dsh-docker-muted dsh-docker-truncate" title={item.mountpoint}>{displayValue(item.mountpoint)}</td>
+                    <td className="dsh-docker-col-actions">
+                      <span className="dsh-docker-row-actions">
+                        <IconButton size="sm" label={t('inspect')} onClick={() => onInspect('volume', item.name)}>
+                          <IconInfo size={14} />
+                        </IconButton>
+                        <IconButton size="sm" label={t('removeVolume')} onClick={() => onAction({ kind: 'volume', action: 'delete', id: item.name })}>
+                          <IconTrash size={14} />
+                        </IconButton>
+                      </span>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </section>
+      )}
+    </div>
+  )
+}

package/src/host/apple-cli.js

@@ -0,0 +1,307 @@
+/**
+ * Apple `container` CLI discovery and process execution.
+ *
+ * Apple container is not Docker: there is no daemon socket, no Docker context,
+ * and every container runs in its own lightweight VM. The CLI is invoked
+ * directly and its `--format json` output is parsed by the provider.
+ */
+import { accessSync, constants, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+
+import { summarizeStderr } from './parsers.js'
+import { codeOf, messageOf } from './util.js'
+
+const DEFAULT_MAX_OUTPUT = 1024 * 1024
+const DEFAULT_TIMEOUT = 20_000
+const RESOLVE_RETRY_MS = 10_000
+
+export class AppleCliError extends Error {
+  /** @param {string} message @param {string} code @param {Record<string, unknown>} details */
+  constructor(message, code = 'container/cli-missing', details = {}) {
+    super(message)
+    this.name = 'AppleCliError'
+    this.code = code
+    this.details = details
+  }
+}
+
+export class AppleCommandError extends Error {
+  /** @param {string} message @param {{code?: string, stderr?: string, details?: Record<string, unknown>}} [options] */
+  constructor(message, options = {}) {
+    super(message)
+    this.name = 'AppleCommandError'
+    this.code = options.code ?? 'container/exec-failed'
+    this.stderr = options.stderr ?? ''
+    this.details = options.details ?? {}
+  }
+}
+
+/** @param {string} path */
+function executable(path) {
+  try {
+    accessSync(path, constants.X_OK)
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** @param {number} value @param {number} fallback */
+function clampBytes(value, fallback) {
+  return Number.isFinite(value) ? Math.min(Math.max(Math.trunc(value), 64 * 1024), 8 * 1024 * 1024) : fallback
+}
+
+export class AppleCli {
+  /**
+   * @param {{
+   *   subprocess: any,
+   *   config?: Record<string, any>,
+   *   env?: NodeJS.ProcessEnv,
+   *   home?: string,
+   *   platform?: NodeJS.Platform,
+   *   logger?: any,
+   * }} options
+   */
+  constructor(options) {
+    this.subprocess = options.subprocess
+    this.config = options.config ?? {}
+    this.env = options.env ?? process.env
+    this.home = options.home ?? homedir()
+    this.platform = options.platform ?? process.platform
+    this.logger = options.logger
+    this.maxOutput = clampBytes(Number(this.config.maxOutputBytes), DEFAULT_MAX_OUTPUT)
+    this.containerPath = undefined
+    this.lastAttempt = 0
+    this.error = undefined
+  }
+
+  /** @returns {string[]} */
+  candidates() {
+    const configured = typeof this.config.containerPath === 'string' && this.config.containerPath.trim() !== '' ? this.config.containerPath.trim() : null
+    const envPath = typeof this.env.CONTAINER_PATH === 'string' && this.env.CONTAINER_PATH.trim() !== '' ? this.env.CONTAINER_PATH.trim() : null
+    return [
+      configured,
+      envPath,
+      '/usr/local/bin/container',
+      '/opt/homebrew/bin/container',
+      join(this.home, '.local/bin/container'),
+    ].filter((value, index, list) => typeof value === 'string' && value !== '' && list.indexOf(value) === index)
+  }
+
+  /** @param {AbortSignal | undefined} signal */
+  async resolveOnPath(signal) {
+    if (typeof this.subprocess.resolveExecutable !== 'function') return undefined
+    try {
+      return await this.subprocess.resolveExecutable('container', undefined, signal)
+    } catch (error) {
+      if (error?.name === 'SubprocessExecutableNotFoundError' || codeOf(error) === 'ENOENT') return undefined
+      throw error
+    }
+  }
+
+  /**
+   * @param {{signal?: AbortSignal, force?: boolean}} [options]
+   * @returns {Promise<string>}
+   */
+  async ensureContainer(options = {}) {
+    if (this.containerPath !== undefined) return this.containerPath
+    const now = Date.now()
+    if (!options.force && now - this.lastAttempt < RESOLVE_RETRY_MS && this.error !== undefined) throw this.error
+    this.lastAttempt = now
+    const configured = typeof this.config.containerPath === 'string' && this.config.containerPath.trim() !== '' ? this.config.containerPath.trim() : null
+    if (configured !== null) {
+      const path = isAbsolute(configured) ? configured : resolve(this.home, configured)
+      if (executable(path)) {
+        this.containerPath = path
+        this.error = undefined
+        return path
+      }
+      const error = new AppleCliError(`配置的 containerPath 不可执行: ${configured}`, 'container/cli-missing', { candidates: [configured] })
+      this.error = error
+      throw error
+    }
+    for (const candidate of this.candidates()) {
+      const path = isAbsolute(candidate) ? candidate : resolve(this.home, candidate)
+      if (executable(path)) {
+        this.containerPath = path
+        this.error = undefined
+        return path
+      }
+    }
+    const onPath = await this.resolveOnPath(options.signal)
+    if (onPath !== undefined && executable(onPath)) {
+      this.containerPath = onPath
+      this.error = undefined
+      return onPath
+    }
+    const error = new AppleCliError(
+      '未找到 Apple container 命令。请安装 container（macOS 26 / Apple silicon）并执行 container system start。',
+      'container/cli-missing',
+      { candidates: this.candidates() },
+    )
+    this.error = error
+    throw error
+  }
+
+  /** @returns {NodeJS.ProcessEnv} */
+  childEnv() {
+    const pathParts = []
+    if (typeof this.containerPath === 'string') pathParts.push(dirname(this.containerPath))
+    pathParts.push('/usr/local/bin', '/opt/homebrew/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin')
+    if (typeof this.env.PATH === 'string') pathParts.push(...this.env.PATH.split(':'))
+    return {
+      PATH: [...new Set(pathParts.filter(Boolean))].join(':'),
+      NO_COLOR: '1',
+      CLICOLOR: '0',
+      TERM: 'dumb',
+      CONTAINER_DEBUG: '0',
+    }
+  }
+
+  /** @param {string} path */
+  markMissing(path) {
+    if (this.containerPath === path) {
+      this.containerPath = undefined
+      this.error = undefined
+      this.lastAttempt = 0
+    }
+  }
+
+  /**
+   * @param {string[]} subargv
+   * @param {{cwd?: string, timeoutMs?: number, signal?: AbortSignal, maxBytes?: number}} [options]
+   */
+  async exec(subargv, options = {}) {
+    const path = await this.ensureContainer({ signal: options.signal })
+    const maxBytes = clampBytes(Number(options.maxBytes ?? this.maxOutput), this.maxOutput)
+    const timeoutMs = Math.min(Math.max(Number(options.timeoutMs ?? DEFAULT_TIMEOUT), 1000), 10 * 60_000)
+    const abort = new AbortController()
+    let timedOut = false
+    const onAbort = () => abort.abort(options.signal?.reason)
+    options.signal?.addEventListener('abort', onAbort, { once: true })
+    if (options.signal?.aborted === true) abort.abort(options.signal.reason)
+    const timeout = setTimeout(() => {
+      timedOut = true
+      abort.abort(new Error('container command timed out'))
+    }, timeoutMs)
+    timeout.unref?.()
+
+    let handle
+    try {
+      handle = this.subprocess.spawn({
+        argv: [path, ...subargv],
+        cwd: options.cwd ?? this.home,
+        stdio: { stdin: 'ignore', stdout: { maxBytes }, stderr: { maxBytes } },
+        graceMs: 2000,
+        env: this.childEnv(),
+        signal: abort.signal,
+      })
+    } catch (error) {
+      clearTimeout(timeout)
+      options.signal?.removeEventListener('abort', onAbort)
+      throw new AppleCommandError(`无法启动 container: ${messageOf(error)}`, { code: 'container/exec-failed' })
+    }
+
+    let outcome
+    try {
+      outcome = await handle.done
+    } catch (error) {
+      clearTimeout(timeout)
+      options.signal?.removeEventListener('abort', onAbort)
+      this.markMissing(path)
+      throw new AppleCommandError(`container 进程失败: ${messageOf(error)}`, { code: 'container/exec-failed' })
+    }
+    clearTimeout(timeout)
+    options.signal?.removeEventListener('abort', onAbort)
+    const stdout = handle.collected?.stdout?.readFrom(0)?.text ?? ''
+    const stderr = handle.collected?.stderr?.readFrom(0)?.text ?? ''
+    return { exitCode: outcome.exitCode, signal: outcome.signal, stdout, stderr, timedOut, argv: [path, ...subargv] }
+  }
+
+  /**
+   * Execute and require a zero exit code.
+   * @param {string[]} subargv
+   * @param {{cwd?: string, timeoutMs?: number, signal?: AbortSignal, maxBytes?: number}} [options]
+   */
+  async ok(subargv, options = {}) {
+    const result = await this.exec(subargv, options)
+    if (result.timedOut || result.exitCode !== 0) {
+      const detail = summarizeStderr(result.stderr)
+      throw new AppleCommandError(
+        result.timedOut ? `container ${subargv[0] ?? ''} 超时` : detail.trim() === '' ? `container ${subargv[0] ?? ''} 退出码 ${String(result.exitCode)}` : detail,
+        {
+          code: result.timedOut ? 'container/timeout' : 'container/exec-failed',
+          stderr: result.stderr,
+          details: { argv: result.argv, exitCode: result.exitCode, timedOut: result.timedOut },
+        },
+      )
+    }
+    return result
+  }
+
+  /**
+   * @param {string[]} subargv
+   * @param {{cwd?: string, timeoutMs?: number, signal?: AbortSignal, maxBytes?: number}} [options]
+   */
+  async json(subargv, options = {}) {
+    const result = await this.ok(subargv, options)
+    try {
+      return JSON.parse(result.stdout)
+    } catch (error) {
+      throw new AppleCommandError(`无法解析 container JSON: ${messageOf(error)}`, {
+        code: 'container/protocol',
+        stderr: result.stderr,
+        details: { stdout: result.stdout.slice(0, 2000) },
+      })
+    }
+  }
+
+  /** @param {AbortSignal | undefined} signal */
+  async systemStatus(signal) {
+    try {
+      const result = await this.exec(['system', 'status', '--format', 'json'], { signal, timeoutMs: 10_000 })
+      if (result.exitCode !== 0) {
+        return { status: 'unavailable', error: summarizeStderr(result.stderr) || `exit ${String(result.exitCode)}`, raw: null }
+      }
+      return JSON.parse(result.stdout)
+    } catch (error) {
+      return { status: 'unavailable', error: messageOf(error), raw: null }
+    }
+  }
+
+  /** @param {AbortSignal | undefined} signal */
+  async systemVersion(signal) {
+    try {
+      const raw = await this.json(['system', 'version', '--format', 'json'], { signal, timeoutMs: 10_000 })
+      return Array.isArray(raw) ? raw : [raw]
+    } catch {
+      return []
+    }
+  }
+
+  /** @param {AbortSignal | undefined} signal */
+  async df(signal) {
+    return this.json(['system', 'df', '--format', 'json'], { signal, timeoutMs: 30_000 })
+  }
+
+  /**
+   * `container system status` has reported `unregistered` on installs where the
+   * apiserver is still reachable; a lightweight list is the authoritative
+   * health probe. Returns undefined when the service is not reachable.
+   * @param {AbortSignal | undefined} signal
+   */
+  async probe(signal) {
+    try {
+      const raw = await this.json(['list', '-a', '--format', 'json'], { signal, timeoutMs: 10_000 })
+      return Array.isArray(raw) ? raw : []
+    } catch {
+      return undefined
+    }
+  }
+
+  /** @param {string} path */
+  static commandName(path) {
+    return basename(path)
+  }
+}