akari-video 0.1.5 → 0.1.7

package/README.md

@@ -31,11 +31,26 @@ akari
         （PATH に opencode が無ければ、インストール案内を出して終了する）
 ```
 
-サブコマンド: `akari update`（更新確認）/ `akari init`（作業場の作成・確認のみ）/
+install.sh 経由インストール（`~/.akari/app`）では、新版の検知・裏 staging DL・sha256 検証・
+次回起動時の自動適用がすべて既定で走る（`AKARI_NO_AUTO_UPDATE=1` で無効化可）。起動を
+ブロックすることは無く、適用は次回起動の頭でアトミックにスワップする（`src/update-check.mjs`
+の `maybeStageInBackground` / `maybeApplyPendingUpdateOnLaunch`、実体は `src/self-update.mjs`
+の `stageSelfUpdate` / `swapStagedApp`）。
+
+サブコマンド: `akari update`（オンデマンドの確認・適用。install.sh 経由インストールなら
+DL・sha256 検証・適用まで実行。それ以外（npm グローバル / git checkout）や旧フィードでは
+更新案内のみ表示。`--rollback` で直前 1 世代へ戻す。`src/self-update.mjs`）/
+`akari init`（作業場の作成・確認のみ）/
+`akari new <target-dir> [--template <path>]`（新規プロジェクト作成）/
+`akari narration generate ...`（VOICEVOX / fal-qwen3 ナレーション生成）/
+`akari internal beat-sync-<beatmap|probe-frame|render-when-idle> ...`（beat-sync-edit 内部実行物）/
 `akari sounds [--variant wav] [--force]`（公式音源の一括ダウンロード。プロンプトなし・headless 可）/
 `akari store <connect|status|download|disconnect>`（AKARI Store 連携。マイページで発行した
 接続トークンを `~/.akari/store-credentials.json`（0600）に保存し、購入済み一覧の確認と
-配布物の取得ができる。`src/store-command.mjs`）。
+配布物の取得ができる。`src/store-command.mjs`）/
+`akari assets <list|fetch|sync|...>`（素材カタログの一覧・取得・同期。
+`packages/asset-resolver` の CLI への薄い委譲で、カタログ合成・entitlements 判定・
+sha256 検証・fail-closed は resolver 側の責務のまま。`src/assets-command.mjs`）。
 
 `akari` に渡した引数はそのまま `opencode` に転送する（例: `akari --continue` は
 `opencode --continue` を起動する）。
@@ -67,7 +82,7 @@ AKARI Video は「同じファイル契約（`.akari/` 配下の JSON）に収
 | アプリ | 接続ボタン（AKARI Video アプリ） | アプリの「はじめる」画面から接続 → はじめかた選択 |
 
 3 つとも最終的に同じもの（`.akari/connections.json` / `.akari/intake.json` /
-`skills/create-project`）を読み書きするため、どの入口から始めても続きは他の入口から
+`akari new` が使う共通 project-scaffold）を読み書きするため、どの入口から始めても続きは他の入口から
 再開できる。
 
 ## インストール

package/bin/akari.mjs

@@ -1,25 +1,72 @@
 #!/usr/bin/env node
 import { run, runUpdateCommand } from '../src/cli.mjs';
 import { runInitCommand } from '../src/init-command.mjs';
+import { runNewCommand } from '../src/new-command.mjs';
+import { runNarrationCommand } from '../src/narration-command.mjs';
+import { runInternalCommand } from '../src/internal-command.mjs';
 import { runSoundsCommand } from '../src/sounds-setup.mjs';
 import { runStatusCommand } from '../src/status-command.mjs';
 import { runAcceptCommand } from '../src/accept-command.mjs';
 import { runCapabilityCommand } from '../src/capability-command.mjs';
 import { runStoreCommand } from '../src/store-command.mjs';
+import { runAssetsCommand } from '../src/assets-command.mjs';
+import { maybeApplyPendingUpdateOnLaunch, readOwnVersion } from '../src/update-check.mjs';
+import { describeCliHelp } from '../src/messages.mjs';
+
+// `akari --version` / `-v`: インストール済みの版を表示するだけの最小コマンド
+// （タスク契約 2026-08-11-update-u4-cli-self-update の受け入れ条件 —
+// `akari update` / `--rollback` 後にインストール先の版を観測する手段として必要）。
+async function printVersion() {
+  console.log(`v${readOwnVersion()}`);
+  return { exitCode: 0 };
+}
+
+// `akari --help` / `-h`: 引数なしのトップレベル一覧を表示するだけの最小コマンド
+// （タスク契約 2026-08-11-onboarding-o3-firstrun-plain §4。それ以前はこの分岐が無く、
+// `--help` は claude/opencode へそのまま転送されてしまっていた — AKARI Video 自身の
+// コマンド一覧が一度も出ない行き止まりだったため新設した）。
+async function printCliHelp() {
+  for (const line of describeCliHelp()) {
+    console.log(line);
+  }
+  return { exitCode: 0 };
+}
+
+// 起動の頭で保留中の自動適用があれば適用する（契約 §11・タスク契約
+// 2026-08-11-update-u5-cli-auto-update）。すべてのサブコマンド分岐より前に置く —
+// 「起動」＝ akari バイナリの実行そのものであり、`--version` や `akari update` の
+// 入口でも既に新版へ切り替わっている必要がある（受け入れ条件: 2 回目の起動で
+// `akari --version` が新版を返す。スワップは rename ベースで `~/.akari/app` の
+// 実体を差し替えるだけなので、このプロセス自身がこの後 `readOwnVersion()` を
+// 読み直せば新版の内容を観測できる — 同一 argv での re-exec はしない設計判断
+// （理由は report.md 参照）)。失敗は他の起動時副作用と同じく握りつぶし、
+// claude/opencode 起動やサブコマンド実行を止めない。
+try {
+  maybeApplyPendingUpdateOnLaunch({ env: process.env, log: (line) => console.log(line) });
+} catch (error) {
+  console.error(`自動更新の適用確認でエラーが発生しました（続行します）: ${error instanceof Error ? error.message : String(error)}`);
+}
 
 const argv = process.argv.slice(2);
-// `akari update` / `akari init` / `akari sounds` / `akari status` / `akari accept` /
-// `akari capability` / `akari store` は claude へ転送せず、
-// 専用のサブコマンドとして扱う（契約 §4-1 / タスク契約 launcher-init（内部リポ）/
-// 音源カタログ既定化のオーナー裁定 2026-08-03 / AKARI Store 連携）。
+// `akari update` / `akari init` / `akari new` / `akari narration` / `akari internal` /
+// `akari sounds` / `akari status` / `akari accept` / `akari capability` / `akari store` /
+// `akari assets` は claude へ転送せず、専用のサブコマンドとして扱う（契約 §4-1 /
+// タスク契約 launcher-init（内部リポ）/ 音源カタログ既定化のオーナー裁定 2026-08-03 /
+// AKARI Store 連携 / タスク契約 2026-08-09-agent-assets-discovery）。
 // それ以外の引数はすべて従来どおり claude へ転送する。
-const invoke = argv[0] === 'update' ? runUpdateCommand(argv.slice(1))
+const invoke = (argv[0] === '--version' || argv[0] === '-v') ? printVersion()
+  : (argv[0] === '--help' || argv[0] === '-h') ? printCliHelp()
+  : argv[0] === 'update' ? runUpdateCommand(argv.slice(1))
   : argv[0] === 'init' ? runInitCommand(argv.slice(1))
+  : argv[0] === 'new' ? runNewCommand(argv.slice(1))
+  : argv[0] === 'narration' ? runNarrationCommand(argv.slice(1))
+  : argv[0] === 'internal' ? runInternalCommand(argv.slice(1))
   : argv[0] === 'sounds' ? runSoundsCommand(argv.slice(1))
   : argv[0] === 'status' ? runStatusCommand(argv.slice(1))
   : argv[0] === 'accept' ? runAcceptCommand(argv.slice(1))
   : argv[0] === 'capability' ? runCapabilityCommand(argv.slice(1))
   : argv[0] === 'store' ? runStoreCommand(argv.slice(1))
+  : argv[0] === 'assets' ? runAssetsCommand(argv.slice(1))
   : run(argv);
 
 const result = await invoke.catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {

package/src/assets-command.mjs

@@ -0,0 +1,42 @@
+import { spawnSync } from 'node:child_process';
+
+import { resolveLauncherAssets } from './repo-assets.mjs';
+import { assetsResolverUnavailableError } from './messages.mjs';
+
+/**
+ * `akari assets <list|fetch|sync|...>` — `packages/asset-resolver` の CLI
+ * （`bin/akari-assets.mjs`）への薄い委譲（タスク契約 2026-08-09-agent-assets-discovery）。
+ *
+ * カタログ合成・entitlements 判定・取得・sha256 検証・validate-asset・fail-closed の実ロジックは
+ * すべて resolver 側の責務のまま変更しない。認証（`~/.akari/store-credentials.json`）も
+ * resolver がそのまま読む。ここでは引数をそのまま子プロセスへ転送し、resolver 側の usage /
+ * エラー文言 / exit code をそのまま利用者に返すだけ。
+ *
+ * 規約は他の launcher 委譲コマンド（`akari sounds` = sounds-setup.mjs）と同じ:
+ *   - 同梱の実体解決は `resolveLauncherAssets()`（モノレポ checkout → npm 配布時の vendor/）
+ *   - 副作用（spawn）は options で注入可能・node --test で実プロセス不要
+ */
+
+function defaultSpawnAssetsCli(cliPath, args, env) {
+  // stdio: inherit — list の一覧表示・fetch の進捗ログ・JSON 出力をそのまま利用者に見せる
+  // （sounds-setup.mjs の defaultSpawnFetch と同じ流儀）。env を明示的に渡すのは必須 —
+  // 注入された AKARI_HOME（テスト・隔離実行）が resolver 側の解決にも効くようにする。
+  return spawnSync(process.execPath, [cliPath, ...args], { stdio: 'inherit', env });
+}
+
+export async function runAssetsCommand(args, options = {}) {
+  const logError = options.logError ?? ((line) => console.error(line));
+  const env = options.env ?? process.env;
+  const assets = options.assets ?? resolveLauncherAssets();
+
+  const cliPath = assets?.assetResolverCliPath;
+  if (!cliPath) {
+    logError(assetsResolverUnavailableError());
+    return { exitCode: 1 };
+  }
+
+  const spawnAssetsCli = options.spawnAssetsCli ?? defaultSpawnAssetsCli;
+  const result = spawnAssetsCli(cliPath, args, env);
+  const exitCode = typeof result.status === 'number' ? result.status : (result.error ? 1 : 0);
+  return { exitCode };
+}

package/src/cli.mjs

@@ -11,12 +11,15 @@ import { resolveEffectiveProjectRoot } from './first-run.mjs';
 import { maybeShowAssetIntroNotice } from './sounds-setup.mjs';
 import {
   checkForUpdateSync,
+  compareVersions,
+  isValidFeedShape,
   readCacheSync,
   readOwnVersion,
   recordDismissalSync,
   resolveCachePath,
   triggerBackgroundRefresh
 } from './update-check.mjs';
+import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self-update.mjs';
 
 /**
  * `akari` ランチャーの本体。3 入口契約（ターミナル `akari` / セッション内 `/akari` /
@@ -173,11 +176,15 @@ function defaultSpawnOpencode(opencodePath, args, projectRoot) {
 }
 
 /**
- * `akari update`: 現在版・最新版・リリースノート URL を表示し、更新手順を**案内するだけ**
- * （自動実行はしない — 契約 §4-1）。`--dismiss` を渡すと、キャッシュに載っている最新版の
- * 通知を今後出さないよう記録する。ネットワークには一切触れない
- * （表示に使う情報はすべて既存キャッシュ由来 — 最新情報は `akari` 起動時のバックグラウンド
- * fetch で更新される）。
+ * `akari update`: 新版があり、かつ自己更新の対象（app 経由実行 + フィードに
+ * `components.app` がある）なら DL → sha256 検証 → 適用まで実行する（契約 §11。
+ * 「update は明示操作」なので U2 の沈黙原則は適用せず、失敗は必ず表示する）。
+ * 対象外（npm グローバル / git checkout・旧フィード）のときは従来どおり
+ * **案内するだけ**（自動実行はしない — 契約 §4-1）に縮退する。`--dismiss` は
+ * 自己更新を試みず、キャッシュに載っている最新版の通知を今後出さないよう記録するだけ
+ * （既存挙動を維持）。`--rollback` は直前 1 世代（`~/.akari/app-previous/`）へ戻す。
+ * ネットワークに触れるのは自己更新の DL 区間のみ — フィード自体は既存キャッシュ由来
+ * （最新情報は `akari` 起動時のバックグラウンド fetch で更新される）。
  */
 export async function runUpdateCommand(args, options = {}) {
   const log = options.log ?? ((line) => console.log(line));
@@ -186,16 +193,44 @@ export async function runUpdateCommand(args, options = {}) {
   const cachePath = resolveCachePath(env);
   const cache = readCacheSync(cachePath);
   const dismissRequested = args.includes('--dismiss');
+  const rollbackRequested = args.includes('--rollback');
 
-  let dismissed = false;
-  if (dismissRequested && typeof cache?.feed?.product === 'string') {
-    recordDismissalSync({ version: cache.feed.product, env });
-    dismissed = true;
+  if (rollbackRequested) {
+    return (options.rollbackSelfUpdate ?? rollbackSelfUpdate)({ env, log });
   }
 
-  const finalCache = dismissed ? readCacheSync(cachePath) : cache;
-  for (const line of describeUpdateCommand({ currentVersion, cache: finalCache, dismissed })) {
-    log(line);
+  if (dismissRequested) {
+    let dismissed = false;
+    if (typeof cache?.feed?.product === 'string') {
+      recordDismissalSync({ version: cache.feed.product, env });
+      dismissed = true;
+    }
+    const finalCache = dismissed ? readCacheSync(cachePath) : cache;
+    for (const line of describeUpdateCommand({ currentVersion, cache: finalCache, dismissed })) {
+      log(line);
+    }
+    return { exitCode: 0 };
   }
-  return { exitCode: 0 };
+
+  const feed = cache?.feed;
+  const updateAvailable = isValidFeedShape(feed) && compareVersions(feed.product, currentVersion) > 0;
+  const selfUpdateEligible = updateAvailable
+    && !!feed.components?.app?.url
+    && !!feed.components?.app?.sha256
+    && (options.isRunningFromAppDir ?? isRunningFromAppDir)({ env, launcherRoot: options.launcherRoot });
+
+  if (!selfUpdateEligible) {
+    for (const line of describeUpdateCommand({ currentVersion, cache, dismissed: false })) {
+      log(line);
+    }
+    return { exitCode: 0 };
+  }
+
+  return (options.applySelfUpdate ?? applySelfUpdate)({
+    env,
+    feed,
+    log,
+    fetchImpl: options.fetchImpl,
+    runNpmInstall: options.runNpmInstall
+  });
 }

package/src/internal-command.mjs

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { resolveLauncherAssets } from './repo-assets.mjs';
+
+const commands = [
+  'beat-sync-beatmap',
+  'beat-sync-probe-frame',
+  'beat-sync-render-when-idle',
+  'vision-finger-frame',
+  'eye-bar'
+];
+
+const usage = [
+  '使い方: akari internal <subcommand> [args...]',
+  '',
+  'サブコマンド:',
+  ...commands.map((command) => `  ${command}`)
+].join('\n');
+
+export async function runInternalCommand(args, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const logError = options.logError ?? ((line) => console.error(line));
+  const assets = options.assets ?? resolveLauncherAssets();
+  const spawn = options.spawn ?? spawnSync;
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    log(usage);
+    return { exitCode: 0 };
+  }
+
+  // vision-finger-frame は task/2026-08-11-finger-frame-generator の境界規約により
+  // repo-assets.mjs（別タスク task/2026-08-11-eye-bar-generator と衝突しやすい共有ファイル）を
+  // 編集せず、他コマンドと違い assets.repoRoot から自己解決する（resolveRepoAssets() 側に
+  // フィールドを追加していない唯一の例外 -- 経緯は非公開の内部記録を参照）。
+  const fingerFrameScript = assets.repoRoot
+    ? path.join(assets.repoRoot, 'packages', 'akari-tools', 'bin', 'finger-frame.mjs')
+    : null;
+
+  const definitions = {
+    'beat-sync-beatmap': { path: assets.beatmapScript, node: true },
+    'beat-sync-probe-frame': { path: assets.probeFrameScript, node: true },
+    'beat-sync-render-when-idle': { path: assets.renderWhenIdleScript, node: false },
+    'vision-finger-frame': {
+      path: fingerFrameScript && existsSync(fingerFrameScript) ? fingerFrameScript : null,
+      node: true
+    },
+    'eye-bar': { path: assets.eyeBarScript, node: true }
+  };
+  const definition = definitions[subcommand];
+  if (!definition) {
+    logError(`不明な internal サブコマンドです: ${subcommand}`);
+    log(usage);
+    return { exitCode: 1 };
+  }
+  if (!definition.path) {
+    logError(`内部コマンド ${subcommand} の実行スクリプトが見つかりません。AKARI Video の完全な checkout または配布物を確認してください。`);
+    return { exitCode: 1 };
+  }
+
+  const forwardedArgs = args.slice(1);
+  const result = definition.node
+    ? spawn(process.execPath, [definition.path, ...forwardedArgs], { stdio: 'inherit' })
+    : spawn(definition.path, forwardedArgs, { stdio: 'inherit' });
+  const exitCode = typeof result?.status === 'number' ? result.status : 1;
+  return { exitCode };
+}

package/src/messages.mjs

@@ -48,7 +48,7 @@ export function claudeMissingGuidance() {
 export function opencodeMissingGuidance() {
   return [
     'opencode コマンドが見つかりませんでした。',
-    'opencode をインストールしてください: npm install -g opencode',
+    'opencode をインストールしてください: npm install -g opencode-ai',
     'インストール後、このフォルダーで再度 `akari --opencode` を実行してください。'
   ].join('\n');
 }
@@ -163,18 +163,25 @@ export function initFailedError(errorMessage) {
 }
 
 /**
- * 素材の取得方式案内 + 公式音源ライブラリ（AKARI Sounds）明示再入口（`akari sounds`）の
- * 文言群。1 行主義の既存流儀に従う。
+ * 素材の取得方式案内 + 無料スターターパック（`akari store connect`）+ 公式音源ライブラリ
+ * （AKARI Sounds）明示再入口（`akari sounds`）の文言群。1 行主義の既存流儀に従う。
  *
  * 2026-08-04 オーナー方針（正本: `planning/notes-2026-08-04-asset-reference-distribution.md`
  * §8）により、初回起動での AKARI Sounds 一括ダウンロード [Y/n] 質問（2026-08-03 裁定）は
  * 廃止した。素材は resolver がオンデマンド取得する設計に一本化されたため、質問文言
  * （`soundsPromptText` / `soundsDeclinedNotice`）はもう使わない。
+ *
+ * 2026-08-11 オーナー裁定（正本: 内部リポ `planning/notes-2026-08-11-onboarding-firstrun.md`
+ * §3 R2）により、無料スターターパックの案内を同じ 1 回だけの通知に統合した（別画面を増やさない
+ * ＝「1 画面 1 問まで」の精神）。件数は明記しない（実際のパック内容は入れ替わりうるため
+ * 実数依存の表現にしない）。表示条件は `sounds-setup.mjs` の `maybeShowAssetIntroNotice` が
+ * 持つ — 既にアカウント連携済みなら、この文言ごと表示をスキップする（連携ずみの人には
+ * 「連携すると使える」という案内自体が的外れなため）。
  */
 
 /** `akari` 起動時に生涯 1 回だけ出す素材案内（質問ではない・対話をブロックしない）。 */
 export function assetIntroNotice() {
-  return '素材（B-roll・背景・音源）は使うときに必要な分だけ自動で取得されます。`akari store connect` でアカウントを接続すると購入済み素材も同じ一覧に並びます。まとめて欲しい場合は `akari sounds` で音源を一括ダウンロードできます（この案内は次回以降表示しません）。';
+  return '素材（B-roll・背景・音源）は使うときに必要な分だけ自動で取得されます。無料の素材パックもあります — `akari store connect` でアカウント連携すると使えるようになります。まとめて音源だけ欲しい場合は `akari sounds` で一括ダウンロードできます（この案内は次回以降表示しません）。';
 }
 
 /** ダウンロード成功後の完了 + 追加カタログ（外部補完）の案内。`akari sounds` の完了時に使う。 */
@@ -191,3 +198,43 @@ export function soundsFailedNotice() {
 export function soundsUnavailableError() {
   return '音源セットアップスクリプト（audio-library-setup）が見つかりませんでした。';
 }
+
+/** `akari assets`: 素材 resolver（asset-resolver）が同梱されていない場合のエラー（stderr 1 行）。 */
+export function assetsResolverUnavailableError() {
+  return '素材 resolver（asset-resolver）が見つかりませんでした。`akari assets` は使えません。';
+}
+
+/**
+ * `akari --help` / `akari -h`（Node CLI 版。npm 配布 `akari-video` パッケージの `akari`
+ * コマンド）の出力（タスク契約 `2026-08-11-onboarding-o3-firstrun-plain` §4）。
+ * `akari.sh` の `-h|--help` 出力と同じ「作る → プレビュー → 連携/素材 → 更新」の初心者目線の
+ * 並びに揃え、開発者向けのフラグ・サブコマンドは末尾に降格する。プレビューサーバーは
+ * シェル版（`akari.sh --preview`）専用の機能で npm 版の `akari` 単体には同梱されないため、
+ * 案内が行き止まりにならないようその旨を明示する。
+ */
+export function describeCliHelp() {
+  return [
+    'AKARI Video — AI が主体で動画を編集するツール',
+    '',
+    '使い方: akari [command] [options...]',
+    '',
+    'よく使うコマンド:',
+    '  (引数なし)              プロジェクトを開いて AI エージェントを起動（未作成なら自動作成）',
+    '  store connect          アカウント連携（無料の素材パックと購入済み素材が使えるようになる）',
+    '  sounds                 公式音源ライブラリを一括ダウンロード（無料）',
+    '  update                 更新を確認する',
+    '  status                 接続状態を確認する',
+    '',
+    '開発者向け:',
+    '  --opencode              Claude Code の代わりに opencode を起動する',
+    '  --claude, --claudecode  Claude Code を明示的に起動する',
+    '  -y, --yes               自動承認（確認をスキップ）',
+    '  --version, -v            インストール済みのバージョンを表示',
+    '  new <dir>                雛形からプロジェクトを新規作成',
+    '  init                     保存フォルダ（作業場）だけを作成・確認',
+    '  narration / assets / internal / capability   各機能の詳細は `akari <command> --help`',
+    '  -h, --help               このヘルプを表示',
+    '',
+    'プレビューサーバー（ブラウザで確認する画面）はシェル版のみ対応です: akari.sh --preview'
+  ];
+}

package/{vendor/skills/generate-narration/bin/generate-narration.mjs → src/narration-command.mjs}

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 // 原稿テキストから VOICEVOX（ローカル）または fal Qwen3-TTS（自声クローン）でナレーション音声を
 // 生成し、docs/contract-2026-07-20-edit-json-v1-narration.md 準拠のエントリを組み立てる。
 
@@ -17,12 +15,20 @@ const FAL_USD_PER_1000_CHARS = 0.09;
 
 const usage = [
   "使い方:",
-  "  node generate-narration.mjs generate \\",
+  "  akari narration generate \\",
   "    --project <projectDir> --engine <voicevox|fal-qwen3> \\",
   "    --reading-file <読み原稿.txt> [--script-file <表示原稿.txt>] \\",
   "    --t <タイムライン秒> [--gain-db 0] [--id n-0001] \\",
   "    [--speaker 3] [--profile owner-ja] [--dry-run] [--yes] [--apply]",
 ].join("\n");
+const commandUsage = [
+  "使い方: akari narration <subcommand> [options]",
+  "",
+  "サブコマンド:",
+  "  generate  原稿からナレーション音声を生成する",
+  "",
+  usage,
+].join("\n");
 
 class PublicError extends Error {
   constructor(message, exitCode = 1) {
@@ -31,8 +37,8 @@ class PublicError extends Error {
   }
 }
 
-function printJson(value) {
-  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+function printJson(value, log = (line) => console.log(line)) {
+  log(JSON.stringify(value, null, 2));
 }
 
 function sleep(ms) {
@@ -390,10 +396,10 @@ async function synthesizeVoicevox(readingText, speakerId) {
 // --- edit.json への --apply ---
 
 function validateEditScriptPath() {
-  return fileURLToPath(new URL("../../../packages/schemas/bin/validate-edit.mjs", import.meta.url));
+  return fileURLToPath(new URL("../../schemas/bin/validate-edit.mjs", import.meta.url));
 }
 
-function applyToEditJson(projectDir, entry) {
+function applyToEditJson(projectDir, entry, io) {
   const editPath = path.join(projectDir, "edit.json");
   let originalText;
   try {
@@ -422,7 +428,7 @@ function applyToEditJson(projectDir, entry) {
       `validate-edit が NG のため edit.json への書き込みをロールバックしました。\n${detail}`,
     );
   }
-  process.stderr.write(`edit.json に ${entry.id} を追加しました（validate-edit: PASS）。\n`);
+  io.logError(`edit.json に ${entry.id} を追加しました（validate-edit: PASS）。`);
 }
 
 // --- dry-run ---
@@ -432,7 +438,7 @@ function maskKey(secret) {
   return secret ? "***configured***" : "***unconfigured***";
 }
 
-async function runDryRun(options, readingText) {
+async function runDryRun(options, readingText, io) {
   const outputPath = relativeOutputPath(options.id ?? computeNextId(options.project), options.engine);
   if (options.engine === "voicevox") {
     printJson({
@@ -449,7 +455,7 @@ async function runDryRun(options, readingText) {
         speaker: Number(options.speaker),
         text: readingText,
       },
-    });
+    }, io.log);
     return;
   }
 
@@ -467,18 +473,18 @@ async function runDryRun(options, readingText) {
       headers: { Authorization: `Key ${maskKey(falKey)}` },
       body: payload,
     },
-  });
+  }, io.log);
 }
 
 // --- generate 本体 ---
 
-async function runGenerate(options) {
+async function runGenerate(options, io) {
   const readingText = readTextFile(options.readingFile, "読み原稿");
   const scriptText = options.scriptFile ? readTextFile(options.scriptFile, "表示原稿") : null;
 
   if (options.dryRun) {
-    await runDryRun(options, readingText);
-    return;
+    await runDryRun(options, readingText, io);
+    return 0;
   }
 
   const id = options.id ?? computeNextId(options.project);
@@ -514,18 +520,15 @@ async function runGenerate(options) {
     const falKey = resolveFalKey();
     const meta = readProfileMeta(options.profile);
     const estimatedCostUsd = estimateFalCostUsd(readingText);
-    process.stderr.write(
-      `fal-qwen3 推定費用: 約 $${estimatedCostUsd}（${readingText.length} 文字 × $${FAL_USD_PER_1000_CHARS}/1000字）\n`,
-    );
+    io.logError(`fal-qwen3 推定費用: 約 $${estimatedCostUsd}（${readingText.length} 文字 × $${FAL_USD_PER_1000_CHARS}/1000字）`);
     if (!options.yes) {
       printJson({
         sent: false,
         engine: "fal-qwen3",
         estimated_cost_usd: estimatedCostUsd,
         reason: "費用承認（--yes）がありません。実リクエストは送信していません。",
-      });
-      process.exitCode = 2;
-      return;
+      }, io.log);
+      return 2;
     }
     // --yes が明示された場合のみ、ここで初めて課金の発生する fal API を呼び出す。
     audioBuffer = await synthesizeFal(readingText, meta, falKey);
@@ -550,23 +553,37 @@ async function runGenerate(options) {
     provenance,
   };
 
-  if (options.apply) applyToEditJson(options.project, entry);
+  if (options.apply) applyToEditJson(options.project, entry, io);
 
-  printJson(entry);
+  printJson(entry, io.log);
+  return 0;
 }
 
-async function main() {
-  let options;
+export async function runNarrationCommand(args, commandOptions = {}) {
+  const io = {
+    log: commandOptions.log ?? ((line) => console.log(line)),
+    logError: commandOptions.logError ?? ((line) => console.error(line)),
+  };
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    io.log(commandUsage);
+    return { exitCode: 0 };
+  }
+  if (args[0] === 'generate' && (args.includes('--help') || args.includes('-h'))) {
+    io.log(usage);
+    return { exitCode: 0 };
+  }
+
+  let parsedOptions;
   try {
-    options = parseArguments(process.argv.slice(2));
-    await runGenerate(options);
+    parsedOptions = parseArguments(args);
+    const exitCode = await runGenerate(parsedOptions, io);
+    return { exitCode };
   } catch (error) {
     const exitCode = error instanceof PublicError ? error.exitCode : 1;
     const message = error instanceof PublicError ? error.message : `内部処理に失敗しました: ${error?.message ?? error}`;
-    process.stderr.write(`${message}\n`);
-    printJson({ error: message });
-    process.exitCode = exitCode;
+    io.logError(message);
+    printJson({ error: message }, io.log);
+    return { exitCode };
   }
 }
-
-await main();