create-promptex-js 1.0.0 → 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.0",
+  "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",
@@ -31,6 +31,7 @@
   "files": [
     "bin",
     "dist",
+    "templates",
     "LICENSE-MIT",
     "LICENSE-APACHE"
   ],
@@ -40,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"
   },

package/templates/adapter-starter/README.md

@@ -0,0 +1,45 @@
+# promptex-adapter-{{name}}
+
+A publishable third-party [promptex](https://github.com/promptex-ai/promptex)
+platform adapter, written in TypeScript.
+
+**Adapters are language-bound**: this package serves TypeScript prompt projects
+only. To support the same platform from Python or Rust projects, implement the
+same `emit` chain against that language's SDK.
+
+The factory returns the same shape as the built-in `claude()` / `codex()`
+targets, so consumers list it right alongside them. Its `emit` function walks a
+fixed responsibility chain:
+
+1. Compute the layout table first — rendering needs it to resolve references.
+2. Report every unsupported kind via `ctx.unsupported` — never drop silently.
+3. Render supported entries via `ctx.render(entry, selfPath, layout)`; where
+   the platform lacks a feature (e.g. scoped loading), record it with
+   `ctx.degrade` and degrade in the output. Read platform-native keys via
+   `ctx.overrides`, never from the entry config directly.
+4. Emit referenced resources.
+
+## Try it
+
+```console
+npm install
+cd example
+npx promptex build --install .
+```
+
+The example project lists `targets: [claude(), target()]`; after install you
+get both `.claude/` and `.{{name}}/` artifacts, and the install report shows
+the `scopedLoading` degradation for the example rule. `npx promptex build --install --dry-run .`
+previews without writing.
+
+## Publishing
+
+- `npm run build` compiles `src/` to `dist/`; the package ships `dist/` plus
+  `promptex.config.schema.json`.
+- Keep `promptex.config.schema.json` at the package root: `promptex config
+  declare promptex-adapter-{{name}}` reads it from there, and `src/index.ts`
+  reads that same root copy at load time (a runtime read, not a compile-time
+  JSON import, so the emitted tree keeps a single copy and `dist/` stays flat)
+  and passes it to `defineTarget`, so it also travels with the intermediate
+  representation.
+- Keep the `promptex-adapter-` name prefix so consumers can find the package.

package/templates/adapter-starter/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+# example 具現化驗證時由 promptex 產生（.{{name}}/ 為自訂平台的產物落點）。
+example/.promptex/
+example/.claude/
+example/.{{name}}/

package/templates/adapter-starter/example/promptex.config.ts

@@ -0,0 +1,12 @@
+// 最小消費專案：自訂 target 與內建 claude() 並列，裝完依賴即可在本目錄執行
+// npx promptex build --install . 驗證兩個平台的產物。真實消費端改為從發布後的套件名
+// import。
+import { claude, defineConfig } from 'promptex-js'
+import target from '../src/index.ts'
+
+export default defineConfig({
+  name: 'adapter-example',
+  srcDir: './prompts',
+  outDir: '.',
+  targets: [claude(), target()],
+})

package/templates/adapter-starter/example/prompts/nodes.ts

@@ -0,0 +1,18 @@
+import { defineRule, defineSkill } from 'promptex-js'
+
+export const exampleSkill = defineSkill({
+  id: 'adapter-demo-skill',
+  name: '{{demoSkillName}}',
+  description: '{{adapterDemoSkillDescription}}',
+  config: { whenToUse: '{{adapterDemoSkillWhenToUse}}' },
+  content: '{{adapterDemoSkillContent}}',
+})
+
+// A rule carrying appliesTo: the custom platform has no scoped-loading mechanism,
+// so the install report shows a scopedLoading degrade entry.
+export const exampleRule = defineRule({
+  id: 'adapter-demo-rule',
+  name: '{{demoRuleName}}',
+  config: { appliesTo: ['prompts/**'] },
+  content: '{{adapterDemoRuleContent}}',
+})

package/templates/adapter-starter/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "promptex-adapter-{{name}}",
+  "version": "0.1.0",
+  "description": "A third-party promptex platform adapter.",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "promptex.config.schema.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "promptex-js": "^{{promptexVersion}}"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "promptex-js": "^{{promptexVersion}}",
+    "typescript": "^7.0.2"
+  }
+}

package/templates/adapter-starter/promptex.config.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "promptex-adapter-{{name}} options",
+  "type": "object",
+  "properties": {
+    "root": {
+      "type": "string",
+      "description": "Root directory for emitted artifacts, relative to the install root. Defaults to \".{{name}}\"."
+    }
+  },
+  "additionalProperties": false
+}

package/templates/adapter-starter/src/index.ts

@@ -0,0 +1,93 @@
+// 第三方 adapter：以 SDK 層實作，只用 AdapterContext 的公開介面。emit 的
+// 責任鏈固定四步：① 算落點表 → ② 回報不支援的 kind → ③ 渲染並產出節點
+// （平台缺某機制時記 degrade 降級）→ ④ 產出被引用的資源。發布前把落點
+// 規則與能力集合換成你的平台實況。
+//
+// adapter 綁語言：本套件服務 TypeScript 專案；Python／Rust 專案要用同一個
+// 平台時，各自以該語言的 SDK 實作一份。
+import { readFileSync } from 'node:fs'
+
+import { defineTarget, type AdapterContext, type AdapterTarget, type PluginEntry } from 'promptex-js'
+
+// 參數宣告（標準 JSON Schema）住套件根，由本檔在載入時讀進來。用執行期讀檔而非
+// 編譯期 import：JSON 在 include 的 src 之外，靜態 import 會把編譯器的共同來源根
+// 抬到套件根，產物因此多一層 src/，包裡還會留下第二份 schema。改讀檔之後
+// src/index.ts 與 dist/index.js 對套件根的相對位置相同，兩種形態都指向同一份。
+const configSchema = JSON.parse(readFileSync(new URL('../promptex.config.schema.json', import.meta.url), 'utf8'))
+
+/** 建構參數：與 promptex.config.schema.json 的宣告一一對應。 */
+export interface Options {
+  /** 產物落點的根目錄；預設 `.{{name}}`。 */
+  readonly root?: string
+}
+
+/** 平台能力：本範例只有提示詞單檔與參考資料，無代理、無事件機制。 */
+const SUPPORTED = ['skill', 'rule', 'instruction'] as const
+const UNSUPPORTED = ['agent', 'hook', 'mcp', 'permission'] as const
+
+export default function target(options: Options = {}): AdapterTarget {
+  const root = options.root ?? '.{{name}}'
+  // 落點規則：提示詞一律單檔平鋪，資源集中於 refs/。
+  const nodePath = (e: PluginEntry) => `${root}/prompts/${e.id}.md`
+  const resourcePath = (e: PluginEntry) => `${root}/refs/${e.id}.md`
+
+  const emit = (ctx: AdapterContext): Map<string, string> => {
+    const files = new Map<string, string>()
+
+    // ① 先算落點表：渲染需要它解析引用，故必須在渲染之前完成。
+    const layout = new Map<string, string>()
+    for (const kind of SUPPORTED) {
+      for (const e of ctx.entries(kind)) layout.set(`${kind}:${e.id}`, nodePath(e))
+    }
+    for (const kind of ['resource', 'asset', 'dir'] as const) {
+      for (const e of ctx.entries(kind)) layout.set(`${kind}:${e.id}`, resourcePath(e))
+    }
+
+    // ② 不支援的 kind 逐一列報告，不靜默丟棄。
+    for (const kind of UNSUPPORTED) {
+      for (const e of ctx.entries(kind)) {
+        ctx.unsupported({ kind, nodeId: e.id, feature: kind, note: `{{name}} 無 ${kind} 對應機制，該節點未產出` })
+      }
+    }
+
+    // ③ 產出提示詞單檔；rule 的載入範圍在本平台無對應機制，降級為內文標註。
+    for (const kind of SUPPORTED) {
+      for (const e of ctx.entries(kind)) {
+        const path = nodePath(e)
+        const cfg = e.def.config as { appliesTo?: readonly string[] } | undefined
+        let note = ''
+        if (kind === 'rule' && cfg?.appliesTo?.length) {
+          note = `適用範圍：${cfg.appliesTo.join('、')}\n\n`
+          ctx.degrade({
+            kind,
+            nodeId: e.id,
+            feature: 'scopedLoading',
+            note: '{{name}} 無範圍載入機制，改為常駐並於內文標註適用範圍',
+          })
+        }
+        files.set(path, `${frontmatter(ctx, e)}# ${e.name}\n\n${note}${ctx.render(e, path, layout)}\n`)
+      }
+    }
+
+    // ④ 被引用的資源。
+    for (const e of ctx.entries('resource')) {
+      const path = resourcePath(e)
+      files.set(path, `# ${e.name}\n\n${ctx.render(e, path, layout)}\n`)
+    }
+
+    return files
+  }
+
+  // 參數宣告隨中介表示交給讀取端；
+  // `promptex config declare` 讀的是套件根的同一份檔案。
+  return defineTarget('{{name}}', emit, { configSchema })
+}
+
+// 平台原生鍵的覆寫：一律經 ctx.overrides 讀取，不自己走
+// entry.def.config.platforms：「空物件視同未宣告」的判定與框架保留鍵
+// （promptex: 前綴）的過濾都由核心同一份實作承載，自己讀會各自重造而漂移。
+const frontmatter = (ctx: AdapterContext, e: PluginEntry): string => {
+  const overrides = ctx.overrides(e)
+  if (!overrides) return ''
+  return `---\n${Object.entries(overrides).map(([k, v]) => `${k}: ${String(v)}`).join('\n')}\n---\n\n`
+}

package/templates/adapter-starter/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/templates/plugin-starter/README.md

@@ -0,0 +1,40 @@
+# promptex-plugin-{{name}}
+
+A publishable [promptex](https://github.com/promptex-ai/promptex) plugin,
+written in TypeScript for TypeScript prompt projects.
+
+A plugin hooks into the evaluation pipeline in a fixed order:
+
+1. `prepare` — the only async stage, runs before source collection. Fetch
+   external data here (cache it under `ctx.cacheDir`, record pins with
+   `ctx.writeLock`) and pass it to later stages through the plugin's closure.
+2. `transform` — rewrite existing entries through the context operations
+   (`appendContent` / `patchConfig`) or add new nodes with `define*`.
+3. `validate` — structural checks over the registry; return diagnostics
+   (an empty array passes). Core checks run first.
+
+Plugins produce **nodes**, not files: anything you want on disk becomes a
+resource node that the core lays out.
+
+## Try it
+
+```console
+npm install
+cd example
+npx promptex build --install .
+```
+
+The example project wires the plugin in via `plugins: [createPlugin(...)]` and
+shows the banner appended to both entries. `npx promptex build --install --dry-run .` previews
+without writing.
+
+## Publishing
+
+- `npm run build` compiles `src/` to `dist/`; the package ships `dist/` plus
+  `promptex.config.schema.json`.
+- Keep `promptex.config.schema.json` at the package root: `promptex config
+  declare promptex-plugin-{{name}}` reads it from there, and `src/index.ts`
+  reads that same root copy at load time (a runtime read, not a compile-time
+  JSON import, so the emitted tree keeps a single copy and `dist/` stays flat),
+  so the schema also travels with the intermediate representation.
+- Keep the `promptex-plugin-` name prefix so consumers can find the package.

package/templates/plugin-starter/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+# example 具現化驗證時由 promptex 產生。
+example/.promptex/
+example/.claude/

package/templates/plugin-starter/example/promptex.config.ts

@@ -0,0 +1,12 @@
+// 最小消費專案：直接以相對路徑掛上本套件的 plugin，裝完依賴即可在本目錄
+// 執行 npx promptex build --install . 驗證產物。真實消費端改為從發布後的套件名 import。
+import { claude, defineConfig } from 'promptex-js'
+import { createPlugin } from '../src/index.ts'
+
+export default defineConfig({
+  name: 'plugin-example',
+  srcDir: './prompts',
+  outDir: '.',
+  targets: [claude()],
+  plugins: [createPlugin({ banner: '（由 {{name}} plugin 追加）' })],
+})

package/templates/plugin-starter/example/prompts/nodes.ts

@@ -0,0 +1,16 @@
+import { defineRule, defineSkill } from 'promptex-js'
+
+export const exampleSkill = defineSkill({
+  id: 'plugin-demo-skill',
+  name: '{{demoSkillName}}',
+  description: '{{pluginDemoSkillDescription}}',
+  config: { whenToUse: '{{pluginDemoSkillWhenToUse}}' },
+  content: '{{pluginDemoSkillContent}}',
+})
+
+export const exampleRule = defineRule({
+  id: 'plugin-demo-rule',
+  name: '{{demoRuleName}}',
+  config: { appliesTo: ['prompts/**'] },
+  content: '{{pluginDemoRuleContent}}',
+})