akari-video 1.5.0 → 1.5.2-beta.1

package/README.md

@@ -21,7 +21,7 @@ akari
   │     （.akari/intake.json は status: "draft" で生成される）
   │
   ├─ 3. 接続状態を確認する:
-  │     skills/manage-connections/bin/doctor.mjs を再利用して
+  │     skills/setup-connections/bin/doctor.mjs を再利用して
   │     .akari/connections.json の doctor ブロックを更新・表示する
   │     （キーの値は一切表示しない）
   │
@@ -47,7 +47,7 @@ DL・sha256 検証・適用まで実行。それ以外（npm グローバル / g
 `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 internal beat-sync-<beatmap|probe-frame|render-when-idle> ...`（edit-to-beat 内部実行物）/
 `akari sounds [--variant wav] [--force]`（公式音源の一括ダウンロード。プロンプトなし・headless 可）/
 `akari store <connect|status|install|download|disconnect>`（AKARI Store 連携。マイページで発行した
 接続トークンを `~/.akari/store-credentials.json`（0600）に保存し、購入済み一覧の確認と

package/bin/akari.mjs

@@ -17,6 +17,8 @@ import { runDoctorCommand } from '../src/doctor-command.mjs';
 import { runGenerateCommand } from '../src/generate-command.mjs';
 import { runStoryboardCommand } from '../src/storyboard-command.mjs';
 import { runWorldCommand } from '../src/world-command.mjs';
+import { runLintCommand } from '../src/lint-command.mjs';
+import { runPreviewCommand } from '../src/preview-command.mjs';
 import { runSkillsCommand, refreshEntrySkillOnLaunch } from '../src/skills-command.mjs';
 import { resolveRuntimePaths } from '../src/runtime-diagnostics.mjs';
 import { maybeApplyPendingUpdateOnLaunch, resolveInstalledVersionInfo } from '../src/update-check.mjs';
@@ -77,6 +79,8 @@ const commands = {
   generate: runGenerateCommand,
   storyboard: runStoryboardCommand,
   world: runWorldCommand,
+  lint: runLintCommand,
+  preview: runPreviewCommand,
 };
 
 // トップレベルのフラグも、振り分けと候補判定に同じ表を使う。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "1.5.0",
+  "version": "1.5.2-beta.1",
   "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/cli.mjs

@@ -32,7 +32,10 @@ import { runWordBookCommand } from './word-book-command.mjs';
 import { runConnectCommand } from './connect-command.mjs';
 import { runProjectCommand } from './project-command.mjs';
 import { runPlaybookCommand } from './playbook-command.mjs';
+import { runTemplateCommand } from './template-command.mjs';
 import { runRecipeCommand } from './recipe-command.mjs';
+import { runLintCommand } from './lint-command.mjs';
+import { runPreviewCommand } from './preview-command.mjs';
 import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
 import { cliText } from './i18n.mjs';
 
@@ -48,7 +51,10 @@ export const runSubcommands = {
   connect: runConnectCommand,
   project: runProjectCommand,
   playbook: runPlaybookCommand,
+  template: runTemplateCommand,
   recipe: runRecipeCommand,
+  lint: runLintCommand,
+  preview: runPreviewCommand,
 };
 
 /**

package/src/connect/connectors.json

@@ -11,7 +11,7 @@
   {
     "id": "3d-recipes",
     "group": "tools",
-    "name": "3D レシピ",
+    "name": "3D の設定",
     "description": "Blender で 3D 素材を作る",
     "icon": "3D",
     "kind": "blender-recipe",

package/src/lint-command.mjs

@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+import { cliText } from './i18n.mjs';
+import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
+
+// 値を 1 つ取るオプション。プロジェクトの位置引数と取り違えないよう読み飛ばす。
+const VALUE_FLAGS = new Set([
+  '--engine',
+  '--silence-error-seconds',
+  '--max-volume-error-db',
+  '--caption-silence-warn-percent',
+  '--declarations',
+  '--ffprobe'
+]);
+
+export function lintHelp() {
+  return [
+    cliText('cli.lint.help.usage'),
+    '',
+    cliText('cli.lint.help.description'),
+    cliText('cli.lint.help.project'),
+    cliText('cli.lint.help.fix'),
+    cliText('cli.lint.help.media'),
+    cliText('cli.lint.help.json'),
+    cliText('cli.lint.help.engine'),
+    cliText('cli.lint.help.help')
+  ];
+}
+
+function hasProjectArgument(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') return index + 1 < argv.length;
+    if (VALUE_FLAGS.has(argument)) {
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith('-')) continue;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * `akari lint [<project>] [--fix] ...` — 決定論的な edit-lint CLI をそのまま呼ぶ。
+ * 既定では `--no-reports` を付けて一切書き込まない。`--fix` のときだけ edit-lint の
+ * 修正経路（退避・差分・再検査）を通す。
+ */
+export async function runLintCommand(argv, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const error = options.error ?? ((line) => console.error(line));
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    for (const line of lintHelp()) log(line);
+    return { exitCode: 0 };
+  }
+
+  const runtime = options.runtime ?? resolveRuntimePaths({ env: options.env ?? process.env });
+  const editLintPath = options.editLintPath ?? runtime.edit_lint?.path ?? null;
+  if (!editLintPath || !existsSync(editLintPath)) {
+    error(cliText('cli.lint.error.scriptMissing'));
+    return { exitCode: 2 };
+  }
+
+  const forwarded = [...argv];
+  if (!hasProjectArgument(forwarded)) forwarded.push('.');
+  if (!forwarded.includes('--fix')) forwarded.push('--no-reports');
+
+  const env = { ...(options.env ?? process.env) };
+  const electron = options.electronRuntime ?? Boolean(process.versions.electron);
+  if (electron && env.ELECTRON_RUN_AS_NODE !== '1') env.ELECTRON_RUN_AS_NODE = '1';
+
+  const spawn = options.spawn ?? spawnSync;
+  const result = spawn(options.execPath ?? process.execPath, [editLintPath, ...forwarded], {
+    stdio: options.stdio ?? 'inherit',
+    cwd: options.cwd ?? process.cwd(),
+    env
+  });
+  return {
+    exitCode: typeof result?.status === 'number' ? result.status : 2,
+    stdout: result?.stdout,
+    stderr: result?.stderr
+  };
+}

package/src/messages.mjs

@@ -335,7 +335,7 @@ export function describeCliHelp() {
     cliText('cli.help.header.usage'),
     '',
     cliText('cli.help.commands.heading'),
-    ...['launch', 'store', 'sounds', 'doctor', 'speakers', 'toolsVoice', 'update', 'status', 'migrate', 'migrateLook', 'generate', 'storyboard', 'project', 'playbook', 'recipe', 'clean'].map((name) => cliText(`cli.help.commands.${name}`)),
+    ...['launch', 'preview', 'store', 'sounds', 'doctor', 'speakers', 'toolsVoice', 'update', 'status', 'migrate', 'migrateLook', 'generate', 'storyboard', 'project', 'playbook', 'recipe', 'lint', 'clean'].map((name) => cliText(`cli.help.commands.${name}`)),
     '',
     cliText('cli.help.developer.heading'),
     ...['opencode', 'claude', 'yes', 'version', 'new', 'init', 'other', 'help'].map((name) => cliText(`cli.help.developer.${name}`)),

package/src/narration-command.mjs

@@ -59,7 +59,7 @@ async function projectLanguage(projectRoot, cliLang) {
 const usage = (language) => [
   cliText('cli.narration.help.usage', {}, language),
   "  akari narration generate \\",
-  "    --project <projectDir> [--engine <voicevox|gemini-tts|irodori|fal-qwen3|gemini-3.1-flash-tts|elevenlabs-v3|minimax-2.6-hd|chatterbox|index-tts-2|fish-s2.1-pro|gemini-3.8-flash-tts>] \\",
+  "    --project <projectDir> [--engine <voicevox|gemini-tts|irodori|fal-qwen3|gemini-3.1-flash-tts|elevenlabs-v3|minimax-2.6-hd|chatterbox|index-tts-2|fish-s2.1-pro|fish-drama-3|gemini-3.8-flash-tts>] \\",
   cliText('cli.narration.help.reading', {}, language),
   cliText('cli.narration.help.timeline', {}, language),
   "    [--lang <code>] [--speaker 3] [--voice Leda] [--style <text>] [--speed 1] \\",
@@ -322,10 +322,10 @@ async function parseArguments(argv) {
     irodoriTimeout();
   } else {
     const engine = ttsEngine(options.engine);
-    options.voice ??= engine ? (engine.id === 'fish-s2.1-pro' && options.language !== 'ja' ? null
+    options.voice ??= engine ? (engine.provider === 'fish-audio' && options.language !== 'ja' ? null
       : engine.default_voices && Object.hasOwn(engine.default_voices, options.language)
       ? engine.default_voices[options.language] : engine.default_voice) : 'Leda';
-    if (options.engine === 'fish-s2.1-pro' && !options.voice && !options.profile) {
+    if (engine?.provider === 'fish-audio' && !options.voice && !options.profile) {
       throw new PublicError(cliText('cli.narration.error.fishDefaultVoiceMissing'), 2);
     }
   }
@@ -773,7 +773,7 @@ function applyToEditJson(projectDir, entry, io) {
 // --- dry-run ---
 
 function maskKey(secret) {
-  // 実際のキー文字は 1 文字も出力しない（manage-connections ハードルール「表示は常にマスク」）。
+  // 実際のキー文字は 1 文字も出力しない（setup-connections ハードルール「表示は常にマスク」）。
   return secret ? "***configured***" : "***unconfigured***";
 }
 
@@ -873,7 +873,7 @@ async function listEngines(runtime = {}) {
       id: engine.id, label: engine.label, languages: engine.languages, place: engine.place, provider: engine.provider,
       group: 'cloud', endpoint: engine.endpoint, price: engine.price,
       availability: directAvailability[engine.provider], default_voice: engine.default_voice,
-      credit_required: false, supports: engine.supports,
+      credit_required: false, supports: engine.supports, ...(engine.candidate ? { candidate: true } : {}),
     })),
   ] };
 }
@@ -956,7 +956,7 @@ async function runDryRun(options, readingText, io) {
     emit({ dry_run: true, engine: engine.id, output_path: outputPath,
       estimated_cost_usd: estimateTtsCost(engine, readingText),
       request: { endpoint: engine.endpoint, headers: engine.provider === 'fish-audio'
-        ? { Authorization: `Bearer ${maskKey(readProviderKey('FISH_AUDIO_API_KEY'))}`, model: 's2.1-pro',
+        ? { Authorization: `Bearer ${maskKey(readProviderKey('FISH_AUDIO_API_KEY'))}`, model: engine.model,
           'Content-Type': record ? 'application/msgpack' : 'application/json' }
         : { 'x-goog-api-key': maskKey(readProviderKey('GEMINI_API_KEY')), 'Content-Type': 'application/json' }, body } }, io.log);
     return;
@@ -1041,6 +1041,10 @@ async function runGenerate(options, io) {
   if (options.engine === 'chatterbox' && readingText.length > 300) {
     throw new PublicError(cliText('cli.narration.error.chatterboxLength'), 2);
   }
+  // 候補は既定で選ばれない。名指しされた場合も、送信前に試聴前であることを 1 行で伝える。
+  if (ttsEngine(options.engine)?.candidate) {
+    io.logError(cliText('cli.narration.warning.candidateEngine', { engine: options.engine }));
+  }
 
   if (options.dryRun) {
     await runDryRun(options, readingText, io);
@@ -1118,7 +1122,7 @@ async function runGenerate(options, io) {
         referenceAudio, referenceText: record?.meta.reference_text });
       audioBuffer = await synthesizeDirect(engine, payload, key);
       provenance = { provider: engine.provider, engine: engine.id,
-        model: engine.provider === 'fish-audio' ? 's2.1-pro' : 'gemini-3.8-flash-tts',
+        model: engine.model ?? engine.id,
         voice: record ? `profile:${options.profile}` : options.voice,
         generated_at: new Date().toISOString(), price_verified: engine.price.verified };
     } else if (options.engine === "gemini-tts") {

package/src/new-command.mjs

@@ -12,18 +12,20 @@ const languageTagPattern = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 
 function parseArguments(args) {
     let target;
+    let scaffold;
     let template;
     let from;
     let lang;
 
     for (let index = 0; index < args.length; index += 1) {
         const argument = args[index];
-        if (argument === '--template') {
+        if (argument === '--template' || argument === '--scaffold') {
             const value = args[index + 1];
             if (!value || value.startsWith('--')) {
-                throw new Error(`${usage()}\n${cliText('cli.new.error.templateMissing', {})}`);
+                throw new Error(`${usage()}\n${cliText(argument === '--scaffold' ? 'cli.new.error.scaffoldMissingPath' : 'cli.new.error.templateMissing', {})}`);
             }
-            template = value;
+            if (argument === '--scaffold') scaffold = value;
+            else template = value;
             index += 1;
         } else if (argument === '--from') {
             const value = args[index + 1];
@@ -51,7 +53,10 @@ function parseArguments(args) {
     if (target === undefined) {
         throw new Error(usage());
     }
-    return { target, template, from, lang };
+    if (scaffold !== undefined && template !== undefined) {
+        throw new Error(`${usage()}\n${cliText('cli.new.error.scaffoldAndTemplate', {})}`);
+    }
+    return { target, scaffold: scaffold ?? template, usedTemplateAlias: template !== undefined, from, lang };
 }
 
 async function directoryHasFile(directory, relativeFile) {
@@ -106,9 +111,10 @@ export async function runNewCommand(args, options = {}) {
         return { exitCode: 1 };
     }
 
-    const { target, template, from, lang } = parsed;
+    const { target, scaffold, usedTemplateAlias, from, lang } = parsed;
+    if (usedTemplateAlias) logError(text('cli.new.notice.templateAlias'));
     const targetDir = path.resolve(cwd, target);
-    const templateDir = template ? path.resolve(cwd, template) : assets.templateDir;
+    const templateDir = scaffold ? path.resolve(cwd, scaffold) : assets.templateDir;
     let playbookDir;
     if (from) {
         try { playbookDir = await resolvePlaybookDir(from, { cwd, targetDir, assets, env: options.env }); }

package/src/playbook-command.mjs

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
+import fs from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 
 import { cliText } from './i18n.mjs';
@@ -9,13 +10,13 @@ const usage = () => `${cliText('cli.playbook.help.usage')}\n${cliText('cli.playb
 const safeChannel = value => typeof value === 'string' && value.trim() && value.length <= 64
     && value !== '.' && !value.includes('..') && !/[/\\<>:"|?*\x00-\x1f]/.test(value);
 
-function parse(args) {
+function parse(args, usageText = usage()) {
     const action = args[0];
     if (action === '--help' || action === '-h' || args.includes('--help') || args.includes('-h')) return { action: 'help' };
-    if (!['list', 'apply', 'template'].includes(action)) throw new Error(usage());
+    if (!['list', 'apply', 'template'].includes(action)) throw new Error(usageText);
     const result = { action, id: action === 'apply' ? args[1] : null, project: action === 'template' ? args[1] : null };
-    if (action === 'apply' && (!result.id || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(result.id))) throw new Error(usage());
-    if (action === 'template' && !result.project) throw new Error(usage());
+    if (action === 'apply' && (!result.id || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(result.id))) throw new Error(usageText);
+    if (action === 'template' && !result.project) throw new Error(usageText);
     for (let i = action === 'apply' || action === 'template' ? 2 : 1; i < args.length; i++) {
         const arg = args[i];
         if ((action === 'list' && arg === '--json') || (action === 'apply' && arg === '--dry-run')) {
@@ -23,13 +24,13 @@ function parse(args) {
         } else if ((action === 'list' && ['--category', '--tag', '--channel'].includes(arg))
             || (action === 'apply' && arg === '--into')
             || (action === 'template' && ['--item', '--id', '--name', '--out', '--license-own'].includes(arg))) {
-            if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(usage());
+            if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(usageText);
             result[arg.slice(2)] = args[++i];
-        } else throw new Error(usage());
+        } else throw new Error(usageText);
     }
-    if (action === 'apply' && !result.into) throw new Error(usage());
-    if (action === 'template' && (!result.item || !result.id || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(result.id))) throw new Error(usage());
-    if (result.channel && !safeChannel(result.channel)) throw new Error(usage());
+    if (action === 'apply' && !result.into) throw new Error(usageText);
+    if (action === 'template' && (!result.item || !result.id || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(result.id))) throw new Error(usageText);
+    if (result.channel && !safeChannel(result.channel)) throw new Error(usageText);
     return result;
 }
 
@@ -37,9 +38,12 @@ export async function runPlaybookCommand(args, options = {}) {
     const log = options.log ?? console.log;
     const error = options.error ?? console.error;
     let parsed;
-    try { parsed = parse(args); }
+    try { parsed = parse(args, options.usage ?? usage()); }
     catch (cause) { error(cause.message); return { exitCode: 1 }; }
-    if (parsed.action === 'help') { log(usage()); return { exitCode: 0 }; }
+    if (parsed.action === 'help') { log(options.usage ?? usage()); return { exitCode: 0 }; }
+    if (parsed.action === 'template' && !options.suppressTemplateAliasNotice) {
+        error(cliText('cli.playbook.template.aliasNotice'));
+    }
     try {
         const env = options.env ?? process.env;
         const cwd = options.cwd ?? process.cwd();
@@ -73,11 +77,17 @@ export async function runPlaybookCommand(args, options = {}) {
             category: parsed.category, tag: parsed.tag,
             onWarning: (dir, cause) => error(cliText('cli.playbook.warning.broken', { dir, message: cause.message })) });
         if (parsed.action === 'list') {
-            if (parsed.json) log(JSON.stringify(entries));
-            else for (const entry of entries) log(cliText('cli.playbook.list.row', { id: entry.id, name: entry.name,
+            const listed = options.listDepth === undefined ? entries : (await Promise.all(entries.map(async entry => {
+                try {
+                    const book = JSON.parse(await fs.readFile(path.join(entry.dir, 'playbook.json'), 'utf8'));
+                    return book.depth === options.listDepth ? entry : null;
+                } catch { return null; }
+            }))).filter(Boolean);
+            if (parsed.json) log(JSON.stringify(listed));
+            else for (const entry of listed) log(cliText('cli.playbook.list.row', { id: entry.id, name: entry.name,
                 category: entry.category, source: entry.source,
                 duration: entry.targetDurationSec ?? cliText('cli.playbook.list.durationUnknown') }));
-            return { exitCode: 0, entries };
+            return { exitCode: 0, entries: listed };
         }
         const entry = entries.find(item => item.id === parsed.id);
         if (!entry) throw new Error(cliText('cli.playbook.error.notFound', { id: parsed.id }));

package/src/preview-command.mjs

@@ -0,0 +1,281 @@
+import { spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { PREVIEW_SERVER_SCRIPT_RELATIVE, resolveLauncherAssets } from './repo-assets.mjs';
+import { cliText } from './i18n.mjs';
+
+/**
+ * `akari preview [dir] [--port <port>] [--open]` — プロジェクトのプレビューを
+ * ブラウザで開く URL を出す。サーバーの実体は `packages/preview-server/src/server.mjs`
+ * （モノレポ checkout / アプリの Resources / 同梱されていれば npm vendor）を子プロセスとして
+ * 起動するだけで、ここでサーバーを再実装しない。
+ *
+ * 既定ポートは preview-server の既定（3000）。`akari.sh --preview` の既定は 4567 だが、
+ * シェル版の既存挙動は変えず、Node CLI 側はサーバー本体の既定に合わせる。
+ */
+
+export const PREVIEW_DEFAULT_PORT = 3000;
+
+export function previewHelp() {
+  return [
+    cliText('cli.preview.help.usage'),
+    '',
+    cliText('cli.preview.help.description'),
+    '',
+    cliText('cli.preview.help.port'),
+    cliText('cli.preview.help.open'),
+    cliText('cli.preview.help.help'),
+  ];
+}
+
+function isPort(value) {
+  return /^\d+$/u.test(value) && Number(value) >= 1 && Number(value) <= 65535;
+}
+
+/**
+ * 引数を解釈する。`help` は他引数より優先する（`--help` は常に成功で終わる）。
+ * `projectRoot` は決して実在確認しない — 呼び出し側が案内付きで止める。
+ */
+export function parsePreviewArguments(args, cwd = process.cwd()) {
+  const positional = [];
+  let port = PREVIEW_DEFAULT_PORT;
+  let open = false;
+  let help = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      help = true;
+      continue;
+    }
+    if (arg === '-o' || arg === '--open') {
+      open = true;
+      continue;
+    }
+    if (arg === '-p' || arg === '--port') {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        return { ok: false, message: cliText('cli.preview.error.portMissing') };
+      }
+      i += 1;
+      if (!isPort(value)) {
+        return { ok: false, message: cliText('cli.preview.error.invalidPort', { port: value }) };
+      }
+      port = Number(value);
+      continue;
+    }
+    if (arg.startsWith('--port=')) {
+      const value = arg.slice('--port='.length);
+      if (!isPort(value)) {
+        return { ok: false, message: cliText('cli.preview.error.invalidPort', { port: value }) };
+      }
+      port = Number(value);
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      return { ok: false, message: cliText('cli.preview.error.unknownOption', { option: arg }) };
+    }
+    positional.push(arg);
+  }
+
+  if (help) return { ok: true, help: true };
+  if (positional.length > 1) {
+    return { ok: false, message: cliText('cli.preview.error.multipleDirs') };
+  }
+  return {
+    ok: true,
+    help: false,
+    port,
+    open,
+    projectRoot: path.resolve(cwd, positional[0] ?? '.'),
+  };
+}
+
+/** サーバーが listen 後に出す URL 行だけを取り出す（banner の他行には反応しない）。 */
+export function extractPreviewUrl(line) {
+  const match = /^\s*(http:\/\/(?:127\.0\.0\.1|localhost|\[[^\]]+\]|[^\s:]+):\d+)\s*$/u.exec(line);
+  return match ? match[1] : null;
+}
+
+function isDirectory(target, stat = statSync) {
+  try {
+    return stat(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function defaultOpenBrowser(url, platform = process.platform) {
+  try {
+    const [command, args] = platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : [platform === 'darwin' ? 'open' : 'xdg-open', [url]];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runPreviewCommand(args, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const logError = options.error ?? options.logError ?? ((line) => console.error(line));
+  const parsed = parsePreviewArguments(args, options.cwd ?? process.cwd());
+
+  if (!parsed.ok) {
+    logError(parsed.message);
+    for (const line of previewHelp()) logError(line);
+    return { exitCode: 2 };
+  }
+  if (parsed.help) {
+    for (const line of previewHelp()) log(line);
+    return { exitCode: 0 };
+  }
+
+  const projectRoot = parsed.projectRoot;
+  if (!isDirectory(projectRoot, options.statSync ?? statSync)) {
+    logError(cliText('cli.preview.error.directoryMissing', { root: projectRoot }));
+    return { exitCode: 1 };
+  }
+
+  if (!(options.existsSync ?? existsSync)(path.join(projectRoot, '.akari'))) {
+    logError(cliText('cli.preview.error.notProject', { root: projectRoot }));
+    logError(cliText('cli.preview.error.projectGuidance'));
+    return { exitCode: 1 };
+  }
+
+  const assets = options.assets ?? resolveLauncherAssets({
+    resourcesPath: options.resourcesPath ?? process.resourcesPath,
+  });
+  const script = assets.previewServerScript;
+  if (!script || !(options.existsSync ?? existsSync)(script)) {
+    const missing = script ?? PREVIEW_SERVER_SCRIPT_RELATIVE;
+    const root = assets.repoRoot ?? cliText('cli.preview.label.unknown');
+    logError(cliText('cli.preview.error.serverMissing', { path: missing, root }));
+    return { exitCode: 1 };
+  }
+
+  return await startPreviewServer({
+    script,
+    projectRoot,
+    port: parsed.port,
+    open: parsed.open,
+    log,
+    logError,
+    env: options.env ?? process.env,
+    platform: options.platform ?? process.platform,
+    spawn: options.spawn ?? spawn,
+    openBrowser: options.openBrowser ?? defaultOpenBrowser,
+  });
+}
+
+function startPreviewServer({
+  script,
+  projectRoot,
+  port,
+  open,
+  log,
+  logError,
+  env,
+  platform,
+  spawn,
+  openBrowser,
+}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(process.execPath, [script, projectRoot, '--port', String(port)], {
+        cwd: projectRoot,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (cause) {
+      logError(cliText('cli.preview.error.spawnFailed', {
+        message: cause instanceof Error ? cause.message : String(cause),
+      }));
+      resolve({ exitCode: 1 });
+      return;
+    }
+
+    let ready = false;
+    let settled = false;
+    let outBuffer = '';
+    let errBuffer = '';
+    const pendingLines = [];
+
+    const emitLine = (line) => {
+      if (!ready) {
+        const url = extractPreviewUrl(line);
+        if (url) {
+          ready = true;
+          // URL を 1 行目に出す。banner は URL の後ろへ回し、起動ログも失わない。
+          log(url);
+          for (const pending of pendingLines) log(pending);
+          pendingLines.length = 0;
+          if (open) openBrowser(url, platform);
+          return true;
+        }
+        pendingLines.push(line);
+        return false;
+      }
+      log(line);
+      return true;
+    };
+
+    const onStdout = (chunk) => {
+      outBuffer += chunk;
+      let index;
+      while ((index = outBuffer.indexOf('\n')) >= 0) {
+        const line = outBuffer.slice(0, index).replace(/\r$/u, '');
+        outBuffer = outBuffer.slice(index + 1);
+        emitLine(line);
+      }
+    };
+
+    const onStderr = (chunk) => {
+      if (!ready) {
+        errBuffer += chunk;
+        return;
+      }
+      logError(chunk.replace(/\r?\n$/u, ''));
+    };
+
+    const onSignal = (signal) => {
+      try { child.kill(signal); } catch { /* 既に終了している。 */ }
+    };
+    const signals = ['SIGINT', 'SIGTERM'];
+    for (const signal of signals) process.on(signal, onSignal);
+
+    const cleanup = () => {
+      for (const signal of signals) process.off(signal, onSignal);
+      settled = true;
+    };
+
+    child.stdout?.setEncoding?.('utf8');
+    child.stderr?.setEncoding?.('utf8');
+    child.stdout?.on('data', onStdout);
+    child.stderr?.on('data', onStderr);
+
+    const finish = (code) => {
+      if (settled) return;
+      cleanup();
+      if (!ready) {
+        for (const line of pendingLines) logError(line);
+        if (outBuffer) logError(outBuffer);
+        if (errBuffer) logError(errBuffer.replace(/\r?\n$/u, ''));
+        logError(cliText('cli.preview.error.startFailed', { code: code ?? 1 }));
+      }
+      resolve({ exitCode: typeof code === 'number' ? code : 0 });
+    };
+
+    child.on('error', (cause) => {
+      logError(cliText('cli.preview.error.spawnFailed', {
+        message: cause instanceof Error ? cause.message : String(cause),
+      }));
+      finish(1);
+    });
+    child.on('exit', (code) => finish(code));
+  });
+}