software-stack-cli

name	software-stack-cli
description	TypeScript CLI/TUI/SDK library design on Bun + Hono + zod + vite-plus + vitest. One package hosts a daemon, a CLI, a TUI, and an importable library off the same composition root. Every IO boundary is a port type and every IO-heavy class extracts a pure inner class so the whole thing is mockable end to end.
user-invocable	false
disable-model-invocation	false
metadata	{"author":"shigurenimo","description":"Bun + Hono + zod + vite-plus + vitest ベースの TypeScript CLI / TUI / SDK ライブラリ開発スキル。","dev":true,"tags":["stack"]}

CLI / TUI / SDK Library

A single package that ships as a CLI, a TUI, and an embeddable library, all driven by the same composition root. The design optimises for full mockability: each IO boundary is exposed as a port type and each IO-heavy class extracts a pure sibling.

Toolchain (vite-plus, vitest, @/* alias, fmt/lint config) lives in software-stack under vp.

Layout

Everything lives under lib/. UI layers (cli/, tui/) depend on runtime/; only runtime/ reaches into the core modules (engine/, channels/, config/, gateway/, env/, daemon/). Core never imports UI.

lib/
├── api.ts                  public exports (barrel)
├── index.ts                bin entry / argv dispatcher
├── error-message.ts        shared err.message helper
├── cli/                    argv → Hono router → handler
├── tui/                    @opentui/react components
├── runtime/                composition root
├── engine/                 core orchestrator
├── channels/               channel plugins (chat integrations)
├── config/                 .<app>/config.json read/write
├── daemon/                 PID / log / process supervision
├── env/                    env var loading + zod validation
└── gateway/                daemon ↔ UI/external HTTP IPC

Class names carry the project prefix (<App>Engine, <App>Daemon, <App>ConfigStore); filenames are kebab-case without the prefix because the directory provides the namespace. Type aliases stay unprefixed (ChannelPlugin, ProcessResult, ThreadEntry).

Ports for IO boundaries

Every external SDK, child process, or HTTP boundary gets a *Port type that core code depends on; the real class structurally satisfies the port and tests pass in fakes. Concrete examples: engine/codex/codex-client-port.ts exports CodexClientPort, channels/slack/web-client-port.ts exports WebClientPort, engine/channel-plugin.ts exports the ChannelPlugin and ChannelPluginContext pair.

Pure logic isolation

Inside any IO-heavy class — <X>Listener, <X>Client, <X>Server — pull the methods that don't touch fs, spawn, net, or third-party SDKs into a pure sibling. Use <X>Processor for event normalisation (dedup, filtering, mention strip), <X>Protocol for wire framing (JSON-RPC, NDJSON), and standalone helper files for one-off pure logic (daemon/daemon-key.ts, gateway/build-gateway-app.ts). Each pure class is unit-tested with synthetic input and a fake writer; no IO involved.

Composition root

runtime/runtime.ts builds and owns every module. CLI and TUI call <App>Runtime.build({ cwd, env, ... }) and never new core modules directly. Build returns T | Error, never throws.

export class <App>Runtime {
  private constructor(private readonly props: Built) {
    Object.freeze(this)
  }

  static build(props): <App>Runtime | Error {
    const configStore = new <App>ConfigStore({ cwd: props.cwd })
    const config = configStore.load()
    if (config instanceof Error) return config

    const channelHost = <App>ChannelHost.fromConfig({ config, env: props.env })
    if (channelHost instanceof Error) return channelHost

    const core = new <App>CoreClient(...)
    const engine = new <App>Engine({ core, plugins: channelHost.getPlugins(), ... })
    return new <App>Runtime({ configStore, channelHost, core, engine })
  }

  async start(): Promise<void | Error>
  async stop(): Promise<void>
}

Stores

Wrap every file IO surface in a class. Constructor takes cwd (or scope), methods are load() / save() / list() / add() / remove(), no throws, returning T | Error. Pair each store with a sibling <x>-schema.ts that exports zod schemas plus z.infer types. Concrete files: config/config-store.ts plus config/config-schema.ts for app config, and per-domain stores like engine/<x>/<x>-agent-store.ts.

Plugin abstraction

Replaceable behaviour goes through an interface plus a host. The host reads config and constructs plugin instances; the engine sees only the interface, never the concrete plugin types.

type ChannelPlugin = {
  readonly name: string
  start(ctx: ChannelPluginContext): Promise<void>
  stop(): Promise<void>
}

class <App>ChannelHost {
  static fromConfig(props): <App>ChannelHost | Error
  getPlugins(): readonly ChannelPlugin[]
}

CLI router

cli/utils/to-request.ts converts argv into a POST /<cmd> request with a JSON body of { args, flags }; Hono dispatches to handlers. Each handler reads the body via cli/utils/read-cli-body.ts (zod-parsed). Routes are flat, Remix-style: dots in the filename become path segments, and help text lives in a sibling file.

cli/
├── cli-factory.ts                Hono factory
├── routes/
│   ├── index.ts
│   ├── group.help.ts             root --help
│   ├── start.ts        + start.help.ts
│   ├── projects.add.ts + projects.add.help.ts   POST /projects/add
│   └── channels.list.ts          ...
└── utils/
    ├── to-request.ts             argv → POST
    ├── read-cli-body.ts
    ├── flag-bool.ts / flag-string.ts
    └── parse-<param>.ts          per-command flag parsers

Daemon

A PID file gates double-start. State directory is ~/.<app>/daemons/<basename>-<sha1[:6]>/. stop sends SIGTERM and leaves logs in place so <app> logs -f can tail -F against the same file. The pure daemon-key.ts (cwd → state-dir name) is a separate file so tests don't need fs.

daemon/
├── <app>-daemon.ts        start / stop / status / readPid / isRunning
└── daemon-key.ts          pure cwd → state-dir key

Gateway (HTTP IPC)

gateway/build-gateway-app.ts is a pure factory that builds the Hono app from injected deps; gateway/gateway-server.ts is a thin Bun.serve wrapper around it. Tests run app.request(...) directly on the built app — no port binding, no sockets.

gateway/
├── build-gateway-app.ts          pure Hono factory
├── gateway-server.ts             Bun.serve wrapper
├── gateway-factory.ts            Hono factory + Env type
├── gateway-route-deps.ts
└── routes/
    ├── index.ts
    ├── health-route.ts
    ├── status-route.ts
    └── threads/
        ├── list-route.ts
        └── clear-route.ts

Env

env/
├── cli-env-schema.ts             zod schema + type
└── <app>-env.ts                  class <App>Env (loadFile, parseCli)

loadFile(path) reads .env-style files without overwriting existing process.env keys. parseCli() runs the schema's safeParse and returns T | Error.

Public API

Re-export every class, every port type, the major types, and the zod schemas from lib/api.ts. Point package.json main, module, types, and exports.types at ./lib/api.ts so consumers can import { LeucoRuntime, LeucoConfigStore, ... } from "<package>".

{
  "main": "./lib/api.ts",
  "module": "./lib/api.ts",
  "types": "./lib/api.ts",
  "exports": {
    ".": {
      "types": "./lib/api.ts",
      "bun": "./lib/api.ts",
      "default": "./lib/api.ts"
    },
    "./package.json": "./package.json"
  }
}

Tests

Run with vp test run and add "test": "vp test run" to package.json scripts. Test by layer: pure processor, protocol, and utility files take synthetic input/output unit tests; stores get a tmpdir and exercise real fs; the channel host runs against a fake config and fake env; the engine runs against a fake core (via the port) plus fake ChannelPlugins; gateway routes are tested with buildGatewayApp({ engine: fakeEngine }) followed by app.request(...); adapters are tested with the relevant *Port faked, asserting the calls made.

Project rules

No throws — return T | Error. No as (use never-narrowing for exhaustive discriminator unions). No destructuring; use explicit property access (const x = obj.x). One function or one class per file, with the filename matching the class or function name minus the project prefix in kebab-case. Absent values are null, never optional (string | null, never string?). Wire data is always parsed by zod schemas; types come from z.infer.

Migration patterns

When pulling existing code into this layout:

loadEnvFile(path) function       ⇒ <App>Env class method
loadConfig / saveConfig fns      ⇒ <x>-store.ts class
nested routes <res>/<act>.ts     ⇒ flat <res>.<act>.ts
filename <dir>-<class>.ts        ⇒ filename <class>.ts (dir as namespace)
spawn + protocol same class      ⇒ <X>Client (IO) + <X>Protocol (pure)
new ExternalSdk(token) inline    ⇒ static fromXxx() factory + Port type