create-promptex-js 1.0.1 → 1.1.1-rc.1

package/README.md

@@ -1,38 +1,124 @@
 # create-promptex-js
 
-Scaffold a [promptex](https://github.com/promptex-ai/promptex) TypeScript
-project, plugin or adapter from the
-starter templates bundled with this package.
+Start a [promptex](https://github.com/promptex-ai/promptex) TypeScript project,
+plugin or adapter from the starter templates bundled with this package, or add
+promptex to a project you already have.
 
 ```console
-npm create promptex-js
+pnpm create promptex-js my-prompts   # new project in ./my-prompts
+pnpm create promptex-js .            # add promptex to the current directory
 ```
 
-Interactive by default; every answer has a flag for non-interactive use:
+`npx create-promptex-js <dir>` does the same. With `npm create promptex-js`, put the
+flags after `--`, for example `npm create promptex-js . -- --dry-run`.
+
+After that, declare and install the SDK, then build:
+
+```console
+pnpm add promptex-js
+pnpm exec promptex build --install
+```
+
+## 建立模式與初始化模式
+
+create 依目標目錄自動選模式，輸出的第一行說明選了哪一種：
+
+- 目標不存在，或第一層只有下表的項目時，走建立模式，開一個新專案。
+- 其他情況走初始化模式，在原資料夾加入 promptex。初始化模式只支援 `project` 範本，
+  `plugin` 與 `adapter` 遇到這種資料夾會以結束碼 2 拒絕。
+
+| 分組 | 不影響模式判斷的項目 |
+| :--- | :--- |
+| macOS（不分大小寫） | `.DS_Store`、`._*`、`.localized`、`.Spotlight-V100`、`.Trashes`、`.fseventsd`、`.TemporaryItems` |
+| Windows（不分大小寫） | `Thumbs.db`、`desktop.ini`、`ehthumbs.db`、`$RECYCLE.BIN`、`System Volume Information` |
+| Linux | `.directory`、`.Trash-*`、`.fuse_hidden*`、`.nfs*`、`lost+found` |
+| 版本控制與倉庫 | `.git`、`.gitignore`、`.gitattributes`、`.gitkeep`、`.hg`、`.hgignore`、`.svn`、`LICENSE`、`README.md`、`.github` |
+| 編輯器與 AI 工具 | `.vscode`、`.idea`、`*.iml`、`.zed`、`.cursor`、`.claude` |
+
+兩種模式寫入時都逐檔判斷，既有檔一律不覆寫：
+
+| 情況 | 處理 |
+| :--- | :--- |
+| 已有 `promptex.config.ts`、`.py` 或 `.rs` | 判定已初始化，什麼都不寫，結束碼 0 |
+| 已有 `package.json` | 內容不動，`promptex-js` 依賴由你用 `pnpm add promptex-js` 加 |
+| 其他同名的範本檔 | 跳過並列出。`prompts/` 已存在時整個跳過 |
+| `.gitignore` | 不存在就建立。存在就在尾端追加 promptex 區塊，已有區塊的標記行就跳過 |
+| `README.md` | 只在建立模式寫出，已存在仍跳過 |
+| git | 目標在任何 git 工作樹內（含上層資料夾）就不 `git init`。兩種模式都不自動 commit |
+| 寫到一半失敗 | 只移除這次新建的檔案與資料夾，既有檔不動 |
+
+目標本身是符號連結或檔案時，以結束碼 2 拒絕。目標裡的符號連結不跟隨，連到外部的
+檔案不會被寫到。
+
+## 旗標
+
+每個問題都有對應的旗標，可以不互動執行：
 
 ```console
-npm create promptex-js my-prompts -- --template project --name my-prompts --no-git --yes
+pnpm create promptex-js my-prompts --template project --name my-prompts --no-git --yes
 ```
 
 | Flag | Meaning |
 | :--- | :--- |
-| `--template <t>` | `project`（消費專案）、`plugin`、`adapter` |
+| `--template <t>` | `project`（消費專案）、`plugin`、`adapter`。初始化模式只收 `project` |
 | `--name <n>` | kebab-case 名稱；預設取目標目錄名正規化 |
 | `--source <p>` | 改讀本地模板目錄（含各 `*-starter` 的那一層），開發模板時用 |
-| `--git` / `--no-git` | 是否 `git init`；互動預設是 |
-| `--install` | 鷹架後直接 `npm install`；預設只印下一步 |
-| `--yes` | 跳過互動，全部取預設或旗標值 |
+| `--git` / `--no-git` | 是否 `git init`；預設是。在既有 git 工作樹內一律略過。給 `--git` 但沒裝 git 時報錯，沒給時靜默略過 |
+| `--install` | 鷹架後直接安裝依賴，用下一段偵測到的套件管理器；預設只印下一步 |
+| `--force` | 覆寫與範本同名的既有檔。不清空資料夾，也不動 `package.json`、`.gitignore` 與設定檔 |
+| `--dry-run` | 列出會建立、覆寫、追加、跳過的檔，不寫入 |
+| `--json` | 搭配 `--dry-run`，在 stdout 輸出一份 JSON |
+| `--yes` | 跳過互動，全部取預設值；不代表同意覆寫 |
 | `--locale <l>` | 訊息與範例資源的語系：`en`（預設）或 `zh-Hant` |
 
+沒有終端機、帶 `--yes`，或環境變數 `CI` 為真時不提問，全部取預設值。
+
+下一步依偵測到的套件管理器提示：目標或上層有鎖定檔就用它的工具
+（`pnpm-lock.yaml`、`yarn.lock`、`bun.lock`、`package-lock.json`），否則裝了 pnpm 就用
+pnpm，再退回 npm。已有 `package.json` 時下一步改成先加依賴，因為既有的
+`package.json` 沒有範本的 `install:prompts` script。
+
+## 機器可讀的試跑結果
+
+`--dry-run --json` 在 stdout 輸出一行 JSON，欄位與另兩個 create 套件
+（create-promptex-py、create-promptex-rs）相同，只有 `package` 與 `language` 不同：
+
+```json
+{"formatVersion":"1.1","package":{"name":"create-promptex-js","version":"1.0.1"},"language":"ts",
+ "mode":"init","alreadyInitialized":false,"existingConfig":null,"target":"/work/app",
+ "template":"project","name":"app",
+ "files":{"create":["promptex.config.ts","prompts/example-skill.ts","prompts/example.ts"],
+          "overwrite":[],"append":[".gitignore"],
+          "skip":[{"path":"README.md","reason":"init-mode"},{"path":"package.json","reason":"manifest-kept"}]},
+ "git":{"init":false,"reason":"inside-worktree"}}
+```
+
+| 欄位 | 內容 |
+| :--- | :--- |
+| `mode` | `create` 或 `init` |
+| `alreadyInitialized`、`existingConfig` | 已有 promptex 設定檔時為 `true` 與那個檔名，`files` 四個清單都是空的 |
+| `files.create`、`files.overwrite`、`files.append` | 會建立、覆寫（只在 `--force` 時出現）、追加的相對路徑 |
+| `files.skip` | 跳過的路徑與原因：`exists`、`manifest-kept`、`example-dir-exists`、`init-mode`、`marker-present`、`symlink`、`blocked` |
+| `git` | `init` 是否會執行 `git init`；不執行時 `reason` 是 `inside-worktree`、`disabled`、`unavailable` 或 `already-initialized` |
+
+失敗時 stdout 是一份錯誤 JSON，stderr 另寫一行同文的訊息：
+
+```json
+{"formatVersion":"1.1","error":{"code":"USAGE_TEMPLATE_NEEDS_EMPTY_DIR","message":"…","details":{"template":"plugin","path":"/work/app","entries":["src"]}}}
+```
+
+結束碼是 0 成功（含已初始化）、1 執行失敗、2 用法錯誤。程式只比對 `error.code`：
+`USAGE_` 開頭是呼叫本身不對，`RUN_` 開頭是執行失敗。
+
+## 語系與模板
+
 語系未以 `--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 骨架裡教你怎麼填的註解維持英文。
 
-目標目錄非空時列出既有項目、零寫入退出。模板隨本套件一起發布，
-鷹架時不需要網路，每個版本具現化的都是它發布時的模板。`{{promptexVersion}}`
-於鷹架當下以本套件版本填入，三套件與 SDK 同版發布。
+模板隨本套件一起發布，鷹架時不需要網路，每個版本具現化的都是它發布時的模板。
+`{{promptexVersion}}` 於鷹架當下以本套件版本填入，三套件與 SDK 同版發布。
 
-`promptex init` 與本工具的分工：init 在既有專案就地補上 promptex（非互動、
-極簡骨架）；本工具從零開一個 repo（互動、三種模板、git init）。
+`promptex init` 已棄用，2.0 移除。它能做的事改由本工具的初始化模式處理。

package/dist/contract.generated.d.ts

@@ -0,0 +1,24 @@
+/** 機器可讀輸出的格式版本（ADR-041）。 */
+export declare const FORMAT_VERSION = "1.1";
+/** `.gitignore` 區塊的標記行。已有這一行就不再追加。 */
+export declare const GITIGNORE_MARKER = "# === promptex init \u7522\u751F\u7684\u5FFD\u7565\u898F\u5247\uFF08\u91CD\u8DD1\u4EE5\u672C\u884C\u5224\u5B9A\uFF0C\u52FF\u6539\u5BEB\uFF09===";
+/** 任一存在就判定目標已初始化。 */
+export declare const CONFIG_FILES: readonly string[];
+/** 只決定模式的允許清單：第一層只有這些項目時走建立模式。 */
+export declare const ALLOWLIST: readonly {
+    group: string;
+    caseInsensitive: boolean;
+    entries: readonly string[];
+}[];
+/** 錯誤代碼。`exitCode` 由前綴決定：`USAGE_` 為 2，`RUN_` 為 1。 */
+export interface ErrorCode {
+    code: string;
+    exitCode: number;
+    messageKey: string;
+    details: readonly string[];
+}
+export declare const ERRORS: readonly ErrorCode[];
+/** 依代碼查錯誤記錄。代碼不在表內是呼叫端的程式錯誤。 */
+export declare function errorCode(code: string): ErrorCode;
+/** 第一層項目名稱是否在允許清單內。 */
+export declare function isAllowlisted(name: string): boolean;

package/dist/contract.generated.js

@@ -0,0 +1,59 @@
+// 本檔由 packages/promptex-js/scripts/gen-messages.mjs 自動產生，請勿手改。
+//
+// 來源是 crates/promptex-core/cli/create.json（允許清單、配置檔名、標記行與錯誤代碼），
+// 格式版本取自 crates/promptex-core/src/graph.rs 的 FORMAT_VERSION。要改內容就改來源，
+// 再跑 `pnpm --filter promptex-js run gen:messages` 重新生成；直接改本檔會被核對閘擋下。
+/** 機器可讀輸出的格式版本（ADR-041）。 */
+export const FORMAT_VERSION = "1.1";
+/** `.gitignore` 區塊的標記行。已有這一行就不再追加。 */
+export const GITIGNORE_MARKER = "# === promptex init 產生的忽略規則（重跑以本行判定，勿改寫）===";
+/** 任一存在就判定目標已初始化。 */
+export const CONFIG_FILES = ["promptex.config.ts", "promptex.config.py", "promptex.config.rs"];
+/** 只決定模式的允許清單：第一層只有這些項目時走建立模式。 */
+export const ALLOWLIST = [
+    { group: "macos", caseInsensitive: true, entries: [".DS_Store", "._*", ".localized", ".Spotlight-V100", ".Trashes", ".fseventsd", ".TemporaryItems"] },
+    { group: "windows", caseInsensitive: true, entries: ["Thumbs.db", "desktop.ini", "ehthumbs.db", "$RECYCLE.BIN", "System Volume Information"] },
+    { group: "linux", caseInsensitive: false, entries: [".directory", ".Trash-*", ".fuse_hidden*", ".nfs*", "lost+found"] },
+    { group: "vcs", caseInsensitive: false, entries: [".git", ".gitignore", ".gitattributes", ".gitkeep", ".hg", ".hgignore", ".svn", "LICENSE", "README.md", ".github"] },
+    { group: "editor", caseInsensitive: false, entries: [".vscode", ".idea", "*.iml", ".zed", ".cursor", ".claude"] },
+];
+export const ERRORS = [
+    { code: "USAGE_UNKNOWN_ARGUMENT", exitCode: 2, messageKey: "scaffold.error.unknown_argument", details: ["arg"] },
+    { code: "USAGE_FLAG_MISSING_VALUE", exitCode: 2, messageKey: "scaffold.error.flag_missing_value", details: ["flag"] },
+    { code: "USAGE_TEMPLATE_UNSUPPORTED", exitCode: 2, messageKey: "scaffold.error.template_unsupported", details: ["template", "choices"] },
+    { code: "USAGE_JSON_REQUIRES_DRY_RUN", exitCode: 2, messageKey: "scaffold.error.json_requires_dry_run", details: [] },
+    { code: "USAGE_TARGET_IS_FILE", exitCode: 2, messageKey: "scaffold.error.target_is_file", details: ["path"] },
+    { code: "USAGE_TARGET_IS_SYMLINK", exitCode: 2, messageKey: "scaffold.error.target_is_symlink", details: ["path"] },
+    { code: "USAGE_TEMPLATE_NEEDS_EMPTY_DIR", exitCode: 2, messageKey: "scaffold.error.template_needs_empty_dir", details: ["template", "path", "entries"] },
+    { code: "USAGE_MISSING_INPUTS", exitCode: 2, messageKey: "scaffold.error.missing_inputs", details: ["flags"] },
+    { code: "RUN_GIT_UNAVAILABLE", exitCode: 1, messageKey: "scaffold.error.git_unavailable", details: [] },
+    { code: "RUN_STARTER_MISSING", exitCode: 1, messageKey: "scaffold.error.starter_missing", details: ["template", "path"] },
+    { code: "RUN_READ_FAILED", exitCode: 1, messageKey: "scaffold.error.read_failed", details: ["path", "detail"] },
+    { code: "RUN_WRITE_FAILED", exitCode: 1, messageKey: "scaffold.error.write_failed", details: ["path", "detail"] },
+    { code: "RUN_INSTALL_TOOL_MISSING", exitCode: 1, messageKey: "scaffold.error.install_tool_missing", details: ["command"] },
+    { code: "RUN_INSTALL_FAILED", exitCode: 1, messageKey: "scaffold.error.install_failed", details: ["command"] },
+    { code: "RUN_CANCELLED", exitCode: 1, messageKey: "scaffold.cancelled", details: [] },
+];
+/** 依代碼查錯誤記錄。代碼不在表內是呼叫端的程式錯誤。 */
+export function errorCode(code) {
+    const found = ERRORS.find((e) => e.code === code);
+    if (found === undefined)
+        throw new Error(`create.json 沒有錯誤代碼 ${code}`);
+    return found;
+}
+/** 單一樣式比對：`*` 只會出現在頭或尾。 */
+function matchesPattern(name, pattern) {
+    if (pattern.startsWith('*'))
+        return name.endsWith(pattern.slice(1));
+    if (pattern.endsWith('*'))
+        return name.startsWith(pattern.slice(0, -1));
+    return name === pattern;
+}
+/** 只轉 ASCII 字母：三種語言的小寫轉換對非 ASCII 字元結果不同，而清單本身全是 ASCII。 */
+function asciiLower(text) {
+    return text.replace(/[A-Z]/g, (c) => c.toLowerCase());
+}
+/** 第一層項目名稱是否在允許清單內。 */
+export function isAllowlisted(name) {
+    return ALLOWLIST.some((group) => group.entries.some((pattern) => group.caseInsensitive ? matchesPattern(asciiLower(name), asciiLower(pattern)) : matchesPattern(name, pattern)));
+}