1.3 Implement the command registry

[goofmint]

Part of Phase 1 — Core skeleton (tasks.md Task 1.3).

Summary

Implement core/commands/registry.ts: the command bus every behavior in tecode goes through.

Details

• register(id, handler, meta?) returns a Disposable; re-registering an existing ID replaces the handler (last-wins) and logs a warning.
• execute(id, ...args) is async and never throws: unknown ID and handler exceptions become HostErrors routed to a status sink (stub interface for now; the statusbar extension consumes it later). Returns undefined on failure, the handler's return value on success.
• list() returns { id, title, category, when }[] for the palette; no when-filtering here (callers filter).
• Command IDs follow namespace.verb; meta supports title, category, when.

Completion requirements

• Unknown-ID execute surfaces Command not found: <id> via the status sink and does not throw
• A throwing handler is caught, logged to the host log, surfaced via the sink; execute resolves undefined
• Disposing a registration removes the command; double-dispose is a no-op
• Re-registration replaces last-wins with a logged warning
• Unit tests cover: unknown ID, throwing handler, dispose semantics, list() metadata
• bun test and lint pass

References

• requirements.md: Req 3.1–3.5
• design.md: §5

Dependencies

Blocked by: 1.2 (#3). Parallelizable with 1.4–1.10.

[goofmint]

@coderabbitai make plan in Japanese

---

Generated by Claude Code

[coderabbitai]

Coding Plan

Summary

• @tecode/api には、1.3 に必要な最小限の型（Disposable、CommandMeta、CommandHandler、CommandInfo）だけを追加する。1.2 の全 API サーフェスは作らない。
• HostError、HostLog、StatusSink を @tecode/core の host モジュールに新設する。依存注入でレジストリへ渡す。
• レジストリはファクトリ関数 createCommandRegistry(deps) として実装する。Map<string, CommandEntry> を状態に持つ。execute は例外を投げない。失敗を HostError としてシンクへ送る。
• bun:test のフラットな test(...) 形式で、未登録 ID・例外ハンドラ・dispose 意味論・list() メタデータを検証する。bun test と lint を通す。

Design Choices

Design Choice 1: `Disposable` とコマンド関連型をどこに定義するか

Options Considered:

1. 必要最小限の型（Disposable、コマンドの handler／meta／list 用型）だけを @tecode/api に追加する。
2. @tecode/core 内にローカル型を定義し、@tecode/api は変更しない。

Chosen Option: 1

Rationale: 設計は Disposable を @tecode/api に置くと定める。@tecode/core は既に @tecode/api に依存する。したがって、公開型は @tecode/api に置くのが自然である。ただし、1.2 の全型は作らない。1.3 に必要な範囲に限定する。

Design Choice 2: `HostError`、`HostLog`、ステータスシンクをどこに置くか

Options Considered:

1. HostError、HostLog、StatusSink を @tecode/core の host モジュールに置く。
2. すべて registry.ts 内に置く。

Chosen Option: 1

Rationale: HostLog は core の横断的な仕組みである。後続タスク（developer.showLog、statusbar 拡張）がこれを消費する。したがって、host モジュールに置くと再利用しやすい。

Design Choice 3: レジストリをクラスにするか関数にするか

Options Considered:

1. ファクトリ関数 createCommandRegistry(deps) が register／execute／list を持つオブジェクトを返す。
2. モジュールレベルの Map を持つ純関数群。

Chosen Option: 1

Rationale: ファクトリ関数を使うと、ステータスシンクとホストログを依存注入できる。テストでスタブを差し込める。既存の「クラスを使わない」慣習にも沿う。したがって、ファクトリ関数が最も適する。

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: 補助型と host モジュールの定義

このフェーズでは、レジストリが依存する公開型とエラー処理の仕組みを用意する。@tecode/api に最小限の公開型を追加する。@tecode/core の host に HostError、HostLog、StatusSink を定義する。

Task 1: `@tecode/api` にコマンド関連の公開型を追加する

レジストリが参照する公開型を最小限だけ定義する。

• packages/api/src/index.ts に Disposable を追加する。形は { dispose(): void } とする。
• コマンドメタデータ型 CommandMeta を追加する。title?、category?、when?（すべて任意、string）を持たせる（Req 3.3）。
• コマンドハンドラ型 CommandHandler を追加する。(...args: unknown[]) => unknown | Promise<unknown> とする。
• list() の戻り値要素型 CommandInfo を追加する。{ id: string; title?: string; category?: string; when?: string } とする。
• 既存のプレースホルダ定数は残すか、名前付きエクスポートの追加のみに留める。全 API サーフェス（1.2 の全型）は作らない。

Task 2: host に `HostError`、`HostLog`、`StatusSink` を定義する

コマンド失敗を集約・通知する仕組みを用意する。

• packages/core/src/host/ に新規ファイル（例: packages/core/src/host/errors.ts）を作成する。
• HostError 型を定義する。形は設計 §4.1 に合わせ { extensionId?: string; path?: string; message: string } とする。コマンド失敗にも再利用する。
• HostLog を定義する。構造化エラーを配列に蓄積し、追加と取得を行う最小実装とする。ファクトリ関数 createHostLog() を提供する。
• StatusSink インターフェースを定義する。HostError を受け取る 1 メソッド（例: error(err: HostError): void）を持つスタブ用インターフェースとする。実 UI 配線は後続タスクで行う。
• テスト用に使えるノーオペのデフォルトシンク（例: createNoopStatusSink()）を提供する。
• これらを packages/core/src/host/index.ts から名前付きで再エクスポートする。

🤖 Prompt for AI agents

このフェーズでは、コマンドレジストリが依存する公開型とエラー処理の仕組みを実装する。目的は、`@tecode/api`
に最小限の公開型を追加し、`@tecode/core` の host モジュールにエラー集約・通知の仕組みを用意することである。

タスク 1: `packages/api/src/index.ts` を更新する。
- `Disposable` 型を追加する。形は `{ dispose(): void }` とする。
- `CommandMeta` 型を追加する。`title?`、`category?`、`when?` を持たせる。すべて任意の `string`
とする（Req 3.3）。
- `CommandHandler` 型を追加する。シグネチャは `(...args: unknown[]) => unknown |
Promise<unknown>` とする。
- `CommandInfo` 型を追加する。形は `{ id: string; title?: string; category?: string;
when?: string }` とする。
- 既存のプレースホルダ定数は変更しないか、名前付きエクスポートの追加のみに留める。1.2 で計画されている全 API
サーフェスは実装しない。今回必要な範囲のみを実装する。

タスク 2: `packages/core/src/host/` に新規ファイル（例: `errors.ts`）を作成する。
- `HostError` 型を定義する。設計 §4.1 に合わせ `{ extensionId?: string; path?: string;
message: string }` とする。この型はコマンド失敗の表現にも再利用する。
- `HostLog` を定義する。構造化エラーを配列に蓄積する。エラーの追加と取得ができる最小実装とする。ファクトリ関数 `createHostLog()`
を提供する。
- `StatusSink` インターフェースを定義する。`HostError` を受け取るメソッド（例: `error(err: HostError):
void`）を 1 つ持つ。UI への実配線は本フェーズでは行わない。後続タスクで行う。
- テスト用のノーオペシンク（例: `createNoopStatusSink()`）を提供する。
- `HostError`、`HostLog`（および `createHostLog`）、`StatusSink`（および
`createNoopStatusSink`）を `packages/core/src/host/index.ts`
から名前付きで再エクスポートする。`export default` は使わない。

Phase 2: コマンドレジストリの実装

このフェーズでは、register／execute／list を実装する。core のエクスポートに配線する。

Task 1: `registry.ts` を実装する

コマンドバスの本体を実装する。

• packages/core/src/commands/registry.ts を新規作成する。
• 内部状態を Map<string, CommandEntry> とする。CommandEntry は { handler: CommandHandler; meta: CommandMeta } とする（遅延活性化フラグ lazy は本タスクの範囲外とし、導入しない）。
• ファクトリ関数 createCommandRegistry(deps: { log: HostLog; sink: StatusSink }) を提供する。依存は注入する。
• register(id, handler, meta?) を実装する。ID が既存の場合はハンドラを置き換える（last-wins）。置き換え時は log に警告を記録する。戻り値は Disposable とする。
• Disposable.dispose() は、その登録が現在の登録である場合にのみ Map から削除する。二重 dispose と、既に別ハンドラで再登録済みの場合は何もしない（no-op）。この判定にはエントリ同一性の比較を使う。
• execute(id, ...args) を async で実装し、例外を投げない。
  • ID が未登録の場合、HostError を作り message を Command not found: <id> として sink.error(...) へ送り、undefined を返す（Req 3.4）。
  • ハンドラを try/await/catch で実行する。例外時は catch の値（型は unknown）を安全に文字列化して HostError を作り、log に記録し、sink.error(...) へ送り、undefined を返す（Req 3.5）。catch 変数は unknown なので使用前に絞り込む。
  • 成功時はハンドラの戻り値を解決して返す。
• list() を実装する。各エントリから { id, title, category, when } を作って配列で返す。when によるフィルタは行わない（呼び出し側が行う）。
• 名前付きエクスポートのみを使う。export default は使わない。

Task 2: commands と core のエクスポートを配線する

新しいレジストリを外部から利用できるようにする。

• packages/core/src/commands/index.ts を更新する。プレースホルダ定数の代わりに registry.ts の公開シンボル（createCommandRegistry と関連型）を再エクスポートする。
• packages/core/src/index.ts を更新する。COMMANDS_PLACEHOLDER の再エクスポートを、commands モジュールの新しい公開シンボルの再エクスポートに置き換える。他モジュールのプレースホルダ再エクスポートは変更しない。
• インスタンス生成やモジュール間の合成配線は本タスクの範囲外とする。ファクトリのエクスポートのみを行う。

🤖 Prompt for AI agents

このフェーズでは、コマンドレジストリ本体を実装する。`register`／`execute`／`list` を提供し、core
のエクスポートに配線することが目的である。

タスク 1: `packages/core/src/commands/registry.ts` を新規作成する。
- 内部状態は `Map<string, CommandEntry>` とする。`CommandEntry` は `{ handler:
CommandHandler; meta: CommandMeta }` とする。遅延活性化フラグ `lazy` は導入しない。本タスクの範囲外である。
- ファクトリ関数 `createCommandRegistry(deps: { log: HostLog; sink: StatusSink })`
を実装する。依存は関数の引数として注入する。
- `register(id, handler, meta?)` を実装する。ID が既存の場合、ハンドラを置き換える（last-wins）。置き換え時は
`log` に警告を記録する。戻り値として `Disposable` を返す。
- `Disposable.dispose()` を実装する。その登録が現在の登録である場合にのみ `Map` から削除する。二重 dispose
の場合、何もしない。既に別ハンドラで再登録済みの場合も、何もしない。判定にはエントリ同一性の比較を使う。
- `execute(id, ...args)` を `async` 関数として実装する。例外は投げない。
- ID が未登録の場合、`message` を `Command not found: <id>` とした `HostError`
を作る。`sink.error(...)` へ送る。`undefined` を返す（Req 3.4）。
- ハンドラを `try/await/catch` で実行する。例外発生時、`catch` の値（型は
`unknown`）を安全に文字列化する。`HostError` を作る。`log` に記録する。`sink.error(...)`
へ送る。`undefined` を返す（Req 3.5）。`catch` 変数は `unknown` 型のため、使用前に型を絞り込む。
 - 成功時、ハンドラの戻り値を解決して返す。
- `list()` を実装する。各エントリから `{ id, title, category, when }` を作る。配列で返す。`when`
によるフィルタは行わない。フィルタは呼び出し側の責務とする。
- エクスポートは名前付きのみを使う。`export default` は使わない。

タスク 2: エクスポートを配線する。
- `packages/core/src/commands/index.ts` を更新する。プレースホルダ定数の代わりに、`registry.ts`
の公開シンボル（`createCommandRegistry` と関連型）を再エクスポートする。
- `packages/core/src/index.ts` を更新する。`COMMANDS_PLACEHOLDER` の再エクスポートを、`commands`
モジュールの新しい公開シンボルの再エクスポートに置き換える。他モジュールのプレースホルダ再エクスポートは変更しない。
- インスタンス生成やモジュール間の合成配線は行わない。本タスクの範囲外である。ファクトリのエクスポートのみを行う。

Phase 3: テスト

このフェーズでは、完了要件を満たす単体テストを追加する。

`registry.test.ts` を追加する

レジストリの主要な振る舞いを検証する。

• packages/core/src/commands/registry.test.ts を新規作成する。
• bun:test の import { expect, test } from "bun:test"; を使う。フラットな test(...) を並べる。
• テストではスタブの StatusSink（受け取った HostError を配列に記録する）と HostLog を注入する。
• 次のケースを検証する。
  • 未登録 ID を execute すると undefined を解決し、シンクに Command not found: <id> が届く。例外は投げない。
  • 例外を投げるハンドラを execute すると undefined を解決し、HostLog に記録され、シンクにエラーが届く。
  • register の戻り値を dispose するとコマンドが削除される。再度 execute すると未登録扱いになる。二重 dispose は何もしない。
  • 同一 ID を再登録すると last-wins でハンドラが置き換わり、HostLog に警告が記録される。
  • list() が { id, title, category, when } のメタデータを返す。
• 成功時にハンドラの戻り値が解決されることも 1 ケース加える。

🤖 Prompt for AI agents

このフェーズでは、コマンドレジストリの単体テストを追加する。目的は、完了要件を満たすことを検証することである。

タスク: `packages/core/src/commands/registry.test.ts` を新規作成する。
- `bun:test` から `import { expect, test } from "bun:test";` を使う。フラットな `test(...)`
を並べる形式にする。
- テストでは、スタブの `StatusSink`（受け取った `HostError` を配列に記録する）と `HostLog` を注入する。
- 次のケースを検証する。
- 未登録 ID を `execute` した場合、`undefined` を解決する。シンクに `Command not found: <id>`
が届く。例外は投げない。
 - 例外を投げるハンドラを `execute` した場合、`undefined` を解決する。`HostLog` に記録される。シンクにエラーが届く。
- `register` の戻り値を `dispose` した場合、コマンドが削除される。再度 `execute` すると未登録扱いになる。二重
`dispose` の場合、何もしない。
 - 同一 ID を再登録した場合、last-wins でハンドラが置き換わる。`HostLog` に警告が記録される。
 - `list()` を呼び出した場合、`{ id, title, category, when }` のメタデータを返す。
- 成功時にハンドラの戻り値が解決されることを検証するケースも 1 つ加える。

Research

このリポジトリは Bun ワークスペースのモノレポである。packages/api（@tecode/api）は公開型を提供する。packages/core（@tecode/core）は実装を持つ。@tecode/core は @tecode/api に workspace:* で依存する。

現在、packages/core/src/commands/index.ts、host/index.ts、api/index.ts などは、すべてプレースホルダ定数だけを持つ。Disposable、HostError、HostLog、ステータスシンクの型は、コードにまだ存在しない。

設計は design.md §5 と requirements.md Req 3.1–3.5 に記述がある。

テストは bun:test を使う。test(...) を並べる形式を使う。ソースと同じディレクトリに *.test.ts を置く。TypeScript は strict: true を使う。エクスポートは名前付きのみを使う。export default は使わない。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

このフェーズでは、コマンドレジストリが依存する公開型とエラー処理の仕組みを実装する。目的は、`@tecode/api`
に最小限の公開型を追加し、`@tecode/core` の host モジュールにエラー集約・通知の仕組みを用意することである。

タスク 1: `packages/api/src/index.ts` を更新する。
- `Disposable` 型を追加する。形は `{ dispose(): void }` とする。
- `CommandMeta` 型を追加する。`title?`、`category?`、`when?` を持たせる。すべて任意の `string`
とする（Req 3.3）。
- `CommandHandler` 型を追加する。シグネチャは `(...args: unknown[]) => unknown |
Promise<unknown>` とする。
- `CommandInfo` 型を追加する。形は `{ id: string; title?: string; category?: string;
when?: string }` とする。
- 既存のプレースホルダ定数は変更しないか、名前付きエクスポートの追加のみに留める。1.2 で計画されている全 API
サーフェスは実装しない。今回必要な範囲のみを実装する。

タスク 2: `packages/core/src/host/` に新規ファイル（例: `errors.ts`）を作成する。
- `HostError` 型を定義する。設計 §4.1 に合わせ `{ extensionId?: string; path?: string;
message: string }` とする。この型はコマンド失敗の表現にも再利用する。
- `HostLog` を定義する。構造化エラーを配列に蓄積する。エラーの追加と取得ができる最小実装とする。ファクトリ関数 `createHostLog()`
を提供する。
- `StatusSink` インターフェースを定義する。`HostError` を受け取るメソッド（例: `error(err: HostError):
void`）を 1 つ持つ。UI への実配線は本フェーズでは行わない。後続タスクで行う。
- テスト用のノーオペシンク（例: `createNoopStatusSink()`）を提供する。
- `HostError`、`HostLog`（および `createHostLog`）、`StatusSink`（および
`createNoopStatusSink`）を `packages/core/src/host/index.ts`
から名前付きで再エクスポートする。`export default` は使わない。
===============================================================================

Task: 2

このフェーズでは、コマンドレジストリ本体を実装する。`register`／`execute`／`list` を提供し、core
のエクスポートに配線することが目的である。

タスク 1: `packages/core/src/commands/registry.ts` を新規作成する。
- 内部状態は `Map<string, CommandEntry>` とする。`CommandEntry` は `{ handler:
CommandHandler; meta: CommandMeta }` とする。遅延活性化フラグ `lazy` は導入しない。本タスクの範囲外である。
- ファクトリ関数 `createCommandRegistry(deps: { log: HostLog; sink: StatusSink })`
を実装する。依存は関数の引数として注入する。
- `register(id, handler, meta?)` を実装する。ID が既存の場合、ハンドラを置き換える（last-wins）。置き換え時は
`log` に警告を記録する。戻り値として `Disposable` を返す。
- `Disposable.dispose()` を実装する。その登録が現在の登録である場合にのみ `Map` から削除する。二重 dispose
の場合、何もしない。既に別ハンドラで再登録済みの場合も、何もしない。判定にはエントリ同一性の比較を使う。
- `execute(id, ...args)` を `async` 関数として実装する。例外は投げない。
- ID が未登録の場合、`message` を `Command not found: <id>` とした `HostError`
を作る。`sink.error(...)` へ送る。`undefined` を返す（Req 3.4）。
- ハンドラを `try/await/catch` で実行する。例外発生時、`catch` の値（型は
`unknown`）を安全に文字列化する。`HostError` を作る。`log` に記録する。`sink.error(...)`
へ送る。`undefined` を返す（Req 3.5）。`catch` 変数は `unknown` 型のため、使用前に型を絞り込む。
 - 成功時、ハンドラの戻り値を解決して返す。
- `list()` を実装する。各エントリから `{ id, title, category, when }` を作る。配列で返す。`when`
によるフィルタは行わない。フィルタは呼び出し側の責務とする。
- エクスポートは名前付きのみを使う。`export default` は使わない。

タスク 2: エクスポートを配線する。
- `packages/core/src/commands/index.ts` を更新する。プレースホルダ定数の代わりに、`registry.ts`
の公開シンボル（`createCommandRegistry` と関連型）を再エクスポートする。
- `packages/core/src/index.ts` を更新する。`COMMANDS_PLACEHOLDER` の再エクスポートを、`commands`
モジュールの新しい公開シンボルの再エクスポートに置き換える。他モジュールのプレースホルダ再エクスポートは変更しない。
- インスタンス生成やモジュール間の合成配線は行わない。本タスクの範囲外である。ファクトリのエクスポートのみを行う。
===============================================================================

Task: 3

このフェーズでは、コマンドレジストリの単体テストを追加する。目的は、完了要件を満たすことを検証することである。

タスク: `packages/core/src/commands/registry.test.ts` を新規作成する。
- `bun:test` から `import { expect, test } from "bun:test";` を使う。フラットな `test(...)`
を並べる形式にする。
- テストでは、スタブの `StatusSink`（受け取った `HostError` を配列に記録する）と `HostLog` を注入する。
- 次のケースを検証する。
- 未登録 ID を `execute` した場合、`undefined` を解決する。シンクに `Command not found: <id>`
が届く。例外は投げない。
 - 例外を投げるハンドラを `execute` した場合、`undefined` を解決する。`HostLog` に記録される。シンクにエラーが届く。
- `register` の戻り値を `dispose` した場合、コマンドが削除される。再度 `execute` すると未登録扱いになる。二重
`dispose` の場合、何もしない。
 - 同一 ID を再登録した場合、last-wins でハンドラが置き換わる。`HostLog` に警告が記録される。
 - `list()` を呼び出した場合、`{ id, title, category, when }` のメタデータを返す。
- 成功時にハンドラの戻り値が解決されることを検証するケースも 1 つ加える。

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---