create-promptex-js 1.0.1 → 1.1.0

package/dist/plan.js

@@ -0,0 +1,327 @@
+// create 的模式判斷、寫入規則與套用（m007 d004）。三個 create 套件各有一份同構的實作：
+// create-promptex-py 的 `_plan.py` 與 create-promptex-rs 的 `plan.rs`。函式名、規則表與
+// 輸出欄位三份對齊，允許清單與錯誤代碼則由 `contract.generated.ts` 從同一份來源生成。
+//
+// 流程分四段：inspectTarget（目標狀態與模式）→ planFiles（逐檔決定動作，不寫入）→
+// applyPlan（照計畫寫入，失敗時只回復這次新建的東西）→ 由 CLI 輸出報告或 JSON。
+// --dry-run 只走前兩段。
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { CONFIG_FILES, GITIGNORE_MARKER, isAllowlisted } from './contract.generated.js';
+/** 依代碼帶結構化細節的失敗；CLI 依 `contract.generated.ts` 的錯誤表決定訊息與結束碼。 */
+export class CreateError extends Error {
+    code;
+    details;
+    constructor(code, details = {}) {
+        super(code);
+        this.code = code;
+        this.details = details;
+    }
+}
+function lstatOrNull(path) {
+    return lstatSync(path, { throwIfNoEntry: false }) ?? null;
+}
+/**
+ * 判斷目標狀態與模式。目標不存在，或第一層只有允許清單裡的項目，就走建立模式。
+ * 目標是符號連結或檔案時以用法錯誤拒絕，不寫入任何東西。
+ */
+export function inspectTarget(target) {
+    const stat = lstatOrNull(target);
+    if (stat === null)
+        return { exists: false, mode: 'create', unlisted: [] };
+    if (stat.isSymbolicLink())
+        throw new CreateError('USAGE_TARGET_IS_SYMLINK', { path: target });
+    if (!stat.isDirectory())
+        throw new CreateError('USAGE_TARGET_IS_FILE', { path: target });
+    const unlisted = readdirSync(target)
+        .filter((name) => !isAllowlisted(name))
+        .sort();
+    return { exists: true, mode: unlisted.length === 0 ? 'create' : 'init', unlisted };
+}
+/** 目標裡已存在的 promptex 設定檔；有就代表已初始化。 */
+export function findConfig(target) {
+    return CONFIG_FILES.find((name) => lstatOrNull(join(target, name)) !== null) ?? null;
+}
+/**
+ * 目標是否位於任何 git 工作樹內（含上層資料夾）。往上找 `.git`（資料夾或 worktree 的
+ * 檔案），不呼叫 git：沒裝 git 也判得出來，三種語言的結果也因此一致。
+ */
+export function isInsideGitWorktree(target) {
+    let dir = resolve(target);
+    while (lstatOrNull(dir) === null && dirname(dir) !== dir)
+        dir = dirname(dir);
+    for (;;) {
+        if (lstatOrNull(join(dir, '.git')) !== null)
+            return true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+export function commandAvailable(name) {
+    return spawnSync(name, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
+}
+/** 非互動環境：沒有終端機、帶 --yes，或 CI 環境變數為真（空字串、0、false 不算）。 */
+export function isNonInteractive(stdinIsTty, yes, env) {
+    const ci = (env.CI ?? '').trim().toLowerCase();
+    return !stdinIsTty || yes || (ci !== '' && ci !== '0' && ci !== 'false');
+}
+/** 非互動時沒給又沒有預設值的輸入，一次全列出（結束碼 2）。互動時會問，因此不算缺。 */
+export function missingInputs(inputs, interactive) {
+    if (interactive)
+        return [];
+    return inputs.filter((input) => !input.provided && !input.hasDefault).map((input) => input.flag);
+}
+/** 宣告檔與範例目錄依範本而定，其他角色看檔名。 */
+const MANIFEST = 'package.json';
+const EXAMPLE_DIR = { project: 'prompts', plugin: 'example', adapter: 'example' };
+/**
+ * 每個角色遇到同名既有檔時怎麼做（m007 d004 寫入規則表）。`.gitignore` 走追加，不在表內。
+ * `forceOverwrites` 為假的角色連 --force 都不覆寫；`createModeOnly` 的角色在初始化模式一律不寫。
+ */
+const RULES = {
+    manifest: { existsReason: 'manifest-kept', forceOverwrites: false, createModeOnly: false },
+    readme: { existsReason: 'exists', forceOverwrites: true, createModeOnly: true },
+    example: { existsReason: 'exists', forceOverwrites: true, createModeOnly: false },
+    other: { existsReason: 'exists', forceOverwrites: true, createModeOnly: false },
+};
+export function roleOf(rel, template) {
+    if (rel === MANIFEST)
+        return 'manifest';
+    if (rel === 'README.md')
+        return 'readme';
+    if (rel === '.gitignore')
+        return 'gitignore';
+    if (rel.startsWith(`${EXAMPLE_DIR[template]}/`))
+        return 'example';
+    return 'other';
+}
+/** 上層路徑擋住寫入的原因：符號連結或不是資料夾。全部是資料夾或不存在時回 null。 */
+function blockedParent(target, rel) {
+    const parts = rel.split('/').slice(0, -1);
+    let current = target;
+    for (const part of parts) {
+        current = join(current, part);
+        const stat = lstatOrNull(current);
+        if (stat === null)
+            return null;
+        if (stat.isSymbolicLink())
+            return 'symlink';
+        if (!stat.isDirectory())
+            return 'blocked';
+    }
+    return null;
+}
+/**
+ * `.gitignore`：不存在就建立；存在就在尾端追加帶標記的區塊，已有標記行就跳過。
+ * 追加的區塊前補換行與一個空行，作者的最後一條規則才不會和標記行黏成同一行
+ * （與核心 init 的 `apply_gitignore` 相同）。範本沒有標記行時（plugin、adapter）
+ * 追加前補上，重跑才判得出已追加過。
+ */
+function planGitignore(target, content) {
+    const path = join(target, '.gitignore');
+    const stat = lstatOrNull(path);
+    if (stat === null)
+        return { action: 'create', path: '.gitignore', content };
+    if (stat.isSymbolicLink())
+        return { action: 'skip', path: '.gitignore', reason: 'symlink' };
+    let existing;
+    try {
+        existing = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        throw new CreateError('RUN_READ_FAILED', { path, detail: e instanceof Error ? e.message : String(e) });
+    }
+    if (existing.split(/\r?\n/).includes(GITIGNORE_MARKER)) {
+        return { action: 'skip', path: '.gitignore', reason: 'marker-present' };
+    }
+    const block = content.startsWith(GITIGNORE_MARKER) ? content : `${GITIGNORE_MARKER}\n${content}`;
+    let prefix = '';
+    if (existing !== '' && !existing.endsWith('\n'))
+        prefix += '\n';
+    if (existing !== '')
+        prefix += '\n';
+    return { action: 'append', path: '.gitignore', content: prefix + block };
+}
+/** 逐檔決定動作，不寫入。回傳的順序是範本檔的路徑順序。 */
+export function planFiles(target, files, mode, template, force) {
+    const exampleDir = EXAMPLE_DIR[template];
+    const exampleSkipped = !force && lstatOrNull(join(target, exampleDir)) !== null;
+    const actions = [];
+    let exampleListed = false;
+    for (const file of [...files].sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))) {
+        const role = roleOf(file.rel, template);
+        if (role === 'example' && exampleSkipped) {
+            if (!exampleListed)
+                actions.push({ action: 'skip', path: `${exampleDir}/`, reason: 'example-dir-exists' });
+            exampleListed = true;
+            continue;
+        }
+        const blocked = blockedParent(target, file.rel);
+        if (blocked !== null) {
+            actions.push({ action: 'skip', path: file.rel, reason: blocked });
+            continue;
+        }
+        if (role === 'gitignore') {
+            actions.push(planGitignore(target, file.content));
+            continue;
+        }
+        const rule = RULES[role];
+        if (rule.createModeOnly && mode === 'init') {
+            actions.push({ action: 'skip', path: file.rel, reason: 'init-mode' });
+            continue;
+        }
+        const stat = lstatOrNull(join(target, file.rel));
+        if (stat === null) {
+            actions.push({ action: 'create', path: file.rel, content: file.content });
+        }
+        else if (stat.isDirectory() || !force || !rule.forceOverwrites) {
+            actions.push({ action: 'skip', path: file.rel, reason: rule.existsReason });
+        }
+        else {
+            actions.push({ action: 'overwrite', path: file.rel, content: file.content });
+        }
+    }
+    return actions;
+}
+/** 計畫的四類清單，路徑排序後輸出（JSON 與人讀報告共用）。 */
+export function summarize(actions) {
+    const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const pick = (kind) => actions.filter((a) => a.action === kind).sort(byPath);
+    return {
+        create: pick('create').map((a) => a.path),
+        overwrite: pick('overwrite').map((a) => a.path),
+        append: pick('append').map((a) => a.path),
+        skip: pick('skip').map((a) => ({ path: a.path, reason: a.reason })),
+    };
+}
+/**
+ * 照計畫寫入。先建立與覆寫，最後追加 `.gitignore`，追加之前的失敗因此不會動到既有的
+ * `.gitignore`。任何一步失敗時，倒序刪掉這次新建的檔案與資料夾（資料夾只在已清空時刪），
+ * 既有檔一律不刪，再以 RUN_WRITE_FAILED 回報。
+ *
+ * 環境變數 PROMPTEX_CREATE_FAIL_ON 指定一個相對路徑時，寫到那個檔就模擬失敗。只給測試
+ * 驗證回復用：真實的寫入失敗（磁碟滿、權限）難以在三種語言穩定重現。
+ */
+export function applyPlan(target, actions) {
+    const created = [];
+    const failOn = process.env.PROMPTEX_CREATE_FAIL_ON;
+    const ensureDir = (dir) => {
+        const missing = [];
+        let probe = dir;
+        while (lstatOrNull(probe) === null && dirname(probe) !== probe) {
+            missing.unshift(probe);
+            probe = dirname(probe);
+        }
+        for (const path of missing) {
+            mkdirSync(path);
+            created.push({ path, dir: true });
+        }
+    };
+    let current = target;
+    try {
+        ensureDir(target);
+        const ordered = [
+            ...actions.filter((a) => a.action === 'create' || a.action === 'overwrite'),
+            ...actions.filter((a) => a.action === 'append'),
+        ];
+        for (const entry of ordered) {
+            current = join(target, entry.path);
+            if (failOn === entry.path)
+                throw new Error(`simulated failure (PROMPTEX_CREATE_FAIL_ON=${failOn})`);
+            ensureDir(dirname(current));
+            if (entry.action === 'append') {
+                appendFileSync(current, entry.content);
+            }
+            else if (entry.action === 'overwrite') {
+                // 先刪再寫：既有的若是符號連結，覆寫的是連結本身，不跟過去寫外部檔。
+                unlinkSync(current);
+                writeFileSync(current, entry.content, { flag: 'wx' });
+            }
+            else {
+                writeFileSync(current, entry.content, { flag: 'wx' });
+                created.push({ path: current, dir: false });
+            }
+        }
+    }
+    catch (e) {
+        for (const item of [...created].reverse()) {
+            try {
+                if (item.dir)
+                    rmdirSync(item.path);
+                else
+                    unlinkSync(item.path);
+            }
+            catch {
+                // 資料夾裡有別人放的東西，或已經不在：留著，不刪既有內容。
+            }
+        }
+        throw new CreateError('RUN_WRITE_FAILED', { path: current, detail: e instanceof Error ? e.message : String(e) });
+    }
+}
+const LOCKFILES = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'],
+];
+export function detectPackageManager(target, pnpmAvailable) {
+    let dir = resolve(target);
+    for (;;) {
+        for (const [file, manager] of LOCKFILES) {
+            if (lstatOrNull(join(dir, file)) !== null)
+                return manager;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return pnpmAvailable() ? 'pnpm' : 'npm';
+}
+/** 各套件管理器的四種指令形態。 */
+export const PM_COMMANDS = {
+    pnpm: { install: 'pnpm install', add: 'pnpm add', run: 'pnpm run', exec: 'pnpm exec' },
+    npm: { install: 'npm install', add: 'npm install', run: 'npm run', exec: 'npx' },
+    yarn: { install: 'yarn install', add: 'yarn add', run: 'yarn run', exec: 'yarn' },
+    bun: { install: 'bun install', add: 'bun add', run: 'bun run', exec: 'bunx' },
+};
+/**
+ * 給人看的目標路徑：在工作目錄底下就用相對路徑，目標就是工作目錄時回空字串（不印 `cd .`），
+ * 其他情況用絕對路徑。
+ */
+export function cdPath(target, cwd) {
+    const rel = relative(cwd, target);
+    if (rel === '')
+        return '';
+    if (rel.startsWith('..') || isAbsolute(rel))
+        return target;
+    return rel.split('\\').join('/');
+}
+export function nextSteps(opts) {
+    const pm = PM_COMMANDS[opts.pm];
+    const steps = [];
+    if (opts.template === 'project') {
+        if (opts.cd !== '')
+            steps.push(`cd ${opts.cd}`);
+        if (opts.manifestKept) {
+            // 既有的 package.json 沒有 promptex-js 依賴，也沒有範本的 install:prompts script。
+            steps.push(`${pm.add} promptex-js`, `${pm.exec} promptex build --install`);
+        }
+        else {
+            if (!opts.installed)
+                steps.push(pm.install);
+            steps.push(`${pm.run} install:prompts`);
+        }
+        return steps;
+    }
+    if (opts.cd !== '')
+        steps.push(`cd ${opts.cd}`);
+    if (!opts.installed)
+        steps.push(pm.install);
+    steps.push(`${pm.run} build`, `cd example && ${pm.exec} promptex build --install`);
+    return steps;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-promptex-js",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Scaffold a promptex TypeScript project, plugin or adapter.",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://github.com/promptex-ai/promptex/tree/main/packages/create-promptex-js#readme",
@@ -41,7 +41,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "pretest": "npm run build",
-    "test": "node --experimental-strip-types --test test/smoke.test.ts && npm run test:types",
+    "test": "node --experimental-strip-types --test test/smoke.test.ts test/modes.test.ts && npm run test:types",
     "test:types": "tsc -p tsconfig.typelevel.json",
     "prepack": "npm run build"
   },