promptex-js 1.1.1 → 1.2.0

package/README.md

@@ -89,14 +89,14 @@ Common flags: `--out <install root>` (single-directory mode), `--platform <name>
 ## Machine-readable output
 
 `--json` makes a command print one JSON document on stdout. Every document, and every
-file the tool writes under `.promptex/`, carries `formatVersion` (currently `"1.1"`).
+file the tool writes under `.promptex/`, carries `formatVersion` (currently `"1.2"`).
 Within 1.x the version only gains keys, so read the keys you know and ignore the rest.
 
 `promptex version --json` reports the package, the language and what this CLI
 supports, so a caller can check a feature before using it:
 
 ```json
-{"formatVersion":"1.1","package":{"name":"promptex-js","version":"1.0.1"},"language":"ts",
+{"formatVersion":"1.2","package":{"name":"promptex-js","version":"1.0.1"},"language":"ts",
  "capabilities":{"verbs":{"build":{"flags":["--install","--dry-run","…"]},"version":{"flags":[]}},
                  "globalFlags":["--json","--locale"]}}
 ```
@@ -105,7 +105,7 @@ A failing command with `--json` prints an error document on stdout and the same
 message on one line of stderr:
 
 ```json
-{"formatVersion":"1.1","error":{"code":"USAGE_UNKNOWN_FLAG","message":"Unknown flag: --foo","details":{"flag":"--foo","usage":"…"}}}
+{"formatVersion":"1.2","error":{"code":"USAGE_UNKNOWN_FLAG","message":"Unknown flag: --foo","details":{"flag":"--foo","usage":"…"}}}
 ```
 
 - `code` is stable. A `USAGE_` code means the call was wrong. A `RUN_` code means the

package/dist/cli/core-types.d.ts

@@ -64,6 +64,8 @@ export interface ResolvedUnitLike {
     }[];
     /** 該單元各目標宣告的平台原生設定（ADR-006）；無宣告時缺席。 */
     readonly settings?: unknown;
+    /** 該單元各目標宣告的平台 plugin（`{ 平台名: [宣告] }`，ADR-044）；無宣告時缺席。 */
+    readonly plugins?: unknown;
 }
 export interface WatchTarget {
     readonly promptDir: string;
@@ -76,6 +78,8 @@ export interface WatchTarget {
     readonly targetPlan: unknown;
     /** 該單元各目標宣告的平台原生設定（`{ 平台名: 設定 }`）；無宣告時為 null。 */
     readonly settings: unknown;
+    /** 該單元各目標宣告的平台 plugin（`{ 平台名: [宣告] }`）；無宣告時為 null。 */
+    readonly plugins: unknown;
     readonly opts: {
         readonly select?: unknown;
         readonly externals: readonly unknown[];
@@ -96,6 +100,8 @@ export interface WatchInstallSpec {
     readonly installRoot: string;
     readonly targetPlan: unknown;
     readonly settings: unknown;
+    /** 平台 plugin 宣告（`{ 平台名: [宣告] }`，ADR-044）；無宣告時為 null 或缺席。 */
+    readonly plugins?: unknown;
     /** 每輪重跑的寫入模式（`build`／`install`／`export`，ADR-035）；省略時為安裝。 */
     readonly mode?: string;
     /** 單元的範圍（AC-538）。 */
@@ -148,6 +154,8 @@ export interface CoreArgs {
     readonly irPath: string;
     readonly settingsPath?: string;
     readonly externalsPath?: string;
+    /** 旁置的平台 plugin 宣告檔（ADR-044）；無宣告時為空字串或缺席。 */
+    readonly pluginsPath?: string;
     readonly root: string;
     readonly platform: string;
     readonly sourceRoot?: string;

package/dist/cli/main.d.ts

@@ -57,6 +57,14 @@ export declare const SWITCH_FIELDS: Readonly<Record<string, 'assumeYes' | 'json'
  * 多個目標因此共用同一份輸入而不互相覆寫。
  */
 export declare function writeSettingsFile(dir: string, settings: unknown): string;
+/**
+ * 寫出本單元的旁置平台 plugin 宣告檔，回傳路徑（無宣告時回空字串、不寫檔）。
+ *
+ * 內容即核心算好的 `{ 平台名: [宣告] }`（見 `orchestrate::unit_plugins`），形態與
+ * 平台設定的旁置檔相同、但分開成另一份（ADR-044）：平台設定逐字寫進平台的設定檔，
+ * 混進 plugin 宣告會被一起寫出去。
+ */
+export declare function writePluginsFile(dir: string, plugins: unknown): string;
 /**
  * 一個單元 × 一個目標的投影與落地，回傳結束碼（0 為成功）。
  *
@@ -85,7 +93,7 @@ export declare function writeSettingsFile(dir: string, settings: unknown): strin
  * 寫出的 `externalsPath`，其餘一律由核心的 `projection_entries` 算出本目標
  * 實際用得到的落點子集。
  */
-export declare function distributeTarget({ mode, scope, target, targetPlan, usedJson, externalsDir, irPath, settingsPath, externalsPath: fallbackExternalsPath, unitOutDir, unitName, installRoot, sourceRoot, select, }: {
+export declare function distributeTarget({ mode, scope, target, targetPlan, usedJson, externalsDir, irPath, settingsPath, pluginsPath, externalsPath: fallbackExternalsPath, unitOutDir, unitName, installRoot, sourceRoot, select, }: {
     mode: string;
     /** 單元的範圍（AC-538）；單一目錄模式與省略時為專案層。 */
     scope?: string;
@@ -96,6 +104,8 @@ export declare function distributeTarget({ mode, scope, target, targetPlan, used
     externalsDir: string;
     irPath: string;
     settingsPath: string;
+    /** 旁置的平台 plugin 宣告檔（ADR-044）；無宣告時為空字串或缺席。 */
+    pluginsPath?: string;
     externalsPath?: string;
     unitOutDir: string;
     unitName: string;
@@ -108,7 +118,7 @@ export declare function distributeTarget({ mode, scope, target, targetPlan, used
  *
  * 由 `src/cli/main.ts` 轉發呼叫。本檔被 import 而不呼叫本函式時（監看的求值
  * 子行程），上方那批模組層狀態維持初始值、不執行任何命令列行為 ── 那正是子
- * 行程要的：它只取用 `distributeTarget` 與 `writeSettingsFile`。
+ * 行程要的：它只取用 `distributeTarget`、`writeSettingsFile` 與 `writePluginsFile`。
  *
  * 賦值順序與此前的模組層敘述逐條相同：`configAction` 要早於 `parseCliArgs`
  * （後者讀它判斷第二個位置參數是否合法），`config` 分派要早於動詞白名單檢查

package/dist/cli/main.js

@@ -868,11 +868,14 @@ function emitStructured(out, targetPlatform, queryMeta, contents) {
         outcome: out,
     }), LOCALE));
 }
-/** `invokeCore`／`coreOutcome`／`runExtendedTarget` 共用的三份輸入讀法。 */
-function readNativeInputs(irPath, settingsPath, externalsPath) {
+/** `invokeCore`／`coreOutcome`／`runExtendedTarget` 共用的四份輸入讀法。 */
+function readNativeInputs(irPath, settingsPath, externalsPath, pluginsPath) {
     return {
         irJson: readFileSync(irPath, 'utf8'),
         settingsJson: readIfPresent(settingsPath),
+        // 平台 plugin 宣告（ADR-044）：與平台設定分開成另一份旁置檔，因為平台設定逐字
+        // 寫進平台的設定檔，混進 plugin 宣告會被一起寫出去。
+        pluginsJson: readIfPresent(pluginsPath),
         // 外部引用（AC-056 至 AC-060）：build 與 install／dry-run／manifest 走同一張
         // 落點表。build 不落地平台產物不代表它不需要落點資訊：省略的話引用外部目標
         // 的節點會渲染成 `[名稱](id)` 占位形態而非算出的相對路徑，而寫進框架中繼
@@ -889,17 +892,17 @@ function readNativeInputs(irPath, settingsPath, externalsPath) {
  * 呼叫核心的這一步因此必須與單獨執行 `build --install` 時完全相同，而非讀本檔
  * 頂層的 `command`（該值此時是 `'watch'`，不是綁定認得的動詞）。
  */
-function invokeCore({ irPath, settingsPath, externalsPath, root, platform, sourceRoot, unitName, mode = MODE, scope = 'project', queryMeta }) {
-    const result = coreOutcome({ irPath, settingsPath, externalsPath, root, platform, sourceRoot, unitName, mode, scope });
+function invokeCore({ irPath, settingsPath, externalsPath, pluginsPath, root, platform, sourceRoot, unitName, mode = MODE, scope = 'project', queryMeta }) {
+    const result = coreOutcome({ irPath, settingsPath, externalsPath, pluginsPath, root, platform, sourceRoot, unitName, mode, scope });
     if (!result.ok) {
         failOps(result.message);
     }
     // 沒有擴充的目標，核心的投影樹即最終落地的那一棵，取它就是安裝結果本身。
     let contents;
     if (CONTENT_REQUESTED) {
-        const { irJson, settingsJson, externalsJson } = readNativeInputs(irPath, settingsPath, externalsPath);
+        const { irJson, settingsJson, externalsJson, pluginsJson } = readNativeInputs(irPath, settingsPath, externalsPath, pluginsPath);
         try {
-            contents = JSON.parse(loadNativeCore().projectionTree(mode, root, irJson, platform, sourceRoot ?? '', settingsJson, externalsJson, unitName, LOCALE, scope));
+            contents = JSON.parse(loadNativeCore().projectionTree(mode, root, irJson, platform, sourceRoot ?? '', settingsJson, externalsJson, unitName, LOCALE, scope, pluginsJson));
         }
         catch (e) {
             failOps(e instanceof Error ? e.message : String(e));
@@ -917,19 +920,19 @@ function invokeCore({ irPath, settingsPath, externalsPath, root, platform, sourc
  * 兩者的結果形態不同（`BuildOutcome` 對 `DistributeOutcome`），由呼叫端依
  * `mode` 分流（`present` 的無標籤形態比對）。
  */
-function coreOutcome({ irPath, settingsPath, externalsPath, root, platform, sourceRoot, unitName: unit, mode = MODE, scope = 'project', }) {
+function coreOutcome({ irPath, settingsPath, externalsPath, pluginsPath, root, platform, sourceRoot, unitName: unit, mode = MODE, scope = 'project', }) {
     const native = loadNativeCore();
-    const { irJson, settingsJson, externalsJson } = readNativeInputs(irPath, settingsPath, externalsPath);
+    const { irJson, settingsJson, externalsJson, pluginsJson } = readNativeInputs(irPath, settingsPath, externalsPath, pluginsPath);
     try {
         if (mode === 'build') {
-            // `unit` 是最後一個引數：框架中繼住 `.promptex/{單元}/`（ADR-027），
-            // 省略它會讓每個單元都寫進預設單元的目錄而互相覆蓋。
+            // 框架中繼住 `.promptex/{單元}/`（ADR-027），省略 `unit` 會讓每個單元都寫進
+            // 預設單元的目錄而互相覆蓋。
             //
-            // 不傳 `sourceRoot`：那個引數只在拷貝型素材落地時當解析基準，而本動詞
-            // 不拷貝素材（ADR-028），綁定與核心都已不收它。`distribute` 那條仍要它。
-            return { ok: true, outcome: JSON.parse(native.build(irJson, root, platform, settingsJson, externalsJson, unit, LOCALE, scope)) };
+            // `sourceRoot` 排在最後：本動詞不拷貝素材（ADR-028），它只用來核對平台
+            // plugin 的 `modules` 檔案存在（ADR-044）。
+            return { ok: true, outcome: JSON.parse(native.build(irJson, root, platform, settingsJson, externalsJson, unit, LOCALE, scope, pluginsJson, sourceRoot ?? '')) };
         }
-        return { ok: true, outcome: JSON.parse(native.distribute(mode, irJson, root, platform, sourceRoot ?? '', settingsJson, unit, externalsJson, LOCALE, scope)) };
+        return { ok: true, outcome: JSON.parse(native.distribute(mode, irJson, root, platform, sourceRoot ?? '', settingsJson, unit, externalsJson, LOCALE, scope, pluginsJson)) };
     }
     catch (e) {
         return { ok: false, message: e instanceof Error ? e.message : String(e) };
@@ -1123,10 +1126,10 @@ async function runExtendedTarget(target, mode, coreArgs, unitOutDir, unitName, q
     const root = unitOutDir;
     const unit = unitName;
     const sourceRoot = coreArgs.sourceRoot;
-    const { irJson, settingsJson, externalsJson } = readNativeInputs(coreArgs.irPath, coreArgs.settingsPath, coreArgs.externalsPath);
+    const { irJson, settingsJson, externalsJson, pluginsJson } = readNativeInputs(coreArgs.irPath, coreArgs.settingsPath, coreArgs.externalsPath, coreArgs.pluginsPath);
     let beforeJson;
     try {
-        beforeJson = native.projectionTree(mode, root, irJson, target.platform, sourceRoot ?? '', settingsJson, externalsJson, unit, LOCALE, coreArgs.scope ?? 'project');
+        beforeJson = native.projectionTree(mode, root, irJson, target.platform, sourceRoot ?? '', settingsJson, externalsJson, unit, LOCALE, coreArgs.scope ?? 'project', pluginsJson);
     }
     catch (e) {
         failOps(e instanceof Error ? e.message : String(e));
@@ -1475,6 +1478,21 @@ export function writeSettingsFile(dir, settings) {
     dumpHandoff('PROMPTEX_DUMP_SETTINGS', text);
     return path;
 }
+/**
+ * 寫出本單元的旁置平台 plugin 宣告檔，回傳路徑（無宣告時回空字串、不寫檔）。
+ *
+ * 內容即核心算好的 `{ 平台名: [宣告] }`（見 `orchestrate::unit_plugins`），形態與
+ * 平台設定的旁置檔相同、但分開成另一份（ADR-044）：平台設定逐字寫進平台的設定檔，
+ * 混進 plugin 宣告會被一起寫出去。
+ */
+export function writePluginsFile(dir, plugins) {
+    if (!plugins)
+        return '';
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'plugins.json');
+    writeFileSync(path, `${JSON.stringify(plugins, null, 2)}\n`);
+    return path;
+}
 /**
  * 既有單一目錄模式：srcDir／root／platform／unit 均取 CLI 旗標，行為與配置
  * 單元系統實作前逐字相同。
@@ -1509,9 +1527,10 @@ async function runSingleDir() {
     const status = invokeCore({
         irPath,
         // 單一目錄模式沒有配置檔，也就沒有 target 可宣告平台原生設定
-        // （ADR-006「平台設定住目標」）：這裡恆為空。
+        // （ADR-006「平台設定住目標」），平台 plugin 同理（ADR-044）：這裡恆為空。
         settingsPath: '',
         externalsPath: '',
+        pluginsPath: '',
         root: singleRoot,
         platform,
         sourceRoot: srcDir,
@@ -1548,7 +1567,7 @@ async function runSingleDir() {
  * 寫出的 `externalsPath`，其餘一律由核心的 `projection_entries` 算出本目標
  * 實際用得到的落點子集。
  */
-export async function distributeTarget({ mode, scope = 'project', target, targetPlan, usedJson, externalsDir, irPath, settingsPath, externalsPath: fallbackExternalsPath = '', unitOutDir, unitName, installRoot, sourceRoot, select, }) {
+export async function distributeTarget({ mode, scope = 'project', target, targetPlan, usedJson, externalsDir, irPath, settingsPath, pluginsPath = '', externalsPath: fallbackExternalsPath = '', unitOutDir, unitName, installRoot, sourceRoot, select, }) {
     present({ kind: 'unitHeader', unit: unitName, platform: target.platform, outDir: unitOutDir });
     const queryMeta = { unit: unitName, installRoot };
     if ('emit' in target && typeof target.emit === 'function') {
@@ -1559,7 +1578,7 @@ export async function distributeTarget({ mode, scope = 'project', target, target
     const externalsPath = targetPlan
         ? writeExternalsFile(externalsDir, target.platform, JSON.parse(loadNativeCore().orchestrateProjectionEntries(targetJson, usedJson, LOCALE)))
         : fallbackExternalsPath;
-    const coreArgs = { irPath, settingsPath, externalsPath, platform: target.platform, sourceRoot, unitName, scope };
+    const coreArgs = { irPath, settingsPath, externalsPath, pluginsPath, platform: target.platform, sourceRoot, unitName, scope };
     // 平台適配的擴充（AC 無對應條款，依 promptex-prototype 原型行為實作）：
     // 各寫入模式一律走同一條路，起點與落地方式的差異由核心承擔（見
     // `runExtendedTarget`）。
@@ -1659,6 +1678,8 @@ async function runConfigUnits(configPath) {
         // 平台原生設定由核心從各目標的宣告合成（ADR-006「平台設定住目標」），本層
         // 只把它原樣寫成投影要吃的旁置檔，不自行從配置物件取一次。
         const settingsPath = writeSettingsFile(compileDir, resolved.settings);
+        // 平台 plugin 宣告同樣由核心合成（ADR-044），寫成另一份旁置檔。
+        const pluginsPath = writePluginsFile(compileDir, resolved.plugins);
         const { irPath, diagnostics } = await compile(resolved.srcDir, compileDir, {
             // 專案根即配置檔所在目錄（PDR-003），與下方呼叫核心時傳的 sourceRoot
             // 同一個值：plugin 的快取目錄與 asset 素材的換算基準因此不會分家。
@@ -1700,6 +1721,7 @@ async function runConfigUnits(configPath) {
                 externalsDir: compileDir,
                 irPath,
                 settingsPath,
+                pluginsPath,
                 unitOutDir: targetOutDir,
                 unitName,
                 installRoot: MODE === 'export' ? targetOutDir : resolved.installRoot,
@@ -1724,7 +1746,7 @@ async function runConfigUnits(configPath) {
  *
  * 由 `src/cli/main.ts` 轉發呼叫。本檔被 import 而不呼叫本函式時（監看的求值
  * 子行程），上方那批模組層狀態維持初始值、不執行任何命令列行為 ── 那正是子
- * 行程要的：它只取用 `distributeTarget` 與 `writeSettingsFile`。
+ * 行程要的：它只取用 `distributeTarget`、`writeSettingsFile` 與 `writePluginsFile`。
  *
  * 賦值順序與此前的模組層敘述逐條相同：`configAction` 要早於 `parseCliArgs`
  * （後者讀它判斷第二個位置參數是否合法），`config` 分派要早於動詞白名單檢查
@@ -1827,6 +1849,8 @@ export async function main(argv) {
         let watchTargetPlan = null;
         // 單一目錄模式沒有配置檔、也就沒有 target 可宣告平台原生設定（ADR-006）。
         let watchSettings = null;
+        // 平台 plugin 同理只住目標（ADR-044）。
+        let watchPlugins = null;
         // 單元的範圍（AC-538）：單一目錄模式固定專案層，配置單元模式取解析結果。
         let watchScope = 'project';
         if (existsSync(configPath)) {
@@ -1858,7 +1882,8 @@ export async function main(argv) {
             }
             ;
             ({ promptDir: watchPromptDir, root: watchRoot, platform: watchPlatform, unitName: watchUnit,
-                installRoot: watchInstallRoot, targetPlan: watchTargetPlan, settings: watchSettings, opts: watchOpts } = target);
+                installRoot: watchInstallRoot, targetPlan: watchTargetPlan, settings: watchSettings, plugins: watchPlugins,
+                opts: watchOpts } = target);
             watchScope = resolution.units.find((u) => u.name === watchUnit)?.scope ?? 'project';
             // 素材相對路徑的換算基準是專案根（配置檔所在目錄），與 runConfigUnits
             // 呼叫核心時傳的 sourceRoot 同一個值：監看沿用安裝流程，不另立一套換算
@@ -1894,6 +1919,7 @@ export async function main(argv) {
                     installRoot: watchInstallRoot,
                     targetPlan: watchTargetPlan,
                     settings: watchSettings,
+                    plugins: watchPlugins,
                     mode: MODE,
                     scope: watchScope,
                 },

package/dist/cli/watch-pass.js

@@ -106,7 +106,7 @@ async function unitDef() {
  * 作者改完檔案永遠等不到下一輪）。本輪安裝成功與否由行程的結束碼帶回。
  */
 async function installTarget(unit, result, spec) {
-    const { distributeTarget, writeSettingsFile } = await import('./main.js');
+    const { distributeTarget, writePluginsFile, writeSettingsFile } = await import('./main.js');
     const { engine } = await import('../index.js');
     // 無配置檔時目標就是命令列指定的那個平台，沒有 emit 也沒有 extend；有配置
     // 檔時取回作者宣告的那一筆（帶不經序列化的閉包）。
@@ -124,6 +124,8 @@ async function installTarget(unit, result, spec) {
         // 平台設定由父行程從核心的單元解析結果帶過來（ADR-006「平台設定住目標」），
         // 不由本輪求值產出：它是配置的宣告，重新求值不會改變它。
         settingsPath: writeSettingsFile(workDir, spec.settings ?? null),
+        // 平台 plugin 宣告與平台設定同一條（ADR-044），分開成另一份旁置檔。
+        pluginsPath: writePluginsFile(workDir, spec.plugins ?? null),
         externalsPath: result.externalsPath,
         unitOutDir: spec.root,
         unitName: spec.unitName,

package/dist/cli/watch.js

@@ -291,6 +291,8 @@ export function resolveWatchTarget(resolved, rawUnits = []) {
         // 平台原生設定隨單元的解析結果一起帶過去（ADR-006「平台設定住目標」）：
         // 監看沿用安裝流程，設定的來源因此也與 安裝模式（`--install`）同一個。
         settings: only.settings ?? null,
+        // 平台 plugin 宣告同理（ADR-044）。
+        plugins: only.plugins ?? null,
         opts: {
             select: rawUnits[target.unitIndex]?.select,
             externals: target.evaluationExternals,

package/dist/cli-contract.generated.d.ts

@@ -1,5 +1,5 @@
 /** 核心的格式版本（`crates/promptex-core/src/graph.rs` 的 `FORMAT_VERSION`），不載入原生綁定即可取得。 */
-export declare const FORMAT_VERSION = "1.1";
+export declare const FORMAT_VERSION = "1.2";
 export type Ecosystem = 'js' | 'py' | 'rs';
 export interface VerbSpec {
     name: string;

package/dist/cli-contract.generated.js

@@ -4,7 +4,7 @@
 // crates/promptex-core/src/graph.rs 的 FORMAT_VERSION。要改內容就改來源，
 // 再跑 `pnpm run gen:cli-contract` 重新生成；直接改本檔會被核對閘擋下。
 /** 核心的格式版本（`crates/promptex-core/src/graph.rs` 的 `FORMAT_VERSION`），不載入原生綁定即可取得。 */
-export const FORMAT_VERSION = '1.1';
+export const FORMAT_VERSION = '1.2';
 export const VERBS = [
     {
         name: 'build',

package/dist/config.d.ts

@@ -80,16 +80,49 @@ export interface Target {
     readonly extend?: readonly AdapterExtension[];
     /** 該平台的原生設定；鍵值逐字寫入該平台的設定檔。 */
     readonly settings?: Record<string, unknown>;
+    /**
+     * 平台 plugin 的分組（ADR-044），只有內建 `claude()`／`codex()` 收這個選項；
+     * 第三方適配（`defineTarget`）不提供它，核心對第三方目標的宣告以 E219 阻斷。
+     */
+    readonly plugins?: readonly PlatformPlugin[];
+}
+/**
+ * 目標上的一個平台 plugin（ADR-044）：把一組節點打包成平台原生的 plugin。
+ *
+ * `select` 沿用單元的 `SelectSpec`，但只決定歸屬：它在單元的 `select` 已選出的
+ * 節點裡分組，選不到單元沒選的節點。沒被任何 plugin 選到的節點照常各自安裝；
+ * 一個節點在同一目標最多屬於一個 plugin。
+ *
+ * 這和單元的 `plugins`（解析期擴充，`Plugin`）是兩件事：這裡的產物是平台的 plugin
+ * 目錄，那裡是解析節點時執行的擴充。
+ */
+export interface PlatformPlugin {
+    /** plugin 名稱：小寫英數加 `-`，長度 1 至 64，不含 `--`，不用 Claude 保留名。 */
+    readonly name: string;
+    /** 版本字串，不核對格式；省略時不寫進 manifest。 */
+    readonly version?: string;
+    readonly description?: string;
+    readonly select: SelectSpec;
+    /** 原樣帶進 manifest 的其他欄位；不得覆寫框架產生的鍵（name、元件路徑等）。 */
+    readonly manifest?: Record<string, unknown>;
+    /** mod 的 hooks module 路徑，相對 plugin 根目錄，指向同一個 plugin 內 dir 節點的檔案（只屬於 Claude）。 */
+    readonly modules?: string;
 }
+/** codex 目標的平台 plugin：mod 只屬於 Claude，因此沒有 `modules`。 */
+export type CodexPlatformPlugin = Omit<PlatformPlugin, 'modules'>;
 /** claude target 建構器的選項。 */
 export interface ClaudeTargetOptions {
     readonly extend?: readonly AdapterExtension[];
     readonly settings?: ClaudeSettings;
+    /** 打包成 Claude plugin 的節點分組（ADR-044）。 */
+    readonly plugins?: readonly PlatformPlugin[];
 }
 /** codex target 建構器的選項。 */
 export interface CodexTargetOptions {
     readonly extend?: readonly AdapterExtension[];
     readonly settings?: CodexSettings;
+    /** 打包成 Codex plugin 的節點分組（ADR-044）。 */
+    readonly plugins?: readonly CodexPlatformPlugin[];
 }
 /** claude target 建構器：求值為 `{ platform: 'claude' }`（AC-086），可選帶 `extend` 擴充既有平台的產物形態、`settings` 宣告平台原生設定。 */
 export declare const claude: (options?: ClaudeTargetOptions) => Target;
@@ -190,6 +223,16 @@ export interface TargetIR {
     readonly settings?: Record<string, unknown>;
     readonly configSchema?: unknown;
     readonly configSchemaLocales?: Record<string, unknown>;
+    readonly plugins?: readonly PlatformPluginIR[];
+}
+/** 中介表示裡的一個平台 plugin：欄位順序與核心的 `PluginDecl` 相同，三語言逐字一致。 */
+export interface PlatformPluginIR {
+    readonly name: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly select: SelectSpec;
+    readonly manifest?: Record<string, unknown>;
+    readonly modules?: string;
 }
 /** 中介表示裡的一個擴充：求值期的名字，加上它的參數宣告（ADR-013） */
 export interface PluginIR {

package/dist/config.js

@@ -13,6 +13,7 @@ function builtinTarget(platform, options) {
         platform,
         ...(options?.extend?.length ? { extend: options.extend } : {}),
         ...(options?.settings ? { settings: options.settings } : {}),
+        ...(options?.plugins?.length ? { plugins: options.plugins } : {}),
     };
 }
 /** claude target 建構器：求值為 `{ platform: 'claude' }`（AC-086），可選帶 `extend` 擴充既有平台的產物形態、`settings` 宣告平台原生設定。 */
@@ -35,6 +36,20 @@ export function isExternalConfigRef(spec) {
 export function defineConfig(unit) {
     return Array.isArray(unit) ? [...unit] : [unit];
 }
+/** 平台 plugin → 中介表示：鍵序固定、省略的欄位不帶，`select` 只留宣告了的兩個欄位。 */
+function platformPluginToIR(p) {
+    return {
+        name: p.name,
+        ...(p.version !== undefined ? { version: p.version } : {}),
+        ...(p.description !== undefined ? { description: p.description } : {}),
+        select: {
+            ...(p.select.tags !== undefined ? { tags: p.select.tags } : {}),
+            ...(p.select.exclude !== undefined ? { exclude: p.select.exclude } : {}),
+        },
+        ...(p.manifest !== undefined ? { manifest: p.manifest } : {}),
+        ...(p.modules !== undefined ? { modules: p.modules } : {}),
+    };
+}
 /**
  * 命令列工具交給核心編排入口的配置形態（ADR-008 協作形態第 1 步）。
  *
@@ -67,6 +82,9 @@ export function configToOrchestrationIR(units) {
                 ...(t.settings ? { settings: t.settings } : {}),
                 ...(t.configSchema !== undefined ? { configSchema: t.configSchema } : {}),
                 ...(t.configSchemaLocales ? { configSchemaLocales: t.configSchemaLocales } : {}),
+                // 平台 plugin 是純資料（ADR-044），進中介表示交給核心分組；無宣告時不帶這一鍵，
+                // 未使用它的既有配置求值結果逐字不變。
+                ...(t.plugins?.length ? { plugins: t.plugins.map(platformPluginToIR) } : {}),
             })),
             // 擴充帶名字與它的參數宣告（ADR-013）：宣告由擴充自己 import 進來，隨中介表示
             // 交給讀取端，讀取端因此不必知道它裝在哪裡。未宣告時該欄省略而非填 null：

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { Content, ContentPiece, Ref, SelectSpec } from './registry.js';
 export type { Ir, Kind, Node, Piece, Provenance, RefTarget } from './ir.js';
 export type { MDNode } from './content.js';
 export { engine, registerExternal } from './registry.js';
-export { claude, codex, configToIR, configToOrchestrationIR, defineConfig, isExternalConfigRef, type AdapterExtension, type ClaudeSettings, type ClaudeTargetOptions, type CodexSettings, type CodexTargetOptions, type ConfigIr, type ConfigUnit, type ConfigUnitIR, type ExternalConfigRef, type ExternalEntry as ConfigExternalEntry, type ExternalSpec, type Target, } from './config.js';
+export { claude, codex, configToIR, configToOrchestrationIR, defineConfig, isExternalConfigRef, type AdapterExtension, type ClaudeSettings, type ClaudeTargetOptions, type CodexSettings, type CodexPlatformPlugin, type CodexTargetOptions, type ConfigIr, type ConfigUnit, type ConfigUnitIR, type ExternalConfigRef, type ExternalEntry as ConfigExternalEntry, type ExternalSpec, type PlatformPlugin, type PlatformPluginIR, type Target, } from './config.js';
 export type { ManifestNode, ManifestQuery } from './externals.js';
 export { readConfig, REFUSAL_MESSAGES, declaredSchema, RefusalError, SCHEMA_FILE, writeConfig, type ConfigView, type Entry, type EntryField, type ImportStyle, type Op, type Refusal, type RefusalCode, type RewriteOutcome, type UnitView, } from './config-rewrite.js';
 export type { LockEntry, Plugin, PluginEntry, PrepareContext, TransformContext, ValidateContext } from './plugin.js';

package/dist/native.d.ts

@@ -17,9 +17,15 @@
  */
 export interface NativeCore {
     /** 編譯：完整投影計算，只寫框架中繼、不落平台產物（ADR-028）。 */
-    build(irJson: string, root: string, platform: string, settingsJson: string | null | undefined, externalsJson: string | null | undefined, unit: string | null | undefined, locale: string, scope?: string | null): string;
+    build(irJson: string, root: string, platform: string, settingsJson: string | null | undefined, externalsJson: string | null | undefined, unit: string | null | undefined, locale: string, scope?: string | null, 
+    /** 旁置的平台 plugin 宣告（`{ 平台名: [宣告] }`，ADR-044）。 */
+    pluginsJson?: string | null, 
+    /** 只用來核對平台 plugin 的 `modules` 檔案存在；本動詞不拷貝素材。 */
+    sourceRoot?: string | null): string;
     /** 安裝／預覽／查詢：`mode` 決定副作用範圍。 */
-    distribute(mode: string, irJson: string, root: string, platform: string, sourceRoot: string, settingsJson: string | null | undefined, unit: string, externalsJson: string | null | undefined, locale: string, scope?: string | null): string;
+    distribute(mode: string, irJson: string, root: string, platform: string, sourceRoot: string, settingsJson: string | null | undefined, unit: string, externalsJson: string | null | undefined, locale: string, scope?: string | null, 
+    /** 旁置的平台 plugin 宣告（ADR-044）。 */
+    pluginsJson?: string | null): string;
     /** 第三方適配的產物落地（AC-244）：`emit` 回傳的檔案表交回核心。 */
     thirdPartyDistribute(mode: string, filesJson: string, irJson: string, reportJson: string, root: string, unit: string, platform: string, locale: string): string;
     /**
@@ -31,7 +37,9 @@ export interface NativeCore {
      */
     projectionTree(mode: string, root: string, irJson: string, platform: string, sourceRoot: string, settingsJson: string | null | undefined, externalsJson: string | null | undefined, unit: string | null | undefined, locale: string, 
     /** 單元的範圍（`user`／`project`，AC-538）；省略時視為專案層。 */
-    scope?: string | null): string;
+    scope?: string | null, 
+    /** 旁置的平台 plugin 宣告（ADR-044）。 */
+    pluginsJson?: string | null): string;
     /** 平台擴充的落地：比對擴充前後的產物樹並寫入。 */
     extensionApply(mode: string, root: string, unit: string, platform: string, beforeJson: string, afterJson: string, baselineJson: string, locale: string): string;
     /** 人讀版面（ADR-030）：版面住核心，三個生態印出同一份。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptex-js",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "TypeScript SDK、核心的預編譯二進位綁定與命令列工具，三者為同一次發布產出",
   "license": "MIT OR Apache-2.0",
   "author": "promptex-ai",
@@ -74,11 +74,11 @@
     "vitest": "^4.1.11"
   },
   "optionalDependencies": {
-    "promptex-js-darwin-arm64": "1.1.1",
-    "promptex-js-darwin-x64": "1.1.1",
-    "promptex-js-linux-arm64-gnu": "1.1.1",
-    "promptex-js-linux-x64-gnu": "1.1.1",
-    "promptex-js-win32-arm64-msvc": "1.1.1",
-    "promptex-js-win32-x64-msvc": "1.1.1"
+    "promptex-js-darwin-arm64": "1.2.0",
+    "promptex-js-darwin-x64": "1.2.0",
+    "promptex-js-linux-arm64-gnu": "1.2.0",
+    "promptex-js-linux-x64-gnu": "1.2.0",
+    "promptex-js-win32-arm64-msvc": "1.2.0",
+    "promptex-js-win32-x64-msvc": "1.2.0"
   }
 }