create-promptex-js 0.0.1-alpha.1 → 1.0.0

package/README.md

@@ -1,55 +1,40 @@
-# create-promptex-js（alpha 原型）
+# create-promptex-js
 
-promptex 專案鷹架的**最小原型**。產出一個可立即建置的專案骨架：宣告一份
-skill，建置後得到 Claude Code 的 `SKILL.md`。
+Scaffold a [promptex](https://github.com/promptex-ai/promptex) TypeScript
+project, plugin or adapter from the
+[promptex-templates](https://github.com/promptex-ai/promptex-templates)
+starters.
 
-## 這不是什麼
-
-本套件是早期 alpha。骨架只有四個檔案、一份範例宣告，沒有多單元配置、沒有
-多平台選擇、沒有外掛與轉接器。正式版把骨架收在核心（`promptex init`），
-本原型自帶一份副本，正式版發布時會被整份取代。
-
-介面與骨架內容在正式版之前都會變，不保證任何相容性。
-
-## 用法
-
-不需要事先安裝，`npm create` 會取得後直接執行。需要 Node.js 22.14 以上。
-
-```bash
-npm create promptex-js my-prompts
-```
-
-產出：
-
-```text
-my-prompts/
-├── .gitignore
-├── README.md
-├── package.json
-└── prompts/skill.ts
+```console
+npm create promptex-js
 ```
 
-（上為 `--lang ts` 的形態；`--lang python` 產出 `pyproject.toml` 與
-`prompts/skill.py`，`--lang rust` 產出 `Cargo.toml` 與 `src/main.rs`。）
-
-### 選項
+Interactive by default; every answer has a flag for non-interactive use:
 
-```text
-npm create promptex-js <目錄> [--lang ts|python|rust] [--yes]
-
-  --lang <語言>  骨架語言，預設 ts
-  --yes          目標目錄已有同名檔案時仍覆寫
+```console
+npm create promptex-js my-prompts -- --template project --name my-prompts --no-git --yes
 ```
 
-非互動：全部輸入取自位置參數與旗標，與正式版 `promptex init` 的介面一致。
-目標目錄已有同名檔案且未帶 `--yes` 時**一個檔案都不寫**，不留半套骨架。
-
-## 三生態等價
-
-`create-promptex-js`、`create-promptex-py`、`create-promptex-rs` 對同一組
-參數產出逐字相同的檔案樹。正式版靠骨架住核心由結構保證，本原型是三份獨立
-實作，等價由產物比對承擔。
-
-## 授權
-
-MIT OR Apache-2.0，見 `LICENSE-MIT` 與 `LICENSE-APACHE`。
+| Flag | Meaning |
+| :--- | :--- |
+| `--template <t>` | `project`（消費專案）、`plugin`、`adapter` |
+| `--name <n>` | kebab-case 名稱；預設取目標目錄名正規化 |
+| `--ref <r>` | 抓 promptex-templates 的指定 branch／tag；預設 `v<本套件版本>` |
+| `--source <p>` | 改用本地 promptex-templates checkout（離線與開發用） |
+| `--git` / `--no-git` | 是否 `git init`；互動預設是 |
+| `--install` | 鷹架後直接 `npm install`；預設只印下一步 |
+| `--yes` | 跳過互動，全部取預設或旗標值 |
+| `--locale <l>` | 訊息與範例資源的語系：`en`（預設）或 `zh-Hant` |
+
+語系未以 `--locale` 指定時，依序讀 `PROMPTEX_LOCALE`、`LANGUAGE`、`LC_ALL`、
+`LC_MESSAGES`、`LANG`，都沒有就用英文；`LC_ALL=C` 意為關掉在地化。`zh-TW`、
+`zh-HK`、`zh-MO` 與 `zh-Hant-*` 都對到 `zh-Hant`。它同時決定鋪出來的範例資源
+用哪個語系寫（[ADR-030](https://github.com/promptex-ai/ssot)）：那份內容從產出
+當下起就歸你，框架不再改寫它。plugin 與 adapter 骨架裡教你怎麼填的註解維持英文。
+
+目標目錄非空時列出既有項目、零寫入退出。模板不內嵌：單一來源住
+promptex-templates 倉庫，鷹架時以 git 取得對應版本 tag（需要 git；
+`{{promptexVersion}}` 於鷹架當下以本套件版本填入，三套件與 SDK 同版發布）。
+
+`promptex init` 與本工具的分工：init 在既有專案就地補上 promptex（非互動、
+極簡骨架）；本工具從零開一個 repo（互動、三種模板、git init）。

package/bin/create-promptex-js.mjs

@@ -1,63 +1,7 @@
 #!/usr/bin/env node
-// create-promptex-js 的進入點。`npm create promptex-js <目錄>` 解析到本套件。
+// create-promptex-js 的轉發殼。
 //
-// 非互動：全部輸入取自位置參數與旗標，與正式版 `promptex init` 的介面一致。
-// 骨架決策不在此處，見 ../dist/index.js 的 skeleton。
-
-import { LANGS, scaffold } from '../dist/index.js'
-
-const USAGE = `create-promptex-js（alpha 原型）
-
-用法：
-  npm create promptex-js <目錄> -- [--lang ts|python|rust] [--yes]
-
-選項：
-  --lang <語言>  骨架語言，預設 ts
-  --yes          目標目錄已有同名檔案時仍覆寫
-  --help         顯示本說明
-`
-
-function parseArgs(argv) {
-  const args = { dir: null, lang: 'ts', assumeYes: false }
-  for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i]
-    if (token === '--yes' || token === '-y') args.assumeYes = true
-    else if (token === '--lang') {
-      const value = argv[i + 1]
-      if (value === undefined) throw new Error('--lang 後面缺少值')
-      if (!LANGS.includes(value)) throw new Error(`不支援的語言：${value}（可用：${LANGS.join('、')}）`)
-      args.lang = value
-      i += 1
-    } else if (token.startsWith('-')) throw new Error(`未知的選項：${token}`)
-    else if (args.dir === null) args.dir = token
-    else throw new Error(`多餘的位置參數：${token}`)
-  }
-  if (args.dir === null) throw new Error('缺少目標目錄。用法：npm create promptex-js <目錄>')
-  return args
-}
-
-async function main() {
-  const argv = process.argv.slice(2)
-  if (argv.includes('--help') || argv.includes('-h')) {
-    process.stdout.write(USAGE)
-    return
-  }
-
-  const args = parseArgs(argv)
-  const outcome = await scaffold(args.dir, args.lang, args.assumeYes)
-
-  if (outcome.aborted) {
-    process.stderr.write(`目標目錄已有同名檔案，未寫入任何檔案：\n`)
-    for (const path of outcome.conflicts) process.stderr.write(`  ${path}\n`)
-    process.stderr.write(`確定要覆寫請加 --yes。\n`)
-    process.exitCode = 1
-    return
-  }
-
-  for (const path of outcome.written) process.stdout.write(`${path}\n`)
-}
-
-await main().catch((error) => {
-  process.stderr.write(`${error.message}\n`)
-  process.exitCode = 1
-})
+// 邏輯住 `src/index.ts`（發布物為 `dist/index.js`），本檔只負責被 npm 當成
+// bin 執行：鷹架的流程是頂層的一段腳本而非可呼叫的函式（它從 argv 讀到底、
+// 逐步問完就結束），因此這裡 import 即執行，不另外呼叫誰。
+import '../dist/index.js'

package/dist/default-ref.d.ts

@@ -0,0 +1,6 @@
+export declare function defaultRef(version: string): string;
+/** `showCloneHint`：clone 失敗時是否附上「tag 可能尚未建立」提示，只在 GA 預設 ref 時為真。 */
+export declare function resolveRef(explicit: string | undefined, version: string): {
+    ref: string;
+    showCloneHint: boolean;
+};

package/dist/default-ref.js

@@ -0,0 +1,14 @@
+// 預設 templates ref 的判定（決策 d006）。三個 create-* 鷹架規則一致：
+// GA 版號（X.Y.Z）抓對應 tag `v<版本>`；帶預發布後綴（-alpha.N、-beta.N、-rc.N 等）
+// 的版本，tag 不一定存在，預設抓 `main`；使用者給 --ref 一律照用。
+const GA_VERSION = /^\d+\.\d+\.\d+$/;
+export function defaultRef(version) {
+    return GA_VERSION.test(version) ? `v${version}` : 'main';
+}
+/** `showCloneHint`：clone 失敗時是否附上「tag 可能尚未建立」提示，只在 GA 預設 ref 時為真。 */
+export function resolveRef(explicit, version) {
+    if (explicit)
+        return { ref: explicit, showCloneHint: false };
+    const ref = defaultRef(version);
+    return { ref, showCloneHint: ref !== 'main' };
+}

package/dist/index.d.ts

@@ -1,22 +1,2 @@
-/** 骨架支援的語言。與 `promptex init --lang` 的取值一致。 */
-export type Lang = 'ts' | 'python' | 'rust';
-export declare const LANGS: readonly Lang[];
-/**
- * 一份骨架的全部檔案，鍵為相對路徑。
- *
- * 純計算、不碰檔案系統：讓「骨架長什麼樣」可被直接比對，不必先寫到磁碟。
- */
-export declare function skeleton(name: string, lang: Lang): Record<string, string>;
-/** 一次初始化的處置結果。`aborted` 為真時 `written` 必為空。 */
-export interface Outcome {
-    aborted: boolean;
-    conflicts: string[];
-    written: string[];
-}
-/**
- * 在目標目錄產出骨架。
- *
- * 全有全無：有同名檔案且未帶 assumeYes 時一個檔案都不寫，避免留下半套骨架。
- * 這與正式版 `promptex init` 的衝突處置一致。
- */
-export declare function scaffold(targetDir: string, lang: Lang, assumeYes: boolean): Promise<Outcome>;
+#!/usr/bin/env node
+export declare function normalizeName(raw: string): string;

package/dist/index.js

@@ -1,177 +1,229 @@
-// create-promptex-js（alpha 原型）：產出可立即建置的 promptex 專案骨架。
+#!/usr/bin/env node
+// 鷹架 CLI：從 promptex-templates 倉庫開出 TypeScript 的 project／plugin／
+// adapter 專案。六階段：環境檢查 → 互動收集 → 模板取得 → 具現化 → 後處理 →
+// 稽核輸出；非互動時（--yes 或無 TTY）全部取預設或旗標值。
 //
-// 骨架內容以資料承載（見 skeleton），三個生態的 create-promptex-* 產出逐字
-// 相同的檔案樹。正式版把骨架收在核心（promptex_core::init），本原型的三份
-// 實作各持一份副本，等價由 verify-promptex-poc.sh 的產物比對承擔。
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve, basename } from 'node:path';
-export const LANGS = ['ts', 'python', 'rust'];
-/** 專案名稱的合法形態。作為套件名與 crate 名，字元集取三個生態的交集。 */
-const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-const SKILL_ID = 'commit-helper';
-const SKILL_NAME = 'Commit 訊息協助';
-const SKILL_WHEN = '當使用者要求撰寫 commit 訊息時使用';
-const SKILL_P1 = '依 Conventional Commits 撰寫：type(scope): subject。';
-const SKILL_P2 = 'subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。';
-/** 各語言的建置指令，投影進骨架 README 的建置段。 */
-const BUILD_COMMANDS = {
-    ts: ['npm install', 'npm run build'],
-    python: ['pip install --pre promptex-py', 'promptex build'],
-    rust: ['cargo run'],
-};
-const readme = (name, lang) => [
-    '# ' + name,
-    '',
-    '以 promptex 管理提示詞資源的專案骨架。',
-    '',
-    '## 建置',
-    '',
-    '```bash',
-    ...BUILD_COMMANDS[lang],
-    '```',
-    '',
-    '產出 `.claude/skills/' + SKILL_ID + '/SKILL.md`。',
-    '',
-    '## 下一步',
-    '',
-    '新增宣告，每份宣告投影成一份產物。',
-    '',
-].join('\n');
-const tsSkeleton = (name) => ({
-    'package.json': JSON.stringify({
-        name,
-        private: true,
-        type: 'module',
-        scripts: { build: 'promptex build' },
-        dependencies: { 'promptex-js': '0.0.1-alpha.1' },
-    }, null, 2) + '\n',
-    'prompts/skill.ts': [
-        "import { defineSkill } from 'promptex-js'",
-        '',
-        'export const commitHelper = defineSkill({',
-        "  id: '" + SKILL_ID + "',",
-        "  name: '" + SKILL_NAME + "',",
-        "  config: { whenToUse: '" + SKILL_WHEN + "' },",
-        '  content: [',
-        "    '" + SKILL_P1 + "',",
-        "    '" + SKILL_P2 + "',",
-        '  ],',
-        '})',
-        '',
-    ].join('\n'),
-    '.gitignore': 'node_modules/\n',
-    'README.md': readme(name, 'ts'),
-});
-const pythonSkeleton = (name) => ({
-    'pyproject.toml': [
-        '[project]',
-        'name = "' + name + '"',
-        'version = "0.0.0"',
-        'requires-python = ">=3.10"',
-        'dependencies = ["promptex-py==0.0.1a1"]',
-        '',
-    ].join('\n'),
-    'prompts/skill.py': [
-        'from promptex import config, define_skill',
-        '',
-        'commit_helper = define_skill(',
-        '    "' + SKILL_ID + '",',
-        '    "' + SKILL_NAME + '",',
-        '    config=config(when_to_use="' + SKILL_WHEN + '"),',
-        '    content=[',
-        '        "' + SKILL_P1 + '",',
-        '        "' + SKILL_P2 + '",',
-        '    ],',
-        ')',
-        '',
-    ].join('\n'),
-    '.gitignore': '__pycache__/\n',
-    'README.md': readme(name, 'python'),
-});
-const rustSkeleton = (name) => ({
-    'Cargo.toml': [
-        '[package]',
-        'name = "' + name + '"',
-        'version = "0.0.0"',
-        'edition = "2021"',
-        '',
-        '[dependencies]',
-        'promptex-rs = "0.0.1-alpha.1"',
-        '',
-    ].join('\n'),
-    'src/main.rs': [
-        'use promptex_rs::{build, define_skill, CapabilityConfig, SkillDef};',
-        '',
-        'fn main() -> Result<(), Box<dyn std::error::Error>> {',
-        '    define_skill(SkillDef {',
-        '        id: "' + SKILL_ID + '".into(),',
-        '        name: "' + SKILL_NAME + '".into(),',
-        '        config: CapabilityConfig::new().when_to_use("' + SKILL_WHEN + '"),',
-        '        content: vec![',
-        '            "' + SKILL_P1 + '".into(),',
-        '            "' + SKILL_P2 + '".into(),',
-        '        ],',
-        '    });',
-        '',
-        '    for path in build(".")? {',
-        '        println!("{}", path.display());',
-        '    }',
-        '    Ok(())',
-        '}',
-        '',
-    ].join('\n'),
-    '.gitignore': 'target/\n',
-    'README.md': readme(name, 'rust'),
+// 模板不內嵌：單一來源住 promptex-templates，GA 版預設抓與本套件版本對應的
+// tag（v<版本>），預發布版預設抓 main，--ref 覆寫、--source 改用本地 checkout
+// （離線與開發用）。
+//
+// 用法：
+//   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';
+import { fileURLToPath } from 'node:url';
+import * as p from '@clack/prompts';
+import mri from 'mri';
+import { resolveRef } from './default-ref.js';
+import { resolveLocale, t } from './messages.generated.js';
+const here = fileURLToPath(new URL('.', import.meta.url));
+const ownVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
+const TEMPLATES = ['project', 'plugin', 'adapter'];
+// 與 promptex init 的單元名正規化同一套規則（crates/promptex-core/src/init.rs）。
+const RESERVED_UNIT_NAMES = ['cache', 'preview', 'content', 'content-index', 'graph', 'main'];
+export function normalizeName(raw) {
+    let out = '';
+    for (const ch of raw.toLowerCase()) {
+        if (/[a-z0-9]/.test(ch))
+            out += ch;
+        else if (!out.endsWith('-'))
+            out += '-';
+    }
+    out = out.replace(/^-+|-+$/g, '');
+    return out === '' || RESERVED_UNIT_NAMES.includes(out) ? 'main' : out;
+}
+function bail(message) {
+    console.error(message);
+    process.exit(1);
+}
+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 separator = t('common.list_separator', locale);
+if (args.help) {
+    console.log(t('scaffold.usage.js', locale));
+    process.exit(0);
+}
+const interactive = process.stdin.isTTY && !args.yes;
+p.intro(`create-promptex-js v${ownVersion}`);
+// ── 互動收集（缺什麼問什麼；非互動時取預設） ──
 /**
- * 一份骨架的全部檔案，鍵為相對路徑。
+ * 缺什麼問什麼：旗標已給就用它，非互動（`--yes` 或無 TTY）取預設，其餘才問。
  *
- * 純計算、不碰檔案系統：讓「骨架長什麼樣」可被直接比對，不必先寫到磁碟。
+ * 泛型鎖住「問到的答案與預設值同型」：`p.text` 回字串、`p.confirm` 回布林，
+ * 兩者的呼叫點接著就把值餵給只收該型別的下游。
  */
-export function skeleton(name, lang) {
-    if (!NAME_PATTERN.test(name)) {
-        throw new Error(`專案名稱只能含英數與 . _ -，且須以英數開頭：${JSON.stringify(name)}`);
+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);
+    }
+    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) }));
+}
+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 }));
     }
-    if (lang === 'ts')
-        return tsSkeleton(name);
-    if (lang === 'python')
-        return pythonSkeleton(name);
-    if (lang === 'rust')
-        return rustSkeleton(name);
-    throw new Error(`不支援的語言：${lang}（可用：${LANGS.join('、')}）`);
 }
-const exists = async (path) => {
+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) });
+}
+else {
+    const { ref, showCloneHint } = resolveRef(args.ref, ownVersion);
+    cloneDir = mkdtempSync(join(tmpdir(), 'promptex-templates-'));
     try {
-        await readFile(path);
-        return true;
+        execFileSync('git', ['clone', '--depth', '1', '--branch', ref, TEMPLATES_REPO, cloneDir], {
+            stdio: ['ignore', 'ignore', 'inherit'],
+        });
     }
     catch {
-        return false;
+        const hint = showCloneHint ? t('scaffold.error.clone_hint', locale) : '';
+        bail(t('scaffold.error.clone_failed', locale, { ref, hint }));
     }
-};
+    sourceRoot = join(cloneDir, 'typescript');
+    sourceLabel = `promptex-templates@${ref}`;
+}
+const starterDir = join(sourceRoot, `${template}-starter`);
+if (!existsSync(starterDir))
+    bail(t('scaffold.error.starter_missing', locale, { template, path: starterDir }));
+// ── 具現化：複製、佔位替換、_gitignore 改名。 ──
 /**
- * 在目標目錄產出骨架。
+ * 把一則訊息文字變成可直接嵌進單引號字串字面量的形態。
+ *
+ * 本套件只鋪 TypeScript 模板，而模板一律以單引號包住文字佔位符，因此界定符固定
+ * 是單引號。反斜線必須第一個處理：先跳脫界定符會讓後補的反斜線又被自己跳脫一次。
  *
- * 全有全無：有同名檔案且未帶 assumeYes 時一個檔案都不寫，避免留下半套骨架。
- * 這與正式版 `promptex init` 的衝突處置一致。
+ * 此前不跳脫，於是英文的 `this skill's content` 一進模板就提前關閉字串，
+ * `npm create promptex-js` 鋪出來的 plugin 與 adapter 專案在第一次建置即失敗
+ * （中文的對應文字沒有 ASCII 引號，因此只有英文使用者踩得到）。核心的 `init`
+ * 骨架走另一條路徑，同一個缺陷在那裡另行修正（`promptex_core::init`）。
  */
-export async function scaffold(targetDir, lang, assumeYes) {
-    const dir = resolve(targetDir);
-    const files = skeleton(basename(dir), lang);
-    const paths = Object.keys(files).sort();
-    const conflicts = [];
-    for (const relative of paths) {
-        if (await exists(join(dir, relative)))
-            conflicts.push(relative);
-    }
-    if (conflicts.length > 0 && !assumeYes)
-        return { aborted: true, conflicts, written: [] };
-    const written = [];
-    for (const relative of paths) {
-        const path = join(dir, relative);
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, files[relative], 'utf8');
-        written.push(path);
+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 { aborted: false, conflicts, written };
+    return out;
+}
+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);
+}
+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));
 }
+// ── 稽核輸出：寫了什麼、來源為何、下一步。 ──
+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')}`);

package/dist/messages.generated.d.ts

@@ -0,0 +1,9 @@
+export declare const MESSAGES: Record<string, Record<string, string>>;
+/** 目錄認得的語系標籤。 */
+export type LocaleTag = 'en' | 'zh-Hant';
+/** POSIX 形態轉 BCP 47 並收斂為目錄認得的標籤；認不出來回 undefined。 */
+export declare function parseLocale(tag: string | undefined): LocaleTag | undefined;
+/** 依旗標與環境算出本次的語系。三項都認不出時回退路。 */
+export declare function resolveLocale(flag?: string): LocaleTag;
+/** 依語系取一則訊息，並以 `%{name}` 形態代入具名參數。 */
+export declare function t(key: string, locale: LocaleTag, params?: Record<string, string | number>): string;

package/dist/messages.generated.js

@@ -0,0 +1,296 @@
+// 本檔由 scripts/gen-messages.mjs 自動產生，請勿手改。
+//
+// 來源是核心的訊息目錄 crates/promptex-core/locales/（ADR-030）。要改文字就改那裡，
+// 再跑 `npm run gen:messages` 重新生成；直接改本檔會被核對閘擋下。
+export const MESSAGES = {
+    "common.list_separator": {
+        "en": ", ",
+        "zh-Hant": "、",
+    },
+    "scaffold.cancelled": {
+        "en": "Cancelled, no file was written.",
+        "zh-Hant": "已取消，未寫入任何檔案。",
+    },
+    "scaffold.done.next_steps": {
+        "en": "Next steps:",
+        "zh-Hant": "下一步：",
+    },
+    "scaffold.done.written": {
+        "en": "Wrote %{count} files → %{path} (template source: %{source})",
+        "zh-Hant": "已寫入 %{count} 個檔案 → %{path}（模板來源：%{source}）",
+    },
+    "scaffold.error.clone_failed": {
+        "en": "git clone promptex-templates@%{ref} failed. %{hint}",
+        "zh-Hant": "git clone promptex-templates@%{ref} 失敗。%{hint}",
+    },
+    "scaffold.error.clone_hint": {
+        "en": "The tag for this version may not have been created yet: use --ref main to get the latest, or --source <local-path> to take it offline.",
+        "zh-Hant": "此版本的 tag 可能尚未建立：用 --ref main 抓最新、或 --source <本地路徑> 離線取用。",
+    },
+    "scaffold.error.dir_create": {
+        "en": "Creating %{path} failed: %{reason}",
+        "zh-Hant": "建立 %{path} 失敗：%{reason}",
+    },
+    "scaffold.error.dir_not_empty": {
+        "en": "Target directory is not empty: %{path}\nExisting entries: %{entries}\nNo file was written.",
+        "zh-Hant": "目標目錄非空：%{path}\n既有項目：%{entries}\n未寫入任何檔案。",
+    },
+    "scaffold.error.file_read": {
+        "en": "Reading %{path} failed: %{reason}",
+        "zh-Hant": "讀取 %{path} 失敗：%{reason}",
+    },
+    "scaffold.error.file_write": {
+        "en": "Writing %{path} failed: %{reason}",
+        "zh-Hant": "寫入 %{path} 失敗：%{reason}",
+    },
+    "scaffold.error.flag_missing_value": {
+        "en": "%{flag} is missing its value",
+        "zh-Hant": "%{flag} 缺值",
+    },
+    "scaffold.error.git_required": {
+        "en": "Getting the template needs git (or give a local promptex-templates path with --source).",
+        "zh-Hant": "取得模板需要 git（或用 --source 指定本地 promptex-templates 路徑）。",
+    },
+    "scaffold.error.install_failed.js": {
+        "en": "npm install failed; the scaffold files were written, the dependencies were not installed.",
+        "zh-Hant": "npm install 失敗，鷹架檔案已寫入、依賴未裝。",
+    },
+    "scaffold.error.install_failed.py": {
+        "en": "uv sync failed; the scaffold files were written, the dependencies were not installed.",
+        "zh-Hant": "uv sync 失敗，鷹架檔案已寫入、依賴未裝。",
+    },
+    "scaffold.error.install_failed.rs": {
+        "en": "cargo fetch failed; the scaffold files were written, the dependencies were not fetched.",
+        "zh-Hant": "cargo fetch 失敗，鷹架檔案已寫入、依賴未取。",
+    },
+    "scaffold.error.starter_missing": {
+        "en": "The template source has no %{template}-starter: %{path}",
+        "zh-Hant": "模板來源缺 %{template}-starter：%{path}",
+    },
+    "scaffold.error.template_dir_read": {
+        "en": "Reading the template directory failed: %{reason}",
+        "zh-Hant": "讀取模板目錄失敗：%{reason}",
+    },
+    "scaffold.error.template_unsupported": {
+        "en": "Unsupported template: %{template} (available: %{choices})",
+        "zh-Hant": "不支援的模板：%{template}（可用：%{choices}）",
+    },
+    "scaffold.error.unknown_argument": {
+        "en": "Unrecognized argument: %{arg}",
+        "zh-Hant": "不認得的引數：%{arg}",
+    },
+    "scaffold.error.uv_missing": {
+        "en": "--install needs uv, but no uv executable was found; the scaffold files were written, the dependencies were not installed.",
+        "zh-Hant": "--install 需要 uv，但找不到 uv 執行檔；鷹架檔案已寫入、依賴未裝。",
+    },
+    "scaffold.help.install": {
+        "en": "run uv sync right after scaffolding",
+        "zh-Hant": "鷹架後直接 uv sync",
+    },
+    "scaffold.help.locale": {
+        "en": "message locale (en|zh-Hant), defaults to the environment variables then English",
+        "zh-Hant": "訊息語系（en|zh-Hant），預設依環境變數，再退回英文",
+    },
+    "scaffold.help.name": {
+        "en": "kebab-case name, defaults to the normalized target directory name",
+        "zh-Hant": "kebab-case 名稱，預設取目標目錄名正規化",
+    },
+    "scaffold.help.ref": {
+        "en": "take the given branch/tag of promptex-templates (defaults to v<this package's version>; pre-release versions default to main)",
+        "zh-Hant": "抓 promptex-templates 的指定 branch/tag（預設 v<本套件版本>；預發布版預設 main）",
+    },
+    "scaffold.help.source": {
+        "en": "use a local promptex-templates checkout instead (for offline and development use)",
+        "zh-Hant": "改用本地 promptex-templates checkout（離線與開發用）",
+    },
+    "scaffold.help.target_dir": {
+        "en": "target directory",
+        "zh-Hant": "目標目錄",
+    },
+    "scaffold.help.template": {
+        "en": "project|plugin|adapter",
+        "zh-Hant": "project|plugin|adapter",
+    },
+    "scaffold.help.yes": {
+        "en": "skip the interactive prompts, take defaults or flag values throughout",
+        "zh-Hant": "跳過互動，全部取預設或旗標值",
+    },
+    "scaffold.prompt.git_init": {
+        "en": "Initialize a git repository?",
+        "zh-Hant": "初始化 git 倉庫？",
+    },
+    "scaffold.prompt.git_init_yn": {
+        "en": "Initialize a git repository? (y/n)",
+        "zh-Hant": "初始化 git 倉庫？（y/n）",
+    },
+    "scaffold.prompt.name": {
+        "en": "Name (kebab-case)",
+        "zh-Hant": "名稱（kebab-case）",
+    },
+    "scaffold.prompt.target_dir": {
+        "en": "Target directory",
+        "zh-Hant": "目標目錄",
+    },
+    "scaffold.prompt.template": {
+        "en": "Template",
+        "zh-Hant": "模板",
+    },
+    "scaffold.prompt.template_choices": {
+        "en": "Template (%{choices})",
+        "zh-Hant": "模板（%{choices}）",
+    },
+    "scaffold.source.local": {
+        "en": "local template (%{path})",
+        "zh-Hant": "本地模板（%{path}）",
+    },
+    "scaffold.template_option.adapter": {
+        "en": "adapter: a publishable third-party platform adapter package",
+        "zh-Hant": "adapter：可發布的第三方平台 adapter 套件",
+    },
+    "scaffold.template_option.plugin": {
+        "en": "plugin: a publishable plugin package",
+        "zh-Hant": "plugin：可發布的 plugin 套件",
+    },
+    "scaffold.template_option.project": {
+        "en": "project: prompt source tree (a consuming project)",
+        "zh-Hant": "project：提示詞源碼樹（消費專案）",
+    },
+    "scaffold.usage.js": {
+        "en": "create-promptex-js [target-dir] --template project|plugin|adapter --name <kebab-name> [--ref <branch|tag>] [--source <local-path>] [--git|--no-git] [--install] [--yes] [--locale <locale>]",
+        "zh-Hant": "create-promptex-js [目標目錄] --template project|plugin|adapter --name <kebab 名> [--ref <branch|tag>] [--source <本地路徑>] [--git|--no-git] [--install] [--yes] [--locale <語系>]",
+    },
+    "scaffold.usage.py": {
+        "en": "uvx create-promptex-py [target-dir] [--template project|plugin|adapter] [--name <kebab-name>] [--ref <branch|tag>] [--source <local-path>] [--git|--no-git] [--install] [--yes] [--locale <locale>]",
+        "zh-Hant": "uvx create-promptex-py [目標目錄] [--template project|plugin|adapter] [--name <kebab 名>] [--ref <branch|tag>] [--source <本地路徑>] [--git|--no-git] [--install] [--yes] [--locale <語系>]",
+    },
+    "scaffold.usage.rs": {
+        "en": "cargo create-promptex-rs [target-dir] --template project|plugin|adapter --name <kebab-name> [--ref <branch|tag>] [--source <local-path>] [--git|--no-git] [--install] [--yes] [--locale <locale>]",
+        "zh-Hant": "cargo create-promptex-rs [目標目錄] --template project|plugin|adapter --name <kebab 名> [--ref <branch|tag>] [--source <本地路徑>] [--git|--no-git] [--install] [--yes] [--locale <語系>]",
+    },
+    "template.adapter_demo.rule_content": {
+        "en": "On the custom platform this rule degrades to always-on, with its scope noted in the body.",
+        "zh-Hant": "本規則在自訂平台會降級為常駐，並於內文標註適用範圍。",
+    },
+    "template.adapter_demo.skill_content": {
+        "en": "This skill is projected onto two placements at once: claude and the custom platform.",
+        "zh-Hant": "本技能會同時投影到 claude 與自訂平台兩個落點。",
+    },
+    "template.adapter_demo.skill_description": {
+        "en": "A demo skill the adapter example projects",
+        "zh-Hant": "adapter 範例用來輸出的示範技能",
+    },
+    "template.adapter_demo.skill_when_to_use": {
+        "en": "When checking what the custom adapter emits",
+        "zh-Hant": "驗證自訂 adapter 的產出時",
+    },
+    "template.demo.rule_name": {
+        "en": "Demo rule",
+        "zh-Hant": "示範規則",
+    },
+    "template.demo.skill_name": {
+        "en": "Demo skill",
+        "zh-Hant": "示範技能",
+    },
+    "template.example_rule.intro": {
+        "en": "This is the example resource produced by promptex init; change it or delete it as your project needs.",
+        "zh-Hant": "這是 promptex init 產出的範例資源，可依專案需求修改或刪除。",
+    },
+    "template.example_rule.name": {
+        "en": "Example rule",
+        "zh-Hant": "範例規則",
+    },
+    "template.example_rule.other_states": {
+        "en": "The other two states: declare the always-on flag instead and it loads unconditionally, regardless of what you are doing; declare neither and you get the default third state, where the resource is still installed on the target but never enters context on its own, appearing only when another resource references it explicitly. A skeleton that stopped at the third state would hand the author a rule that compiles and does nothing.",
+        "zh-Hant": "另兩態：改宣告常駐旗標即無條件載入，不看當下在做什麼；兩者都不宣告則是預設的第三態，資源照樣安裝到目標端，卻不會自動進入上下文，只在被其他資源顯式引用時登場。骨架若停在第三態，作者拿到的會是一份編得動、卻不會有任何作用的規則。",
+    },
+    "template.example_rule.scoped": {
+        "en": "This rule declares a scope (every file under the prompts source directory), which puts it in the scoped-loading state, one of the three loading states. The scope declaration appears in the artifact as that platform's own loading declaration, and the platform loads the rule into context only while working on a matching file.",
+        "zh-Hant": "本規則宣告了適用範圍（源碼目錄 prompts 下的全部檔案），因此屬載入宣告三態中的範圍載入態：範圍宣告在產物裡呈現為該平台的載入宣告，平台於符合的檔案上工作時才把規則載入上下文。",
+    },
+    "template.example_skill.description": {
+        "en": "Shows how an invoked resource is declared: a description of what it does and trigger text for when to use it",
+        "zh-Hant": "示範被喚起型資源的宣告：描述它做什麼、觸發語料說何時用",
+    },
+    "template.example_skill.intro": {
+        "en": "This is the example skill that ships with the project starter; change it or delete it as your project needs.",
+        "zh-Hant": "這是 project starter 附帶的範例技能，可依專案需求修改或刪除。",
+    },
+    "template.example_skill.invoked": {
+        "en": "A skill is an invoked resource: config.whenToUse is its trigger text (required), and the platform decides from it when to load the skill into context. Set against the rule next to it, which uses scoped loading, the two together show the most common pair of loading declarations.",
+        "zh-Hant": "技能屬被喚起型資源：config.whenToUse 是觸發語料（必填），平台依它判斷何時把本技能載入上下文。與相鄰的規則（範圍載入）對照，兩者合起來展示了載入宣告最常用的兩種形態。",
+    },
+    "template.example_skill.invoked_rs": {
+        "en": "A skill is an invoked resource: whenToUse on config is its trigger text (required, enforced by the typestate parameter), and the platform decides from it when to load the skill into context. Set against the rule next to it, which uses scoped loading, the two together show the most common pair of loading declarations.",
+        "zh-Hant": "技能屬被喚起型資源：config 的 whenToUse 是觸發語料（必填，型別狀態參數把關），平台依它判斷何時把本技能載入上下文。與相鄰的規則（範圍載入）對照，兩者合起來展示了載入宣告最常用的兩種形態。",
+    },
+    "template.example_skill.name": {
+        "en": "Example skill",
+        "zh-Hant": "範例技能",
+    },
+    "template.example_skill.when_to_use": {
+        "en": "When demonstrating how an invoked resource is declared",
+        "zh-Hant": "示範被喚起型資源的宣告形態時",
+    },
+    "template.plugin_demo.rule_content": {
+        "en": "The plugin appends a line to this rule's content during the transform stage.",
+        "zh-Hant": "本規則的內容會在 transform 階段被 plugin 追加一行。",
+    },
+    "template.plugin_demo.skill_content": {
+        "en": "The plugin appends a line to this skill's content during the transform stage.",
+        "zh-Hant": "本技能的內容會在 transform 階段被 plugin 追加一行。",
+    },
+    "template.plugin_demo.skill_description": {
+        "en": "A demo skill the plugin example builds against",
+        "zh-Hant": "plugin 範例用來建置的示範技能",
+    },
+    "template.plugin_demo.skill_when_to_use": {
+        "en": "When checking how the plugin rewrites a skill",
+        "zh-Hant": "驗證 plugin 對技能的改寫時",
+    },
+};
+const FALLBACK = 'en';
+const LOCALE_ENV_ORDER = ["PROMPTEX_LOCALE", "LANGUAGE", "LC_ALL", "LC_MESSAGES", "LANG"];
+/** POSIX 形態轉 BCP 47 並收斂為目錄認得的標籤；認不出來回 undefined。 */
+export function parseLocale(tag) {
+    const normalized = String(tag ?? '').trim().split(/[.@]/)[0].replaceAll('_', '-');
+    if (normalized === '')
+        return undefined;
+    const upper = normalized.toUpperCase();
+    if (upper === 'C' || upper === 'POSIX')
+        return 'en';
+    const [language, ...rest] = normalized.toLowerCase().split('-');
+    if (language === 'en')
+        return 'en';
+    if (language === 'zh' && rest.some((p) => ['hant', 'tw', 'hk', 'mo'].includes(p)))
+        return 'zh-Hant';
+    return undefined;
+}
+/** 依旗標與環境算出本次的語系。三項都認不出時回退路。 */
+export function resolveLocale(flag) {
+    const fromFlag = parseLocale(flag);
+    if (fromFlag !== undefined)
+        return fromFlag;
+    for (const key of LOCALE_ENV_ORDER) {
+        const raw = process.env[key];
+        if (raw === undefined || raw.trim() === '')
+            continue;
+        for (const part of raw.split(':')) {
+            const found = parseLocale(part);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return FALLBACK;
+}
+/** 依語系取一則訊息，並以 `%{name}` 形態代入具名參數。 */
+export function t(key, locale, params) {
+    const entry = MESSAGES[key];
+    if (entry === undefined)
+        return key;
+    const template = entry[locale] ?? entry[FALLBACK];
+    if (template === undefined)
+        return key;
+    if (params === undefined)
+        return template;
+    return template.replace(/%\{([^}]+)\}/g, (whole, name) => (name in params ? String(params[name]) : whole));
+}

package/package.json

@@ -1,35 +1,55 @@
 {
   "name": "create-promptex-js",
-  "version": "0.0.1-alpha.1",
-  "description": "promptex 專案鷹架的最小原型（alpha）：產出可立即建置的專案骨架",
+  "version": "1.0.0",
+  "description": "Scaffold a promptex TypeScript project, plugin or adapter.",
   "license": "MIT OR Apache-2.0",
-  "author": "promptex-ai",
-  "homepage": "https://github.com/promptex-ai/promptex#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/promptex-ai/promptex.git"
-  },
+  "homepage": "https://github.com/promptex-ai/promptex/tree/main/packages/create-promptex-js#readme",
   "bugs": {
     "url": "https://github.com/promptex-ai/promptex/issues"
   },
-  "keywords": ["prompt", "prompt-engineering", "ai", "llm", "agent", "claude", "skills", "scaffold"],
+  "keywords": [
+    "promptex",
+    "create",
+    "scaffold",
+    "template",
+    "prompt",
+    "prompt-engineering",
+    "ai",
+    "llm",
+    "agent",
+    "codegen"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/promptex-ai/promptex.git",
+    "directory": "packages/create-promptex-js"
+  },
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "bin": {
     "create-promptex-js": "./bin/create-promptex-js.mjs"
   },
+  "files": [
+    "bin",
+    "dist",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
   "engines": {
-    "node": ">=22.14.0"
+    "node": ">=18"
   },
-  "files": ["dist", "bin", "README.md", "LICENSE-MIT", "LICENSE-APACHE"],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build",
-    "test": "node --test 'test/*.test.mjs'"
+    "pretest": "npm run build",
+    "test": "node --experimental-strip-types --test test/smoke.test.ts && npm run test:types",
+    "test:types": "tsc -p tsconfig.typelevel.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "mri": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
-    "typescript": "^5.7.0"
+    "typescript": "^7.0.2"
   }
 }