docs: add contents and ideas

docs/.vitepress/config/ja.ts

@@ -67,8 +67,8 @@ export const jaConfig = defineConfig({
             text: 'プロジェクトのセットアップ',
             link: '/ja/hands-on/project-setup',
           },
-          // { text: 'Hello, chibivite!', link: '/ja/hands-on/hello-chibivite' },
-          // { text: 'chibivite CLI', link: '/ja/hands-on/chibivite-cli' },
+          { text: 'Hello, chibivite!', link: '/ja/hands-on/hello-chibivite' },
+          // { text: 'chibivite CLIのビルド', link: '/ja/hands-on/cli-build-setup' },
         ],
       },
     ],

docs/content/ja/hands-on/cli-build-setup.draft.md

@@ -0,0 +1,219 @@
+# chibivite CLIのビルド
+
+::: tip このページのゴール
+✅ chibivite CLIをTypeScriptで実装してビルドできるようにしましょう
+:::
+
+chibivite CLIの詳細をTypeScriptで実装できるようにして、より堅牢なコードベースで開発できるようにしましょう！
+
+このハンズオンでは、Viteと同様に[Rollup](https://rollupjs.org/)を使ってビルドをおこないます。
+
+---
+
+まずは、Rollupをインストールして基本のビルドパイプラインを設定しましょう！
+
+```bash
+cd packages/chibivite
+```
+
+```bash
+pnpm install [email protected]
+```
+
+::: info パッケージのバージョンについて
+ほとんどのパッケージは[セマンティックバージョニング](https://semver.org/)を採用しているため、マイナーバージョンの差分は安全に適用することができます。実際のところ、Rollupのバージョンを指定せずに以下のようにインストールしても、それがRollup v4系であれば基本的には問題ありません。
+
+```bash
+pnpm install rollup
+```
+
+しかし、マイナーバーアップデートに破壊的変更が含まれている可能性があります。このハンズオンでは、このハンズオンにしたがって開発したchibiviteが将来にわたって動作することを保証するため、すべての依存パッケージのバージョンを指定してインストールします。
+:::
+
+以下のように `package.json` が書きかわっていれば成功です。
+
+<!-- prettier-ignore -->
+```json
+{
+  // ...
+  "dependencies": {},   // [!code --]
+  "dependencies": {     // [!code ++]
+    "rollup": "4.17.2"  // [!code ++]
+  },                    // [!code ++]
+  // ...
+}
+```
+
+つぎに、`rollup.config.mjs` を作成して、以下のコードをコピーしましょう。
+
+```js{8-12}
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'rollup'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+export default defineConfig({
+  input: path.resolve(__dirname, 'src/cli.mjs'),
+  output: {
+    dir: './dist',
+    format: 'esm'
+  }
+})
+```
+
+Rollupでビルドをおこなうためには、入力元（エントリーポイント）と出力パス、そして出力形式の設定が必要です。
+それぞれ、`input` オプション、`output.dir`オプション、`output.format`オプションに対応しています。
+
+::: details `__dirname` について
+`rollup.config.mjs`はECMAScript Module（ESM）であるため、CommonJS Moduleが提供している[`__dirname`](https://nodejs.org/docs/latest/api/modules.html#__dirname)定数が利用できません。
+ESMでは、代わりに `fileURLToPath(new URL('.', import.meta.url))` のイディオムを使って同様の値を得ることができます。
+今後、このイディオムを毎回記述しなくてすむように、`__dirname` という名前の変数に代入して利用しています。
+
+結果として、`path.resolve(__dirname, 'src/cli.mjs')` は `/path/from/root/dir/to/packages/chibivite/src/cli.mjs` に解決されます。
+:::
+
+`src/cli.mjs` はまだ存在しないため、ファイルを作成して、以下のコードをコピーしましょう。
+
+```js
+console.log('Hello, chibivite!')
+```
+
+<!-- このコードは `packages/chibivite/bin/chibivite.js` のコードから[shebang](https://en.wikipedia.org/wiki/Shebang_(Unix))を除いたものです。`bin/chibivite.js`を書きかえて、ビルドされた -->
+
+Rollupを実行できるようにnpm scriptを定義しましょう。
+
+<!-- prettier-ignore -->
+```json
+{
+  // ...
+  "scripts": {},                                 // [!code --]
+  "scripts": {                                   // [!code ++]
+    "build": "rollup --config rollup.config.mjs" // [!code ++]
+  },                                             // [!code ++]
+  // ...
+}
+```
+
+この状態で以下のコマンドを実行してみましょう。`dist/cli.js`が作成されれば成功です。
+
+```bash
+pnpm run build
+```
+
+以下のコマンドで、ビルドされた `dist/cli.js` を実行してみましょう。ターミナルに `Hello, chibivite!` と表示されれば成功です。
+
+```bash
+node dist/cli.js
+```
+
+`bin/chibivite.js`を以下のように変更して、`bin/chibivite.js`から`dist/cli.js`を呼び出すようにしましょう。これで、プレイグラウンドでビルドしたCLIを利用できるようになります。
+
+```js
+#!/usr/bin/env node
+
+function start() {
+  console.log('Hello, chibivite!') // [!code --]
+  return import('../dist/node/cli.js') // [!code ++]
+}
+
+start()
+```
+
+プレイグラウンドで以下のコマンドを実行してみましょう。ターミナルに `Hello, chibivite!` と表示されれば成功です。
+
+```bash
+cd path/to/playground
+```
+
+```bash
+pnpm run dev
+```
+
+::: info なぜ`bin/chibivite.js`としてビルドしないのか
+Rollupを以下のように設定してビルドの出力先を直接 `bin/chibivite.js` にしても、プレイグラウンドでビルドしたCLIを利用できます（[shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>)のあつかいは省略しています）。
+
+```js
+export default defineConfig({
+  input: path.resolve(__dirname, 'src/cli.mjs'),
+  output: {
+    dir: './bin',
+    entryFileNames: 'chibivite.js',
+    format: 'esm',
+  },
+})
+```
+
+このハンズオンでは、Viteにならいビルドの出力先を別途設定しています。くわしくは[コマンドラインインターフェース](/ja/concepts/command-line-interface)のページを参照してください。
+:::
+
+---
+
+ここから、TypeScriptをJavaScriptにトランスパイルするための設定をしていきましょう！
+
+まず、Rollupを使ってTypeScriptをトランスパイルするために必要なパッケージをインストールしましょう。
+
+```bash
+pnpm install -D @rollup/[email protected] [email protected]
+```
+
+以下のように `package.json` が書きかわっていれば成功です。
+
+<!-- prettier-ignore -->
+```json
+{
+  // ...
+  "devDependencies": {}                    // [!code --]
+  "devDependencies": {                     // [!code ++]
+    "@rollup/plugin-typescript": "11.1.6", // [!code ++]
+    "tslib": "2.6.2"                       // [!code ++]
+  }                                        // [!code ++]
+}
+```
+
+つぎに、`rollu.config.mjs`を以下のように書きかえ、`src/cli.mjs` を `src/cli.ts` にリネームしてTypeScriptファイルにしましょう。
+
+```js
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'rollup'
+import typescript from '@rollup/plugin-typescript' // [!code ++]
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+export default defineConfig({
+  input: path.resolve(__dirname, 'src/cli.mjs'), // [!code --]
+  input: path.resolve(__dirname, 'src/cli.ts'), // [!code ++]
+  output: {
+    dir: './dist',
+    format: 'esm',
+  },
+  plugins: [
+    // [!code ++]
+    typescript(), // [!code ++]
+  ], // [!code ++]
+})
+```
+
+```bash
+mv src/cli.mjs src/cli.ts
+```
+
+では、Rollupでビルドしてみましょう。ただし、`src/cli.ts`のコードにTypeScript特有の内容がふくまれていないため、トランスパイルできているかを確かめることができません。検証のため、以下のようにコードを書き換えてビルドしてみましょう。`dist/cli.js`で型宣言が消えていれば成功です。
+
+```js
+type MyType = true // [!code ++]
+console.log('Hello, chibivite!')
+```
+
+```bash
+pnpm run build
+```
+
+検証がおわったら、型宣言は`src/cli.ts`から削除しましょう。
+
+TODO: tsconfig.jsonのセットアップ
+
+---
+
+おめでとうございます！これでchibivite CLIをTypeScriptで実装してビルドできるようになりました！🎉

docs/content/ja/hands-on/hello-chibivite.draft.md → docs/content/ja/hands-on/hello-chibivite.md

@@ -1,7 +1,7 @@
 # Hello, chibivite!
 
 ::: tip このページのゴール
-✅ chibiviteのパッケージ[コマンドラインインターフェース](/ja/concepts/command-line-interface)を実装しましょう
+✅ chibiviteの[コマンドラインインターフェース](/ja/concepts/command-line-interface)を実装しましょう
 
 ✅ chibiviteを実際に動作させることができるプレイグラウンドを立ち上げましょう
 :::
@@ -24,21 +24,14 @@ start()
 
 chibiviteをパッケージマネージャーでインストールした開発者がこのファイルを実行できるようにするため、`package.json` に以下の内容を設定しましょう。
 
+<!-- prettier-ignore -->
 ```json
 {
-  "name": "chibivite",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=20.12.0"
-  },
+  // ...
   "packageManager": "[email protected]",
   "bin": "bin/chibivite.js", // [!code ++]
   "scripts": {},
-  "dependencies": {},
-  "devDependencies": {}
+  // ...
 }
 ```
 
@@ -58,6 +51,7 @@ packages:
 
 つぎに `playground/package.json` を作成して、以下のコードをコピーしましょう。
 
+<!-- prettier-ignore -->
 ```json
 {
   "name": "playground",
@@ -97,18 +91,12 @@ pnpm install
 <!-- prettier-ignore -->
 ```json
 {
-  "name": "playground",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "sideEffects": false,
+  // ...
   "scripts": {},       // [!code --]
   "scripts": {         // [!code ++]
     "dev": "chibivite" // [!code ++]
   },                   // [!code ++]
-  "devDependencies": {
-    "chibivite": "workspace:*"
-  }
+  // ...
 }
 ```
 
@@ -120,4 +108,4 @@ pnpm run dev
 
 ---
 
-おめでとうございます！これでchibiviteパッケージをインストールして `chibivite` コマンドを利用できるようになりました！🎉
+おめでとうございます！これでchibivite CLIをプレイグラウンドで利用できるようになりました！🎉