create-promptex-js 1.0.0 → 1.1.0

package/dist/messages.generated.js

@@ -7,6 +7,26 @@ export const MESSAGES = {
         "en": ", ",
         "zh-Hant": "、",
     },
+    "scaffold.action.append": {
+        "en": "append",
+        "zh-Hant": "追加",
+    },
+    "scaffold.action.create": {
+        "en": "create",
+        "zh-Hant": "建立",
+    },
+    "scaffold.action.overwrite": {
+        "en": "overwrite",
+        "zh-Hant": "覆寫",
+    },
+    "scaffold.action.skip": {
+        "en": "skip",
+        "zh-Hant": "跳過",
+    },
+    "scaffold.already_initialized": {
+        "en": "Already initialized: %{config} exists, so no file was written.",
+        "zh-Hant": "已初始化：%{config} 已存在，因此未寫入任何檔案。",
+    },
     "scaffold.cancelled": {
         "en": "Cancelled, no file was written.",
         "zh-Hant": "已取消，未寫入任何檔案。",
@@ -19,57 +39,53 @@ export const MESSAGES = {
         "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.dry_run.header": {
+        "en": "Dry run, nothing was written. Planned changes in %{path} (template source: %{source}):",
+        "zh-Hant": "試跑，未寫入任何檔案。預計對 %{path} 做的變更（模板來源：%{source}）：",
     },
     "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.git_unavailable": {
+        "en": "--git was given but no git executable was found. No file was written.",
+        "zh-Hant": "給了 --git，但找不到 git 執行檔。未寫入任何檔案。",
+    },
+    "scaffold.error.install_failed": {
+        "en": "%{command} failed; the scaffold files were written, the dependencies were not installed.",
+        "zh-Hant": "%{command} 失敗，鷹架檔案已寫入、依賴未裝。",
     },
-    "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_tool_missing": {
+        "en": "--install needs %{command}, but it was not found; the scaffold files were written, the dependencies were not installed.",
+        "zh-Hant": "--install 需要 %{command}，但找不到；鷹架檔案已寫入、依賴未裝。",
     },
-    "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.json_requires_dry_run": {
+        "en": "--json only works together with --dry-run",
+        "zh-Hant": "--json 要搭配 --dry-run 使用",
     },
-    "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.missing_inputs": {
+        "en": "Running without a terminal and these inputs have no default, pass them as flags: %{flags}",
+        "zh-Hant": "非互動執行時以下輸入沒有預設值，請用旗標給：%{flags}",
+    },
+    "scaffold.error.read_failed": {
+        "en": "Reading %{path} failed: %{detail}",
+        "zh-Hant": "讀取 %{path} 失敗：%{detail}",
     },
     "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.target_is_file": {
+        "en": "The target is a file, not a directory: %{path}. No file was written.",
+        "zh-Hant": "目標是檔案，不是資料夾：%{path}。未寫入任何檔案。",
+    },
+    "scaffold.error.target_is_symlink": {
+        "en": "The target is a symbolic link: %{path}. Pass the real directory instead. No file was written.",
+        "zh-Hant": "目標是符號連結：%{path}。請改傳實際的資料夾。未寫入任何檔案。",
+    },
+    "scaffold.error.template_needs_empty_dir": {
+        "en": "The %{template} template only goes into a new or empty directory, but %{path} already holds %{entries}. No file was written.",
+        "zh-Hant": "%{template} 模板只能建在新的或空的資料夾，但 %{path} 已有 %{entries}。未寫入任何檔案。",
     },
     "scaffold.error.template_unsupported": {
         "en": "Unsupported template: %{template} (available: %{choices})",
@@ -79,13 +95,37 @@ export const MESSAGES = {
         "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.error.write_failed": {
+        "en": "Writing %{path} failed: %{detail}. The files and directories this run created were removed, existing files were left as they were.",
+        "zh-Hant": "寫入 %{path} 失敗：%{detail}。已移除這次新建的檔案與資料夾，既有檔維持原狀。",
+    },
+    "scaffold.git.inside_worktree": {
+        "en": "git: the target is inside an existing git work tree, so git init is skipped.",
+        "zh-Hant": "git：目標位於既有的 git 工作樹內，因此略過 git init。",
+    },
+    "scaffold.git.will_init": {
+        "en": "git: git init runs in the target.",
+        "zh-Hant": "git：會在目標執行 git init。",
+    },
+    "scaffold.help.dry_run": {
+        "en": "list the files that would be created, skipped or appended, write nothing",
+        "zh-Hant": "列出會建立、跳過、追加的檔，不寫入",
+    },
+    "scaffold.help.force": {
+        "en": "overwrite existing files that clash with the template; never empties the directory or touches the declaration file",
+        "zh-Hant": "覆寫與模板同名的既有檔；不清空資料夾，也不動宣告檔",
+    },
+    "scaffold.help.git": {
+        "en": "run git init or not (default yes, skipped inside an existing git work tree; --git fails when git is missing)",
+        "zh-Hant": "要不要執行 git init（預設要，位於既有 git 工作樹內時略過；給 --git 但沒裝 git 時報錯）",
     },
     "scaffold.help.install": {
-        "en": "run uv sync right after scaffolding",
-        "zh-Hant": "鷹架後直接 uv sync",
+        "en": "install the dependencies right after scaffolding",
+        "zh-Hant": "鷹架後直接安裝依賴",
+    },
+    "scaffold.help.json": {
+        "en": "with --dry-run, print the plan as JSON on stdout",
+        "zh-Hant": "搭配 --dry-run，在 stdout 輸出 JSON 格式的計畫",
     },
     "scaffold.help.locale": {
         "en": "message locale (en|zh-Hant), defaults to the environment variables then English",
@@ -95,25 +135,29 @@ export const MESSAGES = {
         "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（離線與開發用）",
+        "en": "use a local templates directory (the one holding the *-starter folders) instead of the bundled templates, for template development",
+        "zh-Hant": "改用本地模板目錄（含各 *-starter 的那一層）取代內附模板，開發模板時用",
     },
     "scaffold.help.target_dir": {
-        "en": "target directory",
-        "zh-Hant": "目標目錄",
+        "en": "target directory: missing or empty for create mode, an existing project for init mode",
+        "zh-Hant": "目標目錄。不存在或空的走建立模式，既有專案走初始化模式",
     },
     "scaffold.help.template": {
-        "en": "project|plugin|adapter",
-        "zh-Hant": "project|plugin|adapter",
+        "en": "project|plugin|adapter, init mode only takes project",
+        "zh-Hant": "project|plugin|adapter，初始化模式只支援 project",
     },
     "scaffold.help.yes": {
-        "en": "skip the interactive prompts, take defaults or flag values throughout",
-        "zh-Hant": "跳過互動，全部取預設或旗標值",
+        "en": "skip the interactive prompts and take the defaults; does not mean overwrite",
+        "zh-Hant": "跳過互動，全部取預設值；不代表同意覆寫",
+    },
+    "scaffold.mode.create": {
+        "en": "Create mode: new project in %{path}",
+        "zh-Hant": "建立模式：在 %{path} 建立新專案",
+    },
+    "scaffold.mode.init": {
+        "en": "Init mode: adding promptex to the existing directory %{path} (it already holds %{entries})",
+        "zh-Hant": "初始化模式：在既有資料夾 %{path} 加入 promptex（裡面已有 %{entries}）",
     },
     "scaffold.prompt.git_init": {
         "en": "Initialize a git repository?",
@@ -139,6 +183,38 @@ export const MESSAGES = {
         "en": "Template (%{choices})",
         "zh-Hant": "模板（%{choices}）",
     },
+    "scaffold.skip.blocked": {
+        "en": "a parent path is not a directory",
+        "zh-Hant": "上層路徑不是資料夾",
+    },
+    "scaffold.skip.example_dir_exists": {
+        "en": "example directory already exists, skipped as a whole",
+        "zh-Hant": "範例目錄已存在，整個跳過",
+    },
+    "scaffold.skip.exists": {
+        "en": "already exists, pass --force to overwrite",
+        "zh-Hant": "已存在，加 --force 才覆寫",
+    },
+    "scaffold.skip.init_mode": {
+        "en": "only written in create mode",
+        "zh-Hant": "只在建立模式寫出",
+    },
+    "scaffold.skip.manifest_kept": {
+        "en": "declaration file left as is, add the promptex dependency yourself",
+        "zh-Hant": "宣告檔不動，promptex 依賴要自己加",
+    },
+    "scaffold.skip.marker_present": {
+        "en": "the promptex block is already there",
+        "zh-Hant": "已有 promptex 區塊",
+    },
+    "scaffold.skip.symlink": {
+        "en": "symbolic link, not followed",
+        "zh-Hant": "符號連結，不跟隨",
+    },
+    "scaffold.source.bundled": {
+        "en": "bundled templates (v%{version})",
+        "zh-Hant": "內附模板（v%{version}）",
+    },
     "scaffold.source.local": {
         "en": "local template (%{path})",
         "zh-Hant": "本地模板（%{path}）",
@@ -156,16 +232,24 @@ export const MESSAGES = {
         "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 <語系>]",
+        "en": "create-promptex-js [target-dir] [--template project|plugin|adapter] [--name <kebab-name>] [--source <templates-dir>] [--git|--no-git] [--install] [--force] [--dry-run [--json]] [--yes] [--locale <locale>]",
+        "zh-Hant": "create-promptex-js [目標目錄] [--template project|plugin|adapter] [--name <kebab 名>] [--source <模板目錄>] [--git|--no-git] [--install] [--force] [--dry-run [--json]] [--yes] [--locale <語系>]",
+    },
+    "scaffold.usage.modes": {
+        "en": "A missing target directory, or one that only holds system, version-control and editor files, gets a new project (create mode). Any other directory gets promptex added in place (init mode). Existing files are never overwritten unless --force is given, and an existing promptex.config.* means the directory is already initialized.",
+        "zh-Hant": "目標目錄不存在，或裡面只有系統、版本控制與編輯器的檔案時，建立新專案（建立模式）。其他資料夾在原地加入 promptex（初始化模式）。除非給 --force，既有檔一律不覆寫。已有 promptex.config.* 就判定為已初始化。",
+    },
+    "scaffold.usage.options": {
+        "en": "Options:",
+        "zh-Hant": "選項：",
     },
     "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 <語系>]",
+        "en": "uvx create-promptex-py [target-dir] [--template project|plugin|adapter] [--name <kebab-name>] [--source <templates-dir>] [--git|--no-git] [--install] [--force] [--dry-run [--json]] [--yes] [--locale <locale>]",
+        "zh-Hant": "uvx create-promptex-py [目標目錄] [--template project|plugin|adapter] [--name <kebab 名>] [--source <模板目錄>] [--git|--no-git] [--install] [--force] [--dry-run [--json]] [--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 <語系>]",
+        "en": "cargo create-promptex-rs [target-dir] [--template project|plugin|adapter] [--name <kebab-name>] [--source <templates-dir>] [--git|--no-git] [--install] [--force] [--dry-run [--json]] [--yes] [--locale <locale>]",
+        "zh-Hant": "cargo create-promptex-rs [目標目錄] [--template project|plugin|adapter] [--name <kebab 名>] [--source <模板目錄>] [--git|--no-git] [--install] [--force] [--dry-run [--json]] [--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.",

package/dist/plan.d.ts

@@ -0,0 +1,105 @@
+export type Mode = 'create' | 'init';
+export type SkipReason = 'exists' | 'manifest-kept' | 'example-dir-exists' | 'init-mode' | 'marker-present' | 'symlink' | 'blocked';
+/** 依代碼帶結構化細節的失敗；CLI 依 `contract.generated.ts` 的錯誤表決定訊息與結束碼。 */
+export declare class CreateError extends Error {
+    readonly code: string;
+    readonly details: Record<string, string | string[]>;
+    constructor(code: string, details?: Record<string, string | string[]>);
+}
+/** 目標的狀態。`unlisted` 是第一層不在允許清單內的項目，決定模式也供輸出列出。 */
+export interface TargetState {
+    exists: boolean;
+    mode: Mode;
+    unlisted: string[];
+}
+/**
+ * 判斷目標狀態與模式。目標不存在，或第一層只有允許清單裡的項目，就走建立模式。
+ * 目標是符號連結或檔案時以用法錯誤拒絕，不寫入任何東西。
+ */
+export declare function inspectTarget(target: string): TargetState;
+/** 目標裡已存在的 promptex 設定檔；有就代表已初始化。 */
+export declare function findConfig(target: string): string | null;
+/**
+ * 目標是否位於任何 git 工作樹內（含上層資料夾）。往上找 `.git`（資料夾或 worktree 的
+ * 檔案），不呼叫 git：沒裝 git 也判得出來，三種語言的結果也因此一致。
+ */
+export declare function isInsideGitWorktree(target: string): boolean;
+export declare function commandAvailable(name: string): boolean;
+/** 非互動環境：沒有終端機、帶 --yes，或 CI 環境變數為真（空字串、0、false 不算）。 */
+export declare function isNonInteractive(stdinIsTty: boolean, yes: boolean, env: NodeJS.ProcessEnv): boolean;
+/** 一項使用者輸入：旗標名、這次有沒有給、沒給時有沒有預設值。 */
+export interface InputSpec {
+    flag: string;
+    provided: boolean;
+    hasDefault: boolean;
+}
+/** 非互動時沒給又沒有預設值的輸入，一次全列出（結束碼 2）。互動時會問，因此不算缺。 */
+export declare function missingInputs(inputs: InputSpec[], interactive: boolean): string[];
+/** 範本檔在寫入規則裡的角色。 */
+export type Role = 'manifest' | 'readme' | 'gitignore' | 'example' | 'other';
+export declare function roleOf(rel: string, template: string): Role;
+/** 一個範本檔：目標裡的相對路徑（`/` 分隔）與替換後的內容。 */
+export interface TemplateFile {
+    rel: string;
+    content: string;
+}
+export type Action = {
+    action: 'create';
+    path: string;
+    content: string;
+} | {
+    action: 'overwrite';
+    path: string;
+    content: string;
+} | {
+    action: 'append';
+    path: string;
+    content: string;
+} | {
+    action: 'skip';
+    path: string;
+    reason: SkipReason;
+};
+/** 逐檔決定動作，不寫入。回傳的順序是範本檔的路徑順序。 */
+export declare function planFiles(target: string, files: TemplateFile[], mode: Mode, template: string, force: boolean): Action[];
+/** 計畫的四類清單，路徑排序後輸出（JSON 與人讀報告共用）。 */
+export declare function summarize(actions: Action[]): {
+    create: string[];
+    overwrite: string[];
+    append: string[];
+    skip: {
+        path: string;
+        reason: SkipReason;
+    }[];
+};
+/**
+ * 照計畫寫入。先建立與覆寫，最後追加 `.gitignore`，追加之前的失敗因此不會動到既有的
+ * `.gitignore`。任何一步失敗時，倒序刪掉這次新建的檔案與資料夾（資料夾只在已清空時刪），
+ * 既有檔一律不刪，再以 RUN_WRITE_FAILED 回報。
+ *
+ * 環境變數 PROMPTEX_CREATE_FAIL_ON 指定一個相對路徑時，寫到那個檔就模擬失敗。只給測試
+ * 驗證回復用：真實的寫入失敗（磁碟滿、權限）難以在三種語言穩定重現。
+ */
+export declare function applyPlan(target: string, actions: Action[]): void;
+/** JS 的套件管理器：先看鎖定檔（目標或上層），再看有沒有 pnpm，最後退回 npm。 */
+export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+export declare function detectPackageManager(target: string, pnpmAvailable: () => boolean): PackageManager;
+/** 各套件管理器的四種指令形態。 */
+export declare const PM_COMMANDS: Record<PackageManager, {
+    install: string;
+    add: string;
+    run: string;
+    exec: string;
+}>;
+/**
+ * 給人看的目標路徑：在工作目錄底下就用相對路徑，目標就是工作目錄時回空字串（不印 `cd .`），
+ * 其他情況用絕對路徑。
+ */
+export declare function cdPath(target: string, cwd: string): string;
+export declare function nextSteps(opts: {
+    template: string;
+    cd: string;
+    manifestKept: boolean;
+    installed: boolean;
+    pm: PackageManager;
+}): string[];