1.2 Define the @tecode/api type surface

[goofmint]

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

Summary

Author the complete public type surface in @tecode/api — the only package extensions may import — and enforce the layering rule with ESLint.

Details

• Types: Manifest, ExtensionContext, Disposable, Uri, Position / Range / TextEdit / Selection (0-based, LSP-compatible), the Document interface, event types, and the namespace interfaces for commands, workspace, window, editor, ui, config, context, languages, themes.
• UiColorKey union (~40 VS Code color names) and CaptureName union (tree-sitter capture names incl. dotted refinements).
• Export API_VERSION = "1.0" (major.minor).
• @tecode/api has an empty dependencies field and contains no runtime code beyond constants.
• Add ESLint no-restricted-imports forbidding @tecode/core imports outside packages/cli.

Completion requirements

• All namespaces from Req 10.1 are typed in @tecode/api
• @tecode/api has zero dependencies and no runtime logic (types + constants only)
• API_VERSION exported and documented (compat rule: same major, host minor >= requested)
• ESLint fails on a @tecode/core import from builtin (verified by a fixture or lint test)
• bun test and lint pass workspace-wide

References

• requirements.md: Req 1.3, 3.2, 3.3, 7.2, 10.1
• design.md: §2, §12

Dependencies

Blocked by: 1.1 (#2)

[goofmint]

@coderabbitai make plan in Japanese

---

Generated by Claude Code

[coderabbitai]

Coding Plan

Summary

• @tecode/api を単一 TS ソースにまとめ、型宣言と唯一の runtime 定数 API_VERSION のみを持たせ、依存ゼロを維持する。
• 基本プリミティブ(Position/Range/TextEdit/Selection/Uri/Disposable/Event/Document)を先に定義し、その上に Manifest・貢献スキーマ・9 名前空間インターフェースを積み上げる。
• UiColorKey は約 40 個を列挙し、CaptureName は基底名列挙＋template literal でドット精緻化を許容する。
• ESLint flat config の no-restricted-imports で @tecode/core を packages/cli 以外から禁止し、builtin フィクスチャで規則の実効性を検証する。

File-Level Changes(後続エージェント向け)

• packages/api/src/index.ts(新規): 全型(Manifest・ExtensionContext・Disposable・Uri・Position・Range・TextEdit・Selection・Document・イベント型・9 名前空間インターフェース・Tecode 統合型・UiColorKey・CaptureName・RGB・Style・ResolvedTheme・LanguageContribution)と定数 API_VERSION を定義・export する。
• packages/api/package.json(更新): dependencies を空に保ち、types/exports を公開エントリに向ける。main などの runtime エントリは追加しない。
• eslint.config.js(更新): no-restricted-imports を追加し、@tecode/core を packages/cli 以外で禁止する。
• packages/builtin/(新規フィクスチャまたはテスト): @tecode/core import が lint で失敗することを検証する。

follow-up 指示

• Req 10.1 のメンバ名と本 API の名前・シグネチャを完全一致させること。名前空間メンバの過不足を避けること。
• 定数以外の runtime code を @tecode/api に追加しないこと。
• UiColorKey の最終列挙は約 40 個とし、Req 7.2 の 6 例を必ず含めること。

Design Choices

Design Choice 1: `@tecode/api` のソース形式を `.ts` と `.d.ts` のどちらにするか

Options Considered:

1. .d.ts のみ(型専用)。定数は別途 .ts に置く。
2. 単一の .ts(index.ts)に型と API_VERSION 定数の両方を置く。

Chosen Option: 2

Rationale: ticket は「定数以外に runtime code を持たない」と要求する。API_VERSION は実行時定数である。純粋な .d.ts は定数を export できない。OpenTUI ランタイムローダは TS を直接読み込む。単一 .ts に集約すると定数と型を一箇所で管理でき、依存ゼロ制約も満たす。

Design Choice 2: `UiColorKey` と `CaptureName` の型表現をどうするか

Options Considered:

1. 両方とも文字列リテラルの完全列挙にする。
2. UiColorKey は約 40 個を列挙し、CaptureName は基底名の列挙に加えてドット精緻化を template literal 型(${Base}.${string})で許可する。

Chosen Option: 2

Rationale: ドキュメントは代表例のみを示す。完全な列挙は未定義である。VS Code の色キーは有限で安定するため列挙が妥当である。tree-sitter の capture 名はドット精緻化が言語ごとに増えるため、template literal 型で将来の refinement を許容する。

Design Choice 3: ESLint 設定形式をどうするか

Options Considered:

1. 従来の .eslintrc 形式。
2. Flat config(eslint.config.js)で files/ignores により packages/cli を除外し no-restricted-imports を適用する。

Chosen Option: 2

Rationale: 現行の ESLint 標準は flat config である。files/ignores で適用範囲を制御でき、no-restricted-imports.patterns で @tecode/core を禁止できる。

💡 User Tips

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

Implementation Steps

Phase 1: 基本型と API 定数の定義

このフェーズは型サーフェスの土台を作る。他のすべての名前空間型が参照する基本プリミティブと、バージョン定数を定義する。ここで依存ゼロと「定数以外の runtime code 無し」の制約を確立する。

Task 1: 基本プリミティブ型の定義

LSP 互換の位置・範囲・編集・選択の各型と、破棄・URI・イベントの各型を定義する。

• packages/api/src/ に型定義ソースを作成する。
• Position(0 始まりの line・character)、Range(start・end)、Selection、TextEdit(range・newText)を定義する。値は LSP 互換とする。
• Uri、Disposable(dispose(): void)、汎用 Event<T>(listener 登録で Disposable を返す)を定義する。
• これらは design.md §7 の TextEdit = { range, newText }・Range = { start, end } に一致させる。

Task 2: Document 型とドキュメントイベントの定義

開いているファイルを表す Document 型と関連イベント型を定義する。

• Document インターフェースを定義する。uri・languageId・version・dirty・readonly・eol("\n" | "\r\n")を持たせる。
• 変更を表す DocumentChangeEvent 型を定義する。
• 変更経路は applyEdits(edits: TextEdit[]) のみとする(Req 5.2)。他の変更 API は型に含めない。
• design.md §7.1 の Document 断片に一致させる。

Task 3: API_VERSION 定数の定義と互換規則の文書化

バージョン定数を export し、互換規則をコメントで記述する。

• API_VERSION = "1.0" を定数として export する。major.minor 形式とする。
• 互換規則をソース内コメントで記述する。規則は「major が一致し、host の minor が要求 minor 以上なら互換」とする(design.md §4.3)。
• この定数が唯一の runtime code である点をコメントで明示する。

🤖 Prompt for AI agents

型サーフェスの土台となる基本プリミティブ型とバージョン定数を実装する。`packages/api/src/` 配下に依存ゼロの TypeScript
ソースを作成する。

- `Position`(0 始まりの
`line`・`character`)、`Range`(`start`・`end`)、`Selection`、`TextEdit`(`range`・`newText`)を
LSP 互換の値として定義する。design.md §7 の `TextEdit = { range, newText }`・`Range = { start,
end }` に一致させる。
- `Uri`、`Disposable`(`dispose(): void`)、汎用 `Event<T>`(listener 登録で `Disposable`
を返す)を定義する。
- `Document`
インターフェースを定義する。`uri`・`languageId`・`version`・`dirty`・`readonly`・`eol`(`"\n" |
"\r\n"`)を持たせる。design.md §7.1 の `Document` 断片に一致させる。
- `DocumentChangeEvent` 型を定義する。変更経路は `applyEdits(edits: TextEdit[])` のみとし、他の変更
API は型に含めない(Req 5.2)。
- `API_VERSION = "1.0"` を定数として export する。major.minor
形式とする。互換規則をソース内コメントで記述する。規則は「major が一致し、host の minor が要求 minor
以上なら互換」とする(design.md §4.3)。この定数がパッケージ内で唯一の runtime code である点をコメントで明示する。

Phase 2: 名前空間・Manifest・テーマ/言語の型定義

このフェーズは Req 10.1 の全名前空間と、拡張機能マニフェストの契約型を定義する。テーマと言語の貢献スキーマ、色キーと capture 名の union もここで確定する。

Task 1: UiColorKey と CaptureName の union 定義

テーマで使う色キーと構文 capture 名の union 型を定義する。

• UiColorKey を約 40 個の VS Code 色名の文字列リテラル union として定義する。Req 7.2 の代表例(editor.background・editor.foreground・sideBar.background・statusBar.background・tab.activeBackground・list.activeSelectionBackground)を必ず含める。
• CaptureName を基底名の union(keyword・string・comment・function・type・variable・number・operator・punctuation を含む)と、ドット精緻化を許す template literal 型(例: ${BaseCapture}.${string})で構成する。
• テーマ解決結果 ResolvedTheme が参照する RGB 型と Style 型も定義する(design.md §9)。

Task 2: Manifest と貢献スキーマ、ExtensionContext の定義

マニフェスト構造、contributes サブフィールド、拡張コンテキストを定義する。

• Manifest を定義する。id・version・apiVersion・activationEvents・contributes を持たせる(Req 2.3・2.7)。
• activationEvents を onStartup と template literal onCommand:${string}・onLanguage:${string} の union として型付けする(Req 2.5)。
• contributes のサブフィールドを定義する。commands(id・title・category?・when?)、keybindings(key・command・when?)、views、languages、themes、configuration を含める。
• 言語貢献 LanguageContribution を定義する。id・extensions・grammar・highlights・comments・brackets を持たせる(Req 8.2)。
• テーマ貢献を name → JSON パスの形で定義する(Req 7.1)。
• ExtensionContext を定義する。api・extensionUri・subscriptions: Disposable[]・storagePath を持たせる(design.md §4.2)。
• コマンドメタデータ型に title・category・when を含める(Req 3.3)。コマンド ID は namespace.verb 規約であることをコメントで記す(Req 3.2)。

Task 3: 名前空間インターフェースと tecode 名前空間型の定義

Req 10.1 の 9 名前空間をインターフェースとして定義し、統合型を export する。

• 各名前空間インターフェースを定義する。メンバは Req 10.1 に厳密に一致させる。
  • commands: register・execute・list。register は Disposable を返す。
  • workspace: rootUri・openDocument・documents・fs(read/write/stat/readdir/watch)・onDidOpen/onDidClose/onDidSave。
  • window: activeEditor・showMessage・showQuickPick・showInputBox・setStatusBarItem。
  • editor: selections・cursor・revealLine・insertSnippet・applyEdits。
  • ui: registerView・useTheme・共通コンポーネント(List・Tree・Input・Tabs)。
  • config: get・onDidChange。
  • context: set・get。
  • languages: register・getLanguageId。register の引数は LanguageContribution を反映させる。
  • themes: register・current。
• 全名前空間を束ねる Tecode 型(または名前空間集合型)を定義し export する。この型が core/api/create.ts が構築する凍結オブジェクトの契約となる(design.md §12)。
• パッケージの公開エントリからすべての型と API_VERSION を再 export する。

🤖 Prompt for AI agents

Req 10.1 の全名前空間と、拡張機能マニフェストの契約型を実装する。テーマと言語の貢献スキーマ、色キーと capture 名の union
もこのフェーズで確定する。

- `UiColorKey` を約 40 個の VS Code 色名の文字列リテラル union として定義する。Req 7.2
の代表例(`editor.background`・`editor.foreground`・`sideBar.background`・`statusBar.background`・`tab.activeBackground`・`list.activeSelectionBackground`)を必ず含める。
- `CaptureName` を基底名の
union(`keyword`・`string`・`comment`・`function`・`type`・`variable`・`number`・`operator`・`punctuation`
を含む)と、ドット精緻化を許す template literal 型(例: `${BaseCapture}.${string}`)で構成する。
- `ResolvedTheme` が参照する `RGB` 型と `Style` 型を定義する(design.md §9)。
- `Manifest` を定義する。`id`・`version`・`apiVersion`・`activationEvents`・`contributes`
を持たせる(Req 2.3・2.7)。`activationEvents` は `onStartup` と template literal
`onCommand:${string}`・`onLanguage:${string}` の union とする(Req 2.5)。
- `contributes`
のサブフィールドを定義する。`commands`(`id`・`title`・`category?`・`when?`)、`keybindings`(`key`・`command`・`when?`)、`views`、`languages`、`themes`、`configuration`
を含める。
- `LanguageContribution`
を定義する。`id`・`extensions`・`grammar`・`highlights`・`comments`・`brackets` を持たせる(Req
8.2)。
- テーマ貢献を `name` → JSON パスの形で定義する(Req 7.1)。
- `ExtensionContext` を定義する。`api`・`extensionUri`・`subscriptions:
Disposable[]`・`storagePath` を持たせる(design.md §4.2)。コマンドメタデータ型に
`title`・`category`・`when` を含める(Req 3.3)。コマンド ID は `namespace.verb`
規約である旨をコメントで記す(Req 3.2)。
- Req 10.1 の 9
名前空間(`commands`・`workspace`・`window`・`editor`・`ui`・`config`・`context`・`languages`・`themes`)をインターフェースとして定義する。メンバは
Req 10.1 に厳密に一致させ、過不足を避ける。
- 全名前空間を束ねる `Tecode` 型(または名前空間集合型)を定義し export する。この型は `core/api/create.ts`
が構築する凍結オブジェクトの契約となる(design.md §12)。
- パッケージの公開エントリからすべての型と `API_VERSION` を再 export する。

Phase 3: レイヤリング規則の ESLint 適用と検証

このフェーズは @tecode/core を packages/cli 以外から import することを禁止する規則を導入する。規則の実効性をフィクスチャまたは lint テストで検証する。

Task 1: no-restricted-imports レイヤリング規則の追加

ワークスペースの ESLint 設定に import 制限を追加する。

• ルート ESLint flat config(eslint.config.js)を更新する。
• no-restricted-imports を patterns で設定し、@tecode/core と @tecode/core/* の import を禁止する。
• 適用範囲を files: ["packages/**/*.{ts,tsx}"] とし、ignores: ["packages/cli/**"] で cli を除外する。
• 違反時のメッセージに「拡張と core の境界を越える呼び出しは command registry を経由する」旨を含める。
• この規則は Task 1.2 着地後、以降の全タスクのブロッキングゲートになる点を README またはコメントで明示する。

Task 2: レイヤリング規則の検証テスト

規則が builtin からの @tecode/core import を実際に失敗させることを検証する。

• packages/builtin/ 配下に検証用フィクスチャを置く、または lint 実行を確認する bun test を追加する。
• フィクスチャは @tecode/core を import し、lint がエラーを返すことを確認する。
• cli からの @tecode/core import はエラーにならないことも確認する。
• ワークスペース全体で bun test と lint が通ることを最終確認する。

🤖 Prompt for AI agents

`@tecode/core` を `packages/cli` 以外から import することを禁止する ESLint
規則を導入し、規則の実効性をフィクスチャまたは lint テストで検証する。

- ルート ESLint flat config(`eslint.config.js`)を更新する。
- `no-restricted-imports` を `patterns` で設定し、`@tecode/core` と `@tecode/core/*` の
import を禁止する。
- 適用範囲を `files: ["packages/**/*.{ts,tsx}"]` とし、`ignores: ["packages/cli/**"]` で
`cli` を除外する。
- 違反時のメッセージに「拡張と core の境界を越える呼び出しは command registry を経由する」旨を含める。
- この規則が以降の全タスクのブロッキングゲートになる点を README またはコメントで明示する。
- `packages/builtin/` 配下に検証用フィクスチャを置く、または lint 実行を確認する `bun test` を追加する。フィクスチャは
`@tecode/core` を import し、lint がエラーを返すことを確認する。
- `cli` からの `@tecode/core` import はエラーにならないことも確認する。
- ワークスペース全体で `bun test` と lint が通ることを最終確認する。

Research

本プロジェクトは Bun workspaces モノレポである。packages/ 配下に api、core、builtin、cli の 4 パッケージを持つ。

• @tecode/api は型宣言と定数のみを持ち、依存ゼロである。
• @tecode/core は api にのみ依存する。
• builtin 拡張は api のみを import し、core を直接 import しない。
• cli は配線のみを持つ。

型サーフェスの契約は requirements.md の Req 10.1 が列挙し、具体的な型断片は design.md の §4・§7〜§10 に散在する。UiColorKey と CaptureName の完全な列挙はどのドキュメントにも無く、本タスクで確定する。本タスクは Task 1.1(モノレポ scaffold)に依存する。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

型サーフェスの土台となる基本プリミティブ型とバージョン定数を実装する。`packages/api/src/` 配下に依存ゼロの TypeScript
ソースを作成する。

- `Position`(0 始まりの
`line`・`character`)、`Range`(`start`・`end`)、`Selection`、`TextEdit`(`range`・`newText`)を
LSP 互換の値として定義する。design.md §7 の `TextEdit = { range, newText }`・`Range = { start,
end }` に一致させる。
- `Uri`、`Disposable`(`dispose(): void`)、汎用 `Event<T>`(listener 登録で `Disposable`
を返す)を定義する。
- `Document`
インターフェースを定義する。`uri`・`languageId`・`version`・`dirty`・`readonly`・`eol`(`"\n" |
"\r\n"`)を持たせる。design.md §7.1 の `Document` 断片に一致させる。
- `DocumentChangeEvent` 型を定義する。変更経路は `applyEdits(edits: TextEdit[])` のみとし、他の変更
API は型に含めない(Req 5.2)。
- `API_VERSION = "1.0"` を定数として export する。major.minor
形式とする。互換規則をソース内コメントで記述する。規則は「major が一致し、host の minor が要求 minor
以上なら互換」とする(design.md §4.3)。この定数がパッケージ内で唯一の runtime code である点をコメントで明示する。
===============================================================================

Task: 2

Req 10.1 の全名前空間と、拡張機能マニフェストの契約型を実装する。テーマと言語の貢献スキーマ、色キーと capture 名の union
もこのフェーズで確定する。

- `UiColorKey` を約 40 個の VS Code 色名の文字列リテラル union として定義する。Req 7.2
の代表例(`editor.background`・`editor.foreground`・`sideBar.background`・`statusBar.background`・`tab.activeBackground`・`list.activeSelectionBackground`)を必ず含める。
- `CaptureName` を基底名の
union(`keyword`・`string`・`comment`・`function`・`type`・`variable`・`number`・`operator`・`punctuation`
を含む)と、ドット精緻化を許す template literal 型(例: `${BaseCapture}.${string}`)で構成する。
- `ResolvedTheme` が参照する `RGB` 型と `Style` 型を定義する(design.md §9)。
- `Manifest` を定義する。`id`・`version`・`apiVersion`・`activationEvents`・`contributes`
を持たせる(Req 2.3・2.7)。`activationEvents` は `onStartup` と template literal
`onCommand:${string}`・`onLanguage:${string}` の union とする(Req 2.5)。
- `contributes`
のサブフィールドを定義する。`commands`(`id`・`title`・`category?`・`when?`)、`keybindings`(`key`・`command`・`when?`)、`views`、`languages`、`themes`、`configuration`
を含める。
- `LanguageContribution`
を定義する。`id`・`extensions`・`grammar`・`highlights`・`comments`・`brackets` を持たせる(Req
8.2)。
- テーマ貢献を `name` → JSON パスの形で定義する(Req 7.1)。
- `ExtensionContext` を定義する。`api`・`extensionUri`・`subscriptions:
Disposable[]`・`storagePath` を持たせる(design.md §4.2)。コマンドメタデータ型に
`title`・`category`・`when` を含める(Req 3.3)。コマンド ID は `namespace.verb`
規約である旨をコメントで記す(Req 3.2)。
- Req 10.1 の 9
名前空間(`commands`・`workspace`・`window`・`editor`・`ui`・`config`・`context`・`languages`・`themes`)をインターフェースとして定義する。メンバは
Req 10.1 に厳密に一致させ、過不足を避ける。
- 全名前空間を束ねる `Tecode` 型(または名前空間集合型)を定義し export する。この型は `core/api/create.ts`
が構築する凍結オブジェクトの契約となる(design.md §12)。
- パッケージの公開エントリからすべての型と `API_VERSION` を再 export する。
===============================================================================

Task: 3

`@tecode/core` を `packages/cli` 以外から import することを禁止する ESLint
規則を導入し、規則の実効性をフィクスチャまたは lint テストで検証する。

- ルート ESLint flat config(`eslint.config.js`)を更新する。
- `no-restricted-imports` を `patterns` で設定し、`@tecode/core` と `@tecode/core/*` の
import を禁止する。
- 適用範囲を `files: ["packages/**/*.{ts,tsx}"]` とし、`ignores: ["packages/cli/**"]` で
`cli` を除外する。
- 違反時のメッセージに「拡張と core の境界を越える呼び出しは command registry を経由する」旨を含める。
- この規則が以降の全タスクのブロッキングゲートになる点を README またはコメントで明示する。
- `packages/builtin/` 配下に検証用フィクスチャを置く、または lint 実行を確認する `bun test` を追加する。フィクスチャは
`@tecode/core` を import し、lint がエラーを返すことを確認する。
- `cli` からの `@tecode/core` import はエラーにならないことも確認する。
- ワークスペース全体で `bun test` と lint が通ることを最終確認する。

💡 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.

---