create-promptex-js 1.0.0 → 1.0.1

package/README.md

@@ -2,8 +2,7 @@
 
 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.
+starter templates bundled with this package.
 
 ```console
 npm create promptex-js
@@ -19,8 +18,7 @@ npm create promptex-js my-prompts -- --template project --name my-prompts --no-g
 | :--- | :--- |
 | `--template <t>` | `project`（消費專案）、`plugin`、`adapter` |
 | `--name <n>` | kebab-case 名稱；預設取目標目錄名正規化 |
-| `--ref <r>` | 抓 promptex-templates 的指定 branch／tag；預設 `v<本套件版本>` |
-| `--source <p>` | 改用本地 promptex-templates checkout（離線與開發用） |
+| `--source <p>` | 改讀本地模板目錄（含各 `*-starter` 的那一層），開發模板時用 |
 | `--git` / `--no-git` | 是否 `git init`；互動預設是 |
 | `--install` | 鷹架後直接 `npm install`；預設只印下一步 |
 | `--yes` | 跳過互動，全部取預設或旗標值 |
@@ -32,9 +30,9 @@ npm create promptex-js my-prompts -- --template project --name my-prompts --no-g
 用哪個語系寫（[ADR-030](https://github.com/promptex-ai/ssot)）：那份內容從產出
 當下起就歸你，框架不再改寫它。plugin 與 adapter 骨架裡教你怎麼填的註解維持英文。
 
-目標目錄非空時列出既有項目、零寫入退出。模板不內嵌：單一來源住
-promptex-templates 倉庫，鷹架時以 git 取得對應版本 tag（需要 git；
-`{{promptexVersion}}` 於鷹架當下以本套件版本填入，三套件與 SDK 同版發布）。
+目標目錄非空時列出既有項目、零寫入退出。模板隨本套件一起發布，
+鷹架時不需要網路，每個版本具現化的都是它發布時的模板。`{{promptexVersion}}`
+於鷹架當下以本套件版本填入，三套件與 SDK 同版發布。
 
 `promptex init` 與本工具的分工：init 在既有專案就地補上 promptex（非互動、
 極簡骨架）；本工具從零開一個 repo（互動、三種模板、git init）。

package/dist/index.js

@@ -1,27 +1,26 @@
 #!/usr/bin/env node
-// 鷹架 CLI：從 promptex-templates 倉庫開出 TypeScript 的 project／plugin／
-// adapter 專案。六階段：環境檢查 → 互動收集 → 模板取得 → 具現化 → 後處理 →
-// 稽核輸出；非互動時（--yes 或無 TTY）全部取預設或旗標值。
+// 鷹架 CLI：開出 TypeScript 的 project／plugin／adapter 專案。六階段：環境檢查 →
+// 互動收集 → 模板取得 → 具現化 → 後處理 → 稽核輸出；非互動時（--yes 或無 TTY）
+// 全部取預設或旗標值。
 //
-// 模板不內嵌：單一來源住 promptex-templates，GA 版預設抓與本套件版本對應的
-// tag（v<版本>），預發布版預設抓 main，--ref 覆寫、--source 改用本地 checkout
-// （離線與開發用）。
+// Templates ship inside this package (templates/), so every version scaffolds the
+// templates it was released with, offline. --source points at a local templates
+// directory (the one holding the *-starter folders) for template development.
 //
 // 用法：
 //   npm create promptex-js [目標目錄] [-- --template project|plugin|adapter \
-//     --name <kebab 名> --ref <branch|tag> --source <本地路徑> \
+//     --name <kebab 名> --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 { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 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 BUNDLED_TEMPLATES = join(here, '..', 'templates');
 const TEMPLATES = ['project', 'plugin', 'adapter'];
 // 與 promptex init 的單元名正規化同一套規則（crates/promptex-core/src/init.rs）。
 const RESERVED_UNIT_NAMES = ['cache', 'preview', 'content', 'content-index', 'graph', 'main'];
@@ -40,13 +39,21 @@ function bail(message) {
     console.error(message);
     process.exit(1);
 }
-const TEMPLATES_REPO = 'https://github.com/promptex-ai/promptex-templates.git';
+const BOOLEAN_FLAGS = ['install', 'yes', 'git', 'help'];
+const STRING_FLAGS = ['template', 'name', 'source', 'locale'];
 const args = mri(process.argv.slice(2), {
-    boolean: ['install', 'yes', 'git', 'help'],
-    string: ['template', 'name', 'ref', 'source', 'locale'],
+    boolean: BOOLEAN_FLAGS,
+    string: STRING_FLAGS,
     alias: { h: 'help' },
 });
 const locale = resolveLocale(args.locale);
+// mri accepts any flag, so reject the ones this tool does not declare (a removed
+// --ref must fail loudly instead of being ignored). `--no-git` arrives as `git`.
+const knownFlags = new Set(['_', 'h', ...BOOLEAN_FLAGS, ...STRING_FLAGS]);
+for (const key of Object.keys(args)) {
+    if (!knownFlags.has(key))
+        bail(t('scaffold.error.unknown_argument', locale, { arg: `--${key}` }));
+}
 const separator = t('common.list_separator', locale);
 if (args.help) {
     console.log(t('scaffold.usage.js', locale));
@@ -116,32 +123,12 @@ if (existsSync(targetDir)) {
     }
 }
 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 {
-        execFileSync('git', ['clone', '--depth', '1', '--branch', ref, TEMPLATES_REPO, cloneDir], {
-            stdio: ['ignore', 'ignore', 'inherit'],
-        });
-    }
-    catch {
-        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`);
+// ── 模板取得：預設用內附模板；--source 讀本地模板目錄。 ──
+const templatesRoot = args.source ? resolve(args.source) : BUNDLED_TEMPLATES;
+const sourceLabel = args.source
+    ? t('scaffold.source.local', locale, { path: templatesRoot })
+    : t('scaffold.source.bundled', locale, { version: ownVersion });
+const starterDir = join(templatesRoot, `${template}-starter`);
 if (!existsSync(starterDir))
     bail(t('scaffold.error.starter_missing', locale, { template, path: starterDir }));
 // ── 具現化：複製、佔位替換、_gitignore 改名。 ──
@@ -209,8 +196,6 @@ for (const rel of walk(starterDir)) {
     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' });

package/dist/messages.generated.js

@@ -19,14 +19,6 @@ 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}",
@@ -47,10 +39,6 @@ export const MESSAGES = {
         "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 失敗，鷹架檔案已寫入、依賴未裝。",
@@ -95,13 +83,9 @@ 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",
@@ -139,6 +123,10 @@ export const MESSAGES = {
         "en": "Template (%{choices})",
         "zh-Hant": "模板（%{choices}）",
     },
+    "scaffold.source.bundled": {
+        "en": "bundled templates (v%{version})",
+        "zh-Hant": "內附模板（v%{version}）",
+    },
     "scaffold.source.local": {
         "en": "local template (%{path})",
         "zh-Hant": "本地模板（%{path}）",
@@ -156,16 +144,16 @@ 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] [--yes] [--locale <locale>]",
+        "zh-Hant": "create-promptex-js [目標目錄] --template project|plugin|adapter --name <kebab 名> [--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 <語系>]",
+        "en": "uvx create-promptex-py [target-dir] [--template project|plugin|adapter] [--name <kebab-name>] [--source <templates-dir>] [--git|--no-git] [--install] [--yes] [--locale <locale>]",
+        "zh-Hant": "uvx create-promptex-py [目標目錄] [--template project|plugin|adapter] [--name <kebab 名>] [--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 <語系>]",
+        "en": "cargo create-promptex-rs [target-dir] --template project|plugin|adapter --name <kebab-name> [--source <templates-dir>] [--git|--no-git] [--install] [--yes] [--locale <locale>]",
+        "zh-Hant": "cargo create-promptex-rs [目標目錄] --template project|plugin|adapter --name <kebab 名> [--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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-promptex-js",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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"
   ],

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}}',
+})

package/templates/plugin-starter/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "promptex-plugin-{{name}}",
+  "version": "0.1.0",
+  "description": "A promptex plugin.",
+  "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/plugin-starter/promptex.config.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "promptex-plugin-{{name}} options",
+  "type": "object",
+  "properties": {
+    "banner": {
+      "type": "string",
+      "description": "Appended to every skill and rule at the transform stage. Defaults to a built-in notice."
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,63 @@
+// 最小可發布 plugin：三個生命週期各示範一件事，發布前把內容換成你的邏輯。
+// 生命週期固定順序：prepare（唯一 async 的階段，收集遍之前）→ 源碼求值 →
+// transform（改寫遍）→ validate（解析遍，核心檢查在先）。
+import { readFileSync } from 'node:fs'
+
+import type { Diagnostic, Plugin } 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 {
+  /** transform 階段追加到每個 skill 與 rule 的內容；省略時用預設文字。 */
+  readonly banner?: string
+}
+
+const DEFAULT_BANNER = '（本節點由 {{name}} plugin 追加此行）'
+
+export function createPlugin(options: Options = {}): Plugin {
+  // prepare 取得的資料存進閉包，transform 只讀閉包、不知道資料從何而來。
+  let banner = ''
+
+  return {
+    name: '{{name}}',
+    // 宣告本擴充作用在哪幾種節點類型（供文件與讀取端），不隱含過濾。
+    kinds: ['skill', 'rule'],
+    // 相容的框架版本範圍：安裝的 promptex-js 落在範圍外時於編譯開始前報錯。
+    version: '^{{promptexVersion}}',
+    // 參數宣告隨中介表示交給讀取端；
+    // `promptex config declare` 讀的是套件根的同一份檔案。
+    configSchema,
+
+    // 準備：唯一 async 的生命週期。真實 plugin 在這裡請求外部資源，或以
+    // ctx.cacheDir 快取、ctx.writeLock 記錄鎖定；本範例只把參數收斂成
+    // transform 要用的值。
+    async prepare() {
+      banner = options.banner ?? DEFAULT_BANNER
+    },
+
+    // 改寫：改寫既有節點一律經 ctx 操作函式（appendContent／patchConfig），
+    // 型別安全、變更可追蹤、衝突可偵測；也可在此以 define* 新增節點。
+    transform(ctx) {
+      for (const entry of ctx.entries) {
+        if (entry.kind === 'skill' || entry.kind === 'rule') ctx.appendContent(entry, banner)
+      }
+    },
+
+    // 驗證：對註冊表做結構驗證，回傳診斷（空陣列即通過）。
+    validate(ctx): Diagnostic[] {
+      return ctx.entries
+        .filter((e) => e.id.startsWith('promptex-'))
+        .map((e) => ({
+          code: '{{name}}-reserved-id',
+          message: `節點 ${e.id} 以保留前綴 promptex- 命名，請改用其他 id`,
+          at: [e.at],
+          severity: 'error',
+        }))
+    },
+  }
+}

package/templates/plugin-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/project-starter/README.md

@@ -0,0 +1,30 @@
+# {{name}}
+
+A [promptex](https://github.com/promptex-ai/promptex) prompt-source tree:
+resources are declared in TypeScript under `prompts/` and projected onto your
+AI coding tool by the `promptex` CLI.
+
+## Getting started
+
+```console
+npm install
+npm run install:prompts
+```
+
+`npm run install:prompts` compiles the declarations and writes the platform
+artifacts (e.g. `.claude/`) into this directory. `npm run build` only refreshes
+the framework metadata under `.promptex/` without touching platform artifacts;
+`npx promptex build --install --dry-run .` previews the diff without writing anything.
+
+## Layout
+
+| Path | Role |
+| :--- | :--- |
+| `promptex.config.ts` | Unit configuration: source dir, output dir, targets |
+| `prompts/example.ts` | Example rule (scope-loaded via `appliesTo`) |
+| `prompts/example-skill.ts` | Example skill (invoked via `whenToUse`) |
+
+Add more resources as ordinary `.ts` files under `prompts/`; every file in the
+source dir is evaluated. See the
+[promptex-js README](https://github.com/promptex-ai/promptex/tree/main/packages/promptex-js)
+for the full API.

package/templates/project-starter/_gitignore

@@ -0,0 +1,11 @@
+# === promptex init 產生的忽略規則（重跑以本行判定，勿改寫）===
+# 框架的建置快取。整個 .promptex/ 不忽略：查詢進入點的覆寫檔 .promptex/query
+# 是作者手寫的內容，要入版控；匯出的 .promptex/preview/ 入不入版控由你決定。
+.promptex/cache/
+# 框架每次建置重寫的中繼（結構與內容本體），可重建、不入版控。逐檔明列而非
+# 用 .promptex/*/ 這類萬用：同一層還住著所有權登記 {平台}.json，那是要入版控的。
+.promptex/*/graph.json
+.promptex/*/content.json
+.promptex/*/content-index.json
+# npm 安裝依賴的落點。
+node_modules/

package/templates/project-starter/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "promptex build",
+    "install:prompts": "promptex build --install"
+  },
+  "dependencies": {
+    "promptex-js": "^{{promptexVersion}}"
+  }
+}

package/templates/project-starter/promptex.config.ts

@@ -0,0 +1,8 @@
+import { claude, defineConfig } from 'promptex-js'
+
+export default defineConfig({
+  name: '{{unitName}}',
+  srcDir: './prompts',
+  outDir: '.',
+  targets: [claude()],
+})

package/templates/project-starter/prompts/example-skill.ts

@@ -0,0 +1,14 @@
+import { defineSkill } from 'promptex-js'
+
+export const exampleSkill = defineSkill({
+  id: 'example-skill',
+  name: '{{exampleSkillName}}',
+  description: '{{exampleSkillDescription}}',
+  config: {
+    whenToUse: '{{exampleSkillWhenToUse}}',
+  },
+  content: [
+    '{{exampleSkillIntro}}',
+    '{{exampleSkillInvoked}}',
+  ],
+})

package/templates/project-starter/prompts/example.ts

@@ -0,0 +1,14 @@
+import { defineRule } from 'promptex-js'
+
+export const exampleRule = defineRule({
+  id: 'example-rule',
+  name: '{{exampleRuleName}}',
+  config: {
+    appliesTo: ['prompts/**'],
+  },
+  content: [
+    '{{exampleRuleIntro}}',
+    '{{exampleRuleScoped}}',
+    '{{exampleRuleOtherStates}}',
+  ],
+})

package/dist/default-ref.d.ts

@@ -1,6 +0,0 @@
-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

@@ -1,14 +0,0 @@
-// 預設 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' };
-}