create-promptex-js 1.0.0 → 1.1.0

package/dist/index.js

@@ -1,27 +1,32 @@
 #!/usr/bin/env node
-// 鷹架 CLI：從 promptex-templates 倉庫開出 TypeScript 的 project／plugin／
-// adapter 專案。六階段：環境檢查 → 互動收集 → 模板取得 → 具現化 → 後處理 →
-// 稽核輸出；非互動時（--yes 或無 TTY）全部取預設或旗標值。
+// 鷹架 CLI：開出 TypeScript 的 project／plugin／adapter 專案，或在既有資料夾加入 promptex。
+// 目標不存在或只有系統、版本控制、編輯器的檔案時走建立模式，否則走初始化模式
+// （m007 d004）。規則與套用在 plan.ts，本檔負責旗標、互動、輸出與結束碼。
 //
-// 模板不內嵌：單一來源住 promptex-templates，GA 版預設抓與本套件版本對應的
-// tag（v<版本>），預發布版預設抓 main，--ref 覆寫、--source 改用本地 checkout
-// （離線與開發用）。
+// Templates ship inside this package (templates/), so every version scaffolds the
+// templates it was released with, offline. --source points at a local templates
+// directory (the one holding the *-starter folders) for template development.
 //
 // 用法：
-//   npm create promptex-js [目標目錄] [-- --template project|plugin|adapter \
-//     --name <kebab 名> --ref <branch|tag> --source <本地路徑> \
-//     --git|--no-git --install --yes --locale <語系>]
-import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+//   pnpm create promptex-js [目標目錄] [--template project|plugin|adapter] \
+//     [--name <kebab 名>] [--source <模板目錄>] [--git|--no-git] [--install] \
+//     [--force] [--dry-run [--json]] [--yes] [--locale <語系>]
+//
+// 結束碼：0 成功（含已初始化），1 執行失敗，2 用法錯誤（ADR-041）。
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import mri from 'mri';
-import { resolveRef } from './default-ref.js';
+import { errorCode, FORMAT_VERSION } from './contract.generated.js';
 import { resolveLocale, t } from './messages.generated.js';
+import { applyPlan, cdPath, commandAvailable, CreateError, detectPackageManager, findConfig, inspectTarget, isInsideGitWorktree, isNonInteractive, missingInputs, nextSteps, planFiles, PM_COMMANDS, summarize, } from './plan.js';
 const here = fileURLToPath(new URL('.', import.meta.url));
 const ownVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
+const BUNDLED_TEMPLATES = join(here, '..', 'templates');
+const PACKAGE = { name: 'create-promptex-js', version: ownVersion };
+const LANGUAGE = 'ts';
 const TEMPLATES = ['project', 'plugin', 'adapter'];
 // 與 promptex init 的單元名正規化同一套規則（crates/promptex-core/src/init.rs）。
 const RESERVED_UNIT_NAMES = ['cache', 'preview', 'content', 'content-index', 'graph', 'main'];
@@ -36,115 +41,297 @@ export function normalizeName(raw) {
     out = out.replace(/^-+|-+$/g, '');
     return out === '' || RESERVED_UNIT_NAMES.includes(out) ? 'main' : out;
 }
-function bail(message) {
-    console.error(message);
-    process.exit(1);
+const BOOLEAN_FLAGS = ['install', 'yes', 'git', 'force', 'dry-run', 'json', 'help'];
+const STRING_FLAGS = ['template', 'name', 'source', 'locale'];
+// ── 輸出 ──
+// 帶 --json 時 stdout 只放一份 JSON，人讀訊息一律不印，錯誤另在 stderr 寫一行（ADR-041）。
+// 語系與 --json 在解析旗標之前先取，解析失敗時的訊息才用得上它們。
+const rawArgv = process.argv.slice(2);
+const jsonRequested = rawArgv.includes('--json');
+function localeFlag(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--locale')
+            return argv[i + 1];
+        if (argv[i].startsWith('--locale='))
+            return argv[i].slice('--locale='.length);
+    }
+    return undefined;
 }
-const TEMPLATES_REPO = 'https://github.com/promptex-ai/promptex-templates.git';
-const args = mri(process.argv.slice(2), {
-    boolean: ['install', 'yes', 'git', 'help'],
-    string: ['template', 'name', 'ref', 'source', 'locale'],
-    alias: { h: 'help' },
-});
-const locale = resolveLocale(args.locale);
+const locale = resolveLocale(localeFlag(rawArgv));
 const separator = t('common.list_separator', locale);
-if (args.help) {
-    console.log(t('scaffold.usage.js', locale));
-    process.exit(0);
+/** 細節值裡的陣列在訊息中以語系的清單分隔符接起來。 */
+function messageParams(details) {
+    return Object.fromEntries(Object.entries(details).map(([k, v]) => [k, Array.isArray(v) ? v.join(separator) : v]));
 }
-const interactive = process.stdin.isTTY && !args.yes;
-p.intro(`create-promptex-js v${ownVersion}`);
-// ── 互動收集（缺什麼問什麼；非互動時取預設） ──
-/**
- * 缺什麼問什麼：旗標已給就用它，非互動（`--yes` 或無 TTY）取預設，其餘才問。
- *
- * 泛型鎖住「問到的答案與預設值同型」：`p.text` 回字串、`p.confirm` 回布林，
- * 兩者的呼叫點接著就把值餵給只收該型別的下游。
- */
-async function ask(value, prompt) {
-    if (value !== undefined)
-        return value;
-    if (!interactive)
-        return prompt.fallback;
-    const answer = await prompt.run();
-    if (p.isCancel(answer)) {
-        p.cancel(t('scaffold.cancelled', locale));
-        process.exit(1);
+function fail(error) {
+    const record = errorCode(error.code);
+    const message = t(record.messageKey, locale, messageParams(error.details));
+    const firstLine = message.split('\n')[0];
+    if (jsonRequested) {
+        console.log(JSON.stringify({ formatVersion: FORMAT_VERSION, error: { code: error.code, message: firstLine, details: error.details } }));
+        console.error(firstLine);
     }
-    return answer;
-}
-const targetDirRaw = await ask(args._[0], {
-    fallback: 'promptex-project',
-    run: () => p.text({
-        message: t('scaffold.prompt.target_dir', locale),
-        placeholder: 'promptex-project',
-        defaultValue: 'promptex-project',
-    }),
-});
-const targetDir = resolve(String(targetDirRaw));
-const template = await ask(args.template, {
-    fallback: 'project',
-    run: () => p.select({
-        message: t('scaffold.prompt.template', locale),
-        options: [
-            { value: 'project', label: t('scaffold.template_option.project', locale) },
-            { value: 'plugin', label: t('scaffold.template_option.plugin', locale) },
-            { value: 'adapter', label: t('scaffold.template_option.adapter', locale) },
-        ],
-    }),
-});
-if (!TEMPLATES.includes(template)) {
-    bail(t('scaffold.error.template_unsupported', locale, { template, choices: TEMPLATES.join(separator) }));
+    else {
+        console.error(message);
+    }
+    process.exit(record.exitCode);
 }
-const defaultName = normalizeName(basename(targetDir));
-const name = normalizeName(String(await ask(args.name, {
-    fallback: defaultName,
-    run: () => p.text({ message: t('scaffold.prompt.name', locale), defaultValue: defaultName, placeholder: defaultName }),
-})));
-const wantGit = args.git !== undefined
-    ? args.git
-    : await ask(undefined, {
-        fallback: true,
-        run: () => p.confirm({ message: t('scaffold.prompt.git_init', locale), initialValue: true }),
-    });
-// ── 環境檢查：目標目錄非空即列衝突、零寫入退出（比照 promptex init）。 ──
-if (existsSync(targetDir)) {
-    const entries = readdirSync(targetDir);
-    if (entries.length > 0) {
-        const listing = `${entries.slice(0, 10).join(separator)}${entries.length > 10 ? '…' : ''}`;
-        bail(t('scaffold.error.dir_not_empty', locale, { path: targetDir, entries: listing }));
+function parseArgs() {
+    const args = mri(rawArgv, { boolean: BOOLEAN_FLAGS, string: STRING_FLAGS, alias: { h: 'help' } });
+    // mri accepts any flag, so reject the ones this tool does not declare (a removed
+    // --ref must fail loudly instead of being ignored). `--no-git` arrives as `git`.
+    const knownFlags = new Set(['_', 'h', ...BOOLEAN_FLAGS, ...STRING_FLAGS]);
+    for (const key of Object.keys(args)) {
+        if (knownFlags.has(key))
+            continue;
+        // 回報使用者打的原字（`-x`、`--ref`），與另兩個 create 相同；`--ref=main` 只取旗標名。
+        const raw = rawArgv.find((a) => a === `-${key}` || a === `--${key}` || a.startsWith(`--${key}=`));
+        throw new CreateError('USAGE_UNKNOWN_ARGUMENT', { arg: raw?.split('=')[0] ?? `--${key}` });
+    }
+    // mri 把缺值的字串旗標填成空字串。
+    for (const key of STRING_FLAGS) {
+        const value = args[key];
+        if (value === '' || typeof value === 'boolean')
+            throw new CreateError('USAGE_FLAG_MISSING_VALUE', { flag: `--${key}` });
     }
+    if (args._.length > 1)
+        throw new CreateError('USAGE_UNKNOWN_ARGUMENT', { arg: String(args._[1]) });
+    if (args.json && !args['dry-run'])
+        throw new CreateError('USAGE_JSON_REQUIRES_DRY_RUN');
+    return args;
+}
+/** 三個 create 共用的說明版面：用法、兩種模式、旗標逐行。 */
+function helpText() {
+    const options = [
+        ['[target-dir]', 'scaffold.help.target_dir'],
+        ['--template', 'scaffold.help.template'],
+        ['--name', 'scaffold.help.name'],
+        ['--source', 'scaffold.help.source'],
+        ['--git, --no-git', 'scaffold.help.git'],
+        ['--install', 'scaffold.help.install'],
+        ['--force', 'scaffold.help.force'],
+        ['--dry-run', 'scaffold.help.dry_run'],
+        ['--json', 'scaffold.help.json'],
+        ['--yes', 'scaffold.help.yes'],
+        ['--locale', 'scaffold.help.locale'],
+    ];
+    return [
+        t('scaffold.usage.js', locale),
+        '',
+        t('scaffold.usage.modes', locale),
+        '',
+        t('scaffold.usage.options', locale),
+        ...options.map(([flag, key]) => `  ${flag.padEnd(16)}${t(key, locale)}`),
+    ].join('\n');
 }
-const gitAvailable = spawnSync('git', ['--version'], { stdio: 'ignore' }).status === 0;
-if (!args.source && !gitAvailable)
-    bail(t('scaffold.error.git_required', locale));
-// ── 模板取得：--source 讀本地 checkout；否則淺 clone，GA 版預設 ref 綁本套件版本、預發布版取 main。 ──
-let sourceRoot;
-let sourceLabel;
-let cloneDir;
-if (args.source) {
-    sourceRoot = join(resolve(args.source), 'typescript');
-    sourceLabel = t('scaffold.source.local', locale, { path: resolve(args.source) });
+const REASON_KEYS = {
+    exists: 'scaffold.skip.exists',
+    'manifest-kept': 'scaffold.skip.manifest_kept',
+    'example-dir-exists': 'scaffold.skip.example_dir_exists',
+    'init-mode': 'scaffold.skip.init_mode',
+    'marker-present': 'scaffold.skip.marker_present',
+    symlink: 'scaffold.skip.symlink',
+    blocked: 'scaffold.skip.blocked',
+};
+/** 人讀的動作清單：依建立、覆寫、追加、跳過分組，組內依路徑排序。 */
+function actionLines(actions) {
+    const summary = summarize(actions);
+    const rows = [
+        ...summary.create.map((path) => [t('scaffold.action.create', locale), path]),
+        ...summary.overwrite.map((path) => [t('scaffold.action.overwrite', locale), path]),
+        ...summary.append.map((path) => [t('scaffold.action.append', locale), path]),
+        ...summary.skip.map(({ path, reason }) => [
+            t('scaffold.action.skip', locale),
+            `${path} (${t(REASON_KEYS[reason], locale)})`,
+        ]),
+    ];
+    const width = Math.max(0, ...rows.map(([label]) => label.length));
+    return rows.map(([label, text]) => `  ${label.padEnd(width)}  ${text}`);
+}
+/** `--dry-run --json` 的成功輸出。欄位與另兩個 create 逐欄相同，只有 package 與 language 依語言而異。 */
+function report(opts) {
+    return {
+        formatVersion: FORMAT_VERSION,
+        package: PACKAGE,
+        language: LANGUAGE,
+        mode: opts.mode,
+        alreadyInitialized: opts.existingConfig !== null,
+        existingConfig: opts.existingConfig,
+        target: opts.targetDir,
+        template: opts.template,
+        name: opts.name,
+        files: summarize(opts.actions),
+        git: opts.git,
+    };
 }
-else {
-    const { ref, showCloneHint } = resolveRef(args.ref, ownVersion);
-    cloneDir = mkdtempSync(join(tmpdir(), 'promptex-templates-'));
-    try {
-        execFileSync('git', ['clone', '--depth', '1', '--branch', ref, TEMPLATES_REPO, cloneDir], {
-            stdio: ['ignore', 'ignore', 'inherit'],
+async function main() {
+    const args = parseArgs();
+    if (args.help) {
+        console.log(helpText());
+        process.exit(0);
+    }
+    const interactive = !isNonInteractive(Boolean(process.stdin.isTTY), Boolean(args.yes) || Boolean(args.json), process.env);
+    const say = (line) => {
+        if (jsonRequested)
+            return;
+        if (interactive)
+            p.log.message(line);
+        else
+            console.log(line);
+    };
+    // 目前沒有必填輸入（m008 d007：非互動時全部有預設值）。新增必填輸入時把它的
+    // hasDefault 設成 false，非互動執行就會以結束碼 2 一次列出所有缺的旗標。
+    const missing = missingInputs([
+        { flag: '[target-dir]', provided: args._[0] !== undefined, hasDefault: true },
+        { flag: '--template', provided: args.template !== undefined, hasDefault: true },
+        { flag: '--name', provided: args.name !== undefined, hasDefault: true },
+    ], interactive);
+    if (missing.length > 0)
+        throw new CreateError('USAGE_MISSING_INPUTS', { flags: missing });
+    if (interactive)
+        p.intro(`create-promptex-js v${ownVersion}`);
+    /** 缺什麼問什麼：旗標已給就用它，非互動取預設，其餘才問。 */
+    async function ask(value, prompt) {
+        if (value !== undefined)
+            return value;
+        if (!interactive)
+            return prompt.fallback;
+        const answer = await prompt.run();
+        if (p.isCancel(answer))
+            throw new CreateError('RUN_CANCELLED');
+        return answer;
+    }
+    // ── 目標與模式：輸出的第一行說明所選的模式。 ──
+    const targetRaw = await ask(args._[0] === undefined ? undefined : String(args._[0]), {
+        fallback: 'promptex-project',
+        run: () => p.text({
+            message: t('scaffold.prompt.target_dir', locale),
+            placeholder: 'promptex-project',
+            defaultValue: 'promptex-project',
+        }),
+    });
+    const targetDir = resolve(String(targetRaw));
+    const state = inspectTarget(targetDir);
+    if (state.mode === 'create') {
+        say(t('scaffold.mode.create', locale, { path: targetDir }));
+    }
+    else {
+        const shown = `${state.unlisted.slice(0, 10).join(separator)}${state.unlisted.length > 10 ? '…' : ''}`;
+        say(t('scaffold.mode.init', locale, { path: targetDir, entries: shown }));
+    }
+    // 初始化模式只支援 project（m008 d007），不問模板。
+    const template = state.mode === 'init'
+        ? (args.template ?? 'project')
+        : await ask(args.template, {
+            fallback: 'project',
+            run: () => p.select({
+                message: t('scaffold.prompt.template', locale),
+                options: [
+                    { value: 'project', label: t('scaffold.template_option.project', locale) },
+                    { value: 'plugin', label: t('scaffold.template_option.plugin', locale) },
+                    { value: 'adapter', label: t('scaffold.template_option.adapter', locale) },
+                ],
+            }),
         });
+    if (!TEMPLATES.includes(template)) {
+        throw new CreateError('USAGE_TEMPLATE_UNSUPPORTED', { template, choices: TEMPLATES });
+    }
+    if (state.mode === 'init' && template !== 'project') {
+        throw new CreateError('USAGE_TEMPLATE_NEEDS_EMPTY_DIR', { template, path: targetDir, entries: state.unlisted });
     }
-    catch {
-        const hint = showCloneHint ? t('scaffold.error.clone_hint', locale) : '';
-        bail(t('scaffold.error.clone_failed', locale, { ref, hint }));
+    const defaultName = normalizeName(basename(targetDir));
+    const existingConfig = state.mode === 'init' ? findConfig(targetDir) : null;
+    if (existingConfig !== null) {
+        const git = { init: false, reason: 'already-initialized' };
+        if (jsonRequested) {
+            console.log(JSON.stringify(report({ mode: state.mode, existingConfig, targetDir, template, name: defaultName, actions: [], git })));
+        }
+        else {
+            say(t('scaffold.already_initialized', locale, { config: existingConfig }));
+        }
+        process.exit(0);
     }
-    sourceRoot = join(cloneDir, 'typescript');
-    sourceLabel = `promptex-templates@${ref}`;
+    const name = normalizeName(String(await ask(args.name, {
+        fallback: defaultName,
+        run: () => p.text({ message: t('scaffold.prompt.name', locale), defaultValue: defaultName, placeholder: defaultName }),
+    })));
+    // ── git：在既有工作樹內就不 init，也不問。 ──
+    const insideWorktree = isInsideGitWorktree(targetDir);
+    const gitAvailable = commandAvailable('git');
+    if (args.git === true && !gitAvailable)
+        throw new CreateError('RUN_GIT_UNAVAILABLE');
+    const wantGit = args.git !== undefined
+        ? args.git
+        : insideWorktree
+            ? false
+            : await ask(undefined, {
+                fallback: true,
+                run: () => p.confirm({ message: t('scaffold.prompt.git_init', locale), initialValue: true }),
+            });
+    const git = insideWorktree
+        ? { init: false, reason: 'inside-worktree' }
+        : !wantGit
+            ? { init: false, reason: 'disabled' }
+            : !gitAvailable
+                ? { init: false, reason: 'unavailable' }
+                : { init: true, reason: null };
+    // ── 模板取得：預設用內附模板；--source 讀本地模板目錄。 ──
+    const templatesRoot = args.source ? resolve(args.source) : BUNDLED_TEMPLATES;
+    const sourceLabel = args.source
+        ? t('scaffold.source.local', locale, { path: templatesRoot })
+        : t('scaffold.source.bundled', locale, { version: ownVersion });
+    const starterDir = join(templatesRoot, `${template}-starter`);
+    if (!existsSync(starterDir))
+        throw new CreateError('RUN_STARTER_MISSING', { template, path: starterDir });
+    const files = loadTemplateFiles(starterDir, name);
+    // ── 計畫：逐檔決定建立、覆寫、追加或跳過。--dry-run 到此為止。 ──
+    const actions = planFiles(targetDir, files, state.mode, template, Boolean(args.force));
+    if (args['dry-run']) {
+        if (jsonRequested) {
+            console.log(JSON.stringify(report({ mode: state.mode, existingConfig: null, targetDir, template, name, actions, git })));
+        }
+        else {
+            say(t('scaffold.dry_run.header', locale, { path: targetDir, source: sourceLabel }));
+            for (const line of actionLines(actions))
+                say(line);
+            if (git.reason === 'inside-worktree')
+                say(t('scaffold.git.inside_worktree', locale));
+            if (git.init)
+                say(t('scaffold.git.will_init', locale));
+        }
+        process.exit(0);
+    }
+    applyPlan(targetDir, actions);
+    // ── 後處理：git init（可選）、--install 裝依賴。兩種模式都不自動 commit。 ──
+    if (git.init)
+        spawnSync('git', ['init', '--quiet'], { cwd: targetDir, stdio: 'inherit' });
+    const pm = detectPackageManager(targetDir, () => commandAvailable('pnpm'));
+    if (args.install) {
+        const command = PM_COMMANDS[pm].install;
+        if (!commandAvailable(pm))
+            throw new CreateError('RUN_INSTALL_TOOL_MISSING', { command });
+        const [bin, ...rest] = command.split(' ');
+        const r = spawnSync(bin, rest, { cwd: targetDir, stdio: 'inherit', shell: process.platform === 'win32' });
+        if (r.status !== 0)
+            throw new CreateError('RUN_INSTALL_FAILED', { command });
+    }
+    // ── 稽核輸出：做了什麼、來源為何、下一步。 ──
+    const summary = summarize(actions);
+    const count = summary.create.length + summary.overwrite.length + summary.append.length;
+    say(t('scaffold.done.written', locale, { count, path: targetDir, source: sourceLabel }));
+    for (const line of actionLines(actions))
+        say(line);
+    if (git.reason === 'inside-worktree')
+        say(t('scaffold.git.inside_worktree', locale));
+    const manifestKept = summary.skip.some((s) => s.path === 'package.json');
+    const steps = nextSteps({ template, cd: cdPath(targetDir, process.cwd()), manifestKept, installed: Boolean(args.install), pm });
+    const nextBlock = `${t('scaffold.done.next_steps', locale)}\n${steps.map((s, i) => `  ${i + 1}. ${s}`).join('\n')}`;
+    if (interactive)
+        p.outro(nextBlock);
+    else
+        console.log(nextBlock);
 }
-const starterDir = join(sourceRoot, `${template}-starter`);
-if (!existsSync(starterDir))
-    bail(t('scaffold.error.starter_missing', locale, { template, path: starterDir }));
-// ── 具現化：複製、佔位替換、_gitignore 改名。 ──
+// ── 具現化：佔位替換、_gitignore 改名。 ──
 /**
  * 把一則訊息文字變成可直接嵌進單引號字串字面量的形態。
  *
@@ -159,71 +346,64 @@ if (!existsSync(starterDir))
 function escapeForLiteral(text) {
     return text.replaceAll('\\', '\\\\').replaceAll('\n', '\\n').replaceAll("'", "\\'");
 }
-const tokens = {
-    '{{name}}': name,
-    '{{snakeName}}': name.replaceAll('-', '_'),
-    '{{unitName}}': name,
-    '{{promptexVersion}}': ownVersion,
-    // 模板的範例資源文字（ADR-030「一次性的起手內容」、AC-523）：模板檔以佔位符留位，
-    // 寫檔當下代入本次語系的那一份。實作指引註解不在此列，它們在模板裡就是英文。
-    '{{adapterDemoRuleContent}}': escapeForLiteral(t('template.adapter_demo.rule_content', locale)),
-    '{{adapterDemoSkillContent}}': escapeForLiteral(t('template.adapter_demo.skill_content', locale)),
-    '{{adapterDemoSkillDescription}}': escapeForLiteral(t('template.adapter_demo.skill_description', locale)),
-    '{{adapterDemoSkillWhenToUse}}': escapeForLiteral(t('template.adapter_demo.skill_when_to_use', locale)),
-    '{{demoRuleName}}': escapeForLiteral(t('template.demo.rule_name', locale)),
-    '{{demoSkillName}}': escapeForLiteral(t('template.demo.skill_name', locale)),
-    '{{exampleRuleIntro}}': escapeForLiteral(t('template.example_rule.intro', locale)),
-    '{{exampleRuleName}}': escapeForLiteral(t('template.example_rule.name', locale)),
-    '{{exampleRuleOtherStates}}': escapeForLiteral(t('template.example_rule.other_states', locale)),
-    '{{exampleRuleScoped}}': escapeForLiteral(t('template.example_rule.scoped', locale)),
-    '{{exampleSkillDescription}}': escapeForLiteral(t('template.example_skill.description', locale)),
-    '{{exampleSkillIntro}}': escapeForLiteral(t('template.example_skill.intro', locale)),
-    '{{exampleSkillInvoked}}': escapeForLiteral(t('template.example_skill.invoked', locale)),
-    '{{exampleSkillInvokedRs}}': escapeForLiteral(t('template.example_skill.invoked_rs', locale)),
-    '{{exampleSkillName}}': escapeForLiteral(t('template.example_skill.name', locale)),
-    '{{exampleSkillWhenToUse}}': escapeForLiteral(t('template.example_skill.when_to_use', locale)),
-    '{{pluginDemoRuleContent}}': escapeForLiteral(t('template.plugin_demo.rule_content', locale)),
-    '{{pluginDemoSkillContent}}': escapeForLiteral(t('template.plugin_demo.skill_content', locale)),
-    '{{pluginDemoSkillDescription}}': escapeForLiteral(t('template.plugin_demo.skill_description', locale)),
-    '{{pluginDemoSkillWhenToUse}}': escapeForLiteral(t('template.plugin_demo.skill_when_to_use', locale)),
-};
-const substitute = (text) => Object.entries(tokens).reduce((acc, [token, value]) => acc.replaceAll(token, value), text);
-function walk(dir, rel = '') {
-    const out = [];
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const relPath = rel ? `${rel}/${entry.name}` : entry.name;
-        if (entry.isDirectory())
-            out.push(...walk(join(dir, entry.name), relPath));
-        else
-            out.push(relPath);
-    }
-    return out;
+function loadTemplateFiles(starterDir, name) {
+    const tokens = {
+        '{{name}}': name,
+        '{{snakeName}}': name.replaceAll('-', '_'),
+        '{{unitName}}': name,
+        '{{promptexVersion}}': ownVersion,
+        // 模板的範例資源文字（ADR-030「一次性的起手內容」、AC-523）：模板檔以佔位符留位，
+        // 寫檔當下代入本次語系的那一份。實作指引註解不在此列，它們在模板裡就是英文。
+        '{{adapterDemoRuleContent}}': escapeForLiteral(t('template.adapter_demo.rule_content', locale)),
+        '{{adapterDemoSkillContent}}': escapeForLiteral(t('template.adapter_demo.skill_content', locale)),
+        '{{adapterDemoSkillDescription}}': escapeForLiteral(t('template.adapter_demo.skill_description', locale)),
+        '{{adapterDemoSkillWhenToUse}}': escapeForLiteral(t('template.adapter_demo.skill_when_to_use', locale)),
+        '{{demoRuleName}}': escapeForLiteral(t('template.demo.rule_name', locale)),
+        '{{demoSkillName}}': escapeForLiteral(t('template.demo.skill_name', locale)),
+        '{{exampleRuleIntro}}': escapeForLiteral(t('template.example_rule.intro', locale)),
+        '{{exampleRuleName}}': escapeForLiteral(t('template.example_rule.name', locale)),
+        '{{exampleRuleOtherStates}}': escapeForLiteral(t('template.example_rule.other_states', locale)),
+        '{{exampleRuleScoped}}': escapeForLiteral(t('template.example_rule.scoped', locale)),
+        '{{exampleSkillDescription}}': escapeForLiteral(t('template.example_skill.description', locale)),
+        '{{exampleSkillIntro}}': escapeForLiteral(t('template.example_skill.intro', locale)),
+        '{{exampleSkillInvoked}}': escapeForLiteral(t('template.example_skill.invoked', locale)),
+        '{{exampleSkillInvokedRs}}': escapeForLiteral(t('template.example_skill.invoked_rs', locale)),
+        '{{exampleSkillName}}': escapeForLiteral(t('template.example_skill.name', locale)),
+        '{{exampleSkillWhenToUse}}': escapeForLiteral(t('template.example_skill.when_to_use', locale)),
+        '{{pluginDemoRuleContent}}': escapeForLiteral(t('template.plugin_demo.rule_content', locale)),
+        '{{pluginDemoSkillContent}}': escapeForLiteral(t('template.plugin_demo.skill_content', locale)),
+        '{{pluginDemoSkillDescription}}': escapeForLiteral(t('template.plugin_demo.skill_description', locale)),
+        '{{pluginDemoSkillWhenToUse}}': escapeForLiteral(t('template.plugin_demo.skill_when_to_use', locale)),
+    };
+    const substitute = (text) => Object.entries(tokens).reduce((acc, [token, value]) => acc.replaceAll(token, value), text);
+    const walk = (dir, rel = '') => {
+        const out = [];
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                out.push(...walk(join(dir, entry.name), relPath));
+            else
+                out.push(relPath);
+        }
+        return out;
+    };
+    return walk(starterDir).map((rel) => {
+        const dest = substitute(rel);
+        let content;
+        try {
+            content = readFileSync(join(starterDir, rel), 'utf8');
+        }
+        catch (e) {
+            throw new CreateError('RUN_READ_FAILED', { path: join(starterDir, rel), detail: e instanceof Error ? e.message : String(e) });
+        }
+        return { rel: dest === '_gitignore' ? '.gitignore' : dest, content: substitute(content) };
+    });
 }
-const written = [];
-for (const rel of walk(starterDir)) {
-    let destRel = substitute(rel);
-    if (destRel === '_gitignore')
-        destRel = '.gitignore';
-    const destPath = join(targetDir, destRel);
-    mkdirSync(dirname(destPath), { recursive: true });
-    writeFileSync(destPath, substitute(readFileSync(join(starterDir, rel), 'utf8')));
-    written.push(destRel);
+try {
+    await main();
 }
-if (cloneDir)
-    rmSync(cloneDir, { recursive: true, force: true });
-// ── 後處理：git init（可選）、--install 裝依賴。 ──
-if (wantGit && gitAvailable)
-    spawnSync('git', ['init', '--quiet'], { cwd: targetDir, stdio: 'inherit' });
-if (args.install) {
-    const r = spawnSync('npm', ['install'], { cwd: targetDir, stdio: 'inherit', shell: process.platform === 'win32' });
-    if (r.status !== 0)
-        bail(t('scaffold.error.install_failed.js', locale));
+catch (e) {
+    if (e instanceof CreateError)
+        fail(e);
+    throw e;
 }
-// ── 稽核輸出：寫了什麼、來源為何、下一步。 ──
-p.log.success(t('scaffold.done.written', locale, { count: written.length, path: targetDir, source: sourceLabel }));
-for (const rel of written)
-    p.log.message(`  ${rel}`);
-const nextSteps = template === 'project'
-    ? [`cd ${targetDirRaw}`, ...(args.install ? [] : ['npm install']), 'npm run install:prompts']
-    : [`cd ${targetDirRaw}`, ...(args.install ? [] : ['npm install']), 'npm run build', 'cd example && npx promptex build --install'];
-p.outro(`${t('scaffold.done.next_steps', locale)}\n${nextSteps.map((s, i) => `  ${i + 1}. ${s}`).join('\n')}`);