create-promptex-js 1.0.0 → 1.1.0

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' };
-}