i-repo 2.7.0 → 2.8.0

package/dist/commands/plugin.js

@@ -98,24 +98,25 @@ pluginCommand
                     .map((p) => {
                     const choices = Array.isArray(p.choices) ? `:${p.choices.join("|")}` : "";
                     const markers = `${p.required ? " (required)" : ""}${p.secret ? " (secret)" : ""}` +
+                        `${p.destructive ? " (destructive)" : ""}` +
                         `${typeof p.subcommand === "string" ? ` [${p.subcommand}]` : ""}`;
                     return `${String(p.name)} <${String(p.type)}${choices}>${markers}`;
                 })
                     .join(", ");
             }
-            if (Array.isArray(row.platforms)) {
-                row.platforms = row.platforms.join(", ");
-            }
-            if (Array.isArray(row.input)) {
-                row.input = row.input.join(", ");
+            for (const key of ["platforms", "input", "roles", "capabilities", "useCases"]) {
+                if (Array.isArray(row[key])) {
+                    row[key] = row[key].join(", ");
+                }
             }
             if (Array.isArray(row.subcommands)) {
                 row.subcommands = row.subcommands
                     .map((s) => {
                     const intake = Array.isArray(s.input) ? ` [${s.input.join("/")}]` : "";
+                    const destructive = s.destructive ? " (destructive)" : "";
                     return s.description
-                        ? `${String(s.name)}${intake} (${String(s.description)})`
-                        : `${String(s.name)}${intake}`;
+                        ? `${String(s.name)}${intake}${destructive} (${String(s.description)})`
+                        : `${String(s.name)}${intake}${destructive}`;
                 })
                     .join(", ");
             }

package/dist/plugins/describe.d.ts

@@ -30,6 +30,22 @@ export declare function platformKeywordFor(p: NodeJS.Platform): PluginPlatform |
  */
 export declare const KNOWN_INPUTS: readonly ["stdin-ndjson", "files", "dir", "none"];
 export type PluginInput = (typeof KNOWN_INPUTS)[number];
+/**
+ * roles (プラグインが担う価値軸) の閉じた語彙 (要望書v3)。
+ * 「このプラグインは何をする向きか」を機械可読にする — エージェント/GUI が
+ * store 名から推測せず宣言を読むための土台。CLI 本体はこれでゲートしない
+ * (input/platforms と同じく宣言した意図を伝えるヒント)。閉じた語彙なので
+ * 綴り誤り (`sinks`/`reader` 等) は describe-shape の契約違反として検出される。
+ *   source  = 外部システムから取り出す入口
+ *   sink    = 抽出済みデータを保存先へ書き込む
+ *   read    = 着地済みを読み返す (read-only)
+ *   search  = 全文検索・ファセットに向く
+ *   analyze = 集計・DWH・Lakehouse に向く
+ *   keep    = 成果物・証跡を束ねて残す
+ * 予約 (将来追加): lifecycle / derive / subscribe — 現時点では未採用。
+ */
+export declare const KNOWN_ROLES: readonly ["source", "sink", "read", "search", "analyze", "keep"];
+export type PluginRole = (typeof KNOWN_ROLES)[number];
 /** params の1エントリ。GUI/ink がフォーム部品へ写像できる最小集合に絞る */
 export interface PluginParam {
     /** フラグ名 (例: "--bucket") */
@@ -48,6 +64,12 @@ export interface PluginParam {
     placeholder?: string;
     /** 属するサブコマンド (subcommands のいずれかの name)。未設定 = 全サブコマンド共通 */
     subcommand?: string;
+    /**
+     * このフラグを渡すと不可逆な破壊 (削除等) を起こす申告 (要望書v3)。例: --cleanup。
+     * CLI 本体は実行可否を変えない (input と同じヒント) — 自動拒否は宣言を読む側
+     * (ADC/エージェント) の役割。GUI 無し面でのエージェント安全策の土台。
+     */
+    destructive?: boolean;
 }
 /** サブコマンドの宣言 (要望5)。params[].subcommand がここの name を参照する */
 export interface PluginSubcommand {
@@ -55,6 +77,8 @@ export interface PluginSubcommand {
     description?: string;
     /** このサブコマンドの intake。プラグインレベルの input を上書きする (要望書v2 §3.2) */
     input?: PluginInput[];
+    /** このサブコマンド全体が不可逆な破壊を起こす申告 (要望書v3)。params[].destructive と同じ哲学 */
+    destructive?: boolean;
 }
 /** --plugin-schema 応答の全体形 (基本 + 拡張。未知フィールドは無視) */
 export interface PluginDescribe {
@@ -75,6 +99,18 @@ export interface PluginDescribe {
      * 渡し方を推測しない)。subcommands[].input がある場合はそちらが優先。
      */
     input?: PluginInput[];
+    /**
+     * roles = プラグインが担う価値軸の宣言 (要望書v3)。閉じた語彙 (KNOWN_ROLES)。
+     * 未宣言 = 不明 (連携側は推測しない)。
+     */
+    roles?: PluginRole[];
+    /**
+     * capabilities = 細粒度の能力タグ (要望書v3)。開いた語彙 (例 "cluster-filter") —
+     * verify は型 (string[]) のみ検証し、メンバーシップは検証しない (綴り誤りは検出しない)。
+     */
+    capabilities?: string[];
+    /** useCases = 用途タグ (要望書v3)。capabilities と同じく開いた語彙・型のみ検証 */
+    useCases?: string[];
 }
 /**
  * plugin describe の表示行を組む。plugin/path は CLI が解決した事実 —

package/dist/plugins/describe.js

@@ -39,6 +39,21 @@ export function platformKeywordFor(p) {
  * あくまで receipt の verified)。
  */
 export const KNOWN_INPUTS = ["stdin-ndjson", "files", "dir", "none"];
+/**
+ * roles (プラグインが担う価値軸) の閉じた語彙 (要望書v3)。
+ * 「このプラグインは何をする向きか」を機械可読にする — エージェント/GUI が
+ * store 名から推測せず宣言を読むための土台。CLI 本体はこれでゲートしない
+ * (input/platforms と同じく宣言した意図を伝えるヒント)。閉じた語彙なので
+ * 綴り誤り (`sinks`/`reader` 等) は describe-shape の契約違反として検出される。
+ *   source  = 外部システムから取り出す入口
+ *   sink    = 抽出済みデータを保存先へ書き込む
+ *   read    = 着地済みを読み返す (read-only)
+ *   search  = 全文検索・ファセットに向く
+ *   analyze = 集計・DWH・Lakehouse に向く
+ *   keep    = 成果物・証跡を束ねて残す
+ * 予約 (将来追加): lifecycle / derive / subscribe — 現時点では未採用。
+ */
+export const KNOWN_ROLES = ["source", "sink", "read", "search", "analyze", "keep"];
 const PARAM_TYPES = new Set(["string", "number", "boolean", "select"]);
 /**
  * plugin describe の表示行を組む。plugin/path は CLI が解決した事実 —
@@ -120,7 +135,10 @@ export async function probePlatforms(bin, timeoutMs = 1500) {
 }
 /** 拡張フィールドのいずれかを宣言しているか */
 export function hasDescribeFields(row) {
-    return ["name", "version", "description", "phases", "params", "platforms", "subcommands", "input"].some((k) => k in row);
+    return [
+        "name", "version", "description", "phases", "params", "platforms",
+        "subcommands", "input", "roles", "capabilities", "useCases",
+    ].some((k) => k in row);
 }
 /**
  * input (intake) 宣言の検査。閉じた語彙の非空配列であること。
@@ -171,6 +189,27 @@ export function validateDescribe(row) {
         if (problem)
             problems.push(problem);
     }
+    if ("roles" in row) {
+        // 閉じた語彙を強制する: typo (`sinks`/`reader` 等) を受理すると、宣言したのに
+        // エージェント/GUI のどの判定にもマッチしない沈黙の失敗になる。空配列は
+        // 「役割なし」= 宣言ミス扱い (未宣言と区別する意味がない)。
+        const r = row.roles;
+        if (!Array.isArray(r) ||
+            r.length === 0 ||
+            !r.every((v) => typeof v === "string" && KNOWN_ROLES.includes(v))) {
+            problems.push(`roles must be a non-empty array of ${KNOWN_ROLES.map((k) => `"${k}"`).join(" | ")}`);
+        }
+    }
+    // capabilities / useCases は開いた語彙 — 型 (string[]) だけ検証し、値は検証しない
+    // (phases と同じ扱い)。未知の能力タグを宣言できるようにするのが要望の主旨。
+    for (const key of ["capabilities", "useCases"]) {
+        if (key in row) {
+            const v = row[key];
+            if (!Array.isArray(v) || !v.every((x) => typeof x === "string")) {
+                problems.push(`${key} must be an array of strings`);
+            }
+        }
+    }
     let declaredSubs = null;
     if ("subcommands" in row) {
         const subs = row.subcommands;
@@ -202,6 +241,9 @@ export function validateDescribe(row) {
                     if (problem)
                         problems.push(problem);
                 }
+                if ("destructive" in s && typeof s.destructive !== "boolean") {
+                    problems.push(`subcommands[${i}].destructive must be a boolean`);
+                }
             });
         }
     }
@@ -261,6 +303,9 @@ export function validateDescribe(row) {
                 if ("secret" in p && typeof p.secret !== "boolean") {
                     problems.push(`params[${i}].secret must be a boolean`);
                 }
+                if ("destructive" in p && typeof p.destructive !== "boolean") {
+                    problems.push(`params[${i}].destructive must be a boolean`);
+                }
                 for (const key of ["label", "placeholder"]) {
                     if (key in p && typeof p[key] !== "string") {
                         problems.push(`params[${i}].${key} must be a string`);

package/dist/plugins/templates.js

@@ -24,8 +24,10 @@ case "\${1:-}" in
     printf '{"ok":true,"checks":[{"name":"ready","ok":true,"severity":"required","hint":"TODO: how to fix when this fails"}]}\\n'
     exit 0 ;;
   --plugin-schema)
-    # 自己記述 (PLUGINS.md §3)。params は GUI/ink のフォーム生成に使われる
-    printf '{"pluginApi":["1"],"schemaVersions":["1.0"],"recordTypes":["*"],"name":"i-repo-${name}","version":"0.1.0","description":"TODO: what this plugin does","phases":["write","verify"],"platforms":["macos","linux"],"input":["stdin-ndjson"],"params":[{"name":"--dry-run","type":"boolean","label":"Dry run","description":"Validate without writing"}]}\\n'
+    # 自己記述 (PLUGINS.md §3)。params は GUI/ink のフォーム生成に使われる。
+    # roles: 担う価値軸 (閉じた語彙 source|sink|read|search|analyze|keep)。sink が既定。
+    # 破壊的フラグ (削除等) があれば params に "destructive":true を付ける (要望書v3)。
+    printf '{"pluginApi":["1"],"schemaVersions":["1.0"],"recordTypes":["*"],"name":"i-repo-${name}","version":"0.1.0","description":"TODO: what this plugin does","phases":["write","verify"],"platforms":["macos","linux"],"input":["stdin-ndjson"],"roles":["sink"],"params":[{"name":"--dry-run","type":"boolean","label":"Dry run","description":"Validate without writing"}]}\\n'
     exit 0 ;;
 esac
 
@@ -41,8 +43,9 @@ dryrun=false
 jobId="${name}-\$(date +%Y%m%dT%H%M%S)-\$\$"
 
 #   $1=phase $2=count $3=failedCount $4=verified   (SCHEMA.md §6)
+#   producedBy = 来歴 (どのプラグインの何版が作ったか。版ズレ検知用・要望書v3)
 emit_receipt() {
-  printf '{"schemaVersion":"1.0","recordType":"receipt","plugin":"i-repo-${name}","phase":"%s","jobId":"%s","count":%s,"failedCount":%s,"verified":%s}\\n' \\
+  printf '{"schemaVersion":"1.0","recordType":"receipt","plugin":"i-repo-${name}","phase":"%s","jobId":"%s","count":%s,"failedCount":%s,"verified":%s,"producedBy":{"plugin":"i-repo-${name}","version":"0.1.0"}}\\n' \\
     "\$1" "\$jobId" "\$2" "\$3" "\$4"
 }
 
@@ -107,15 +110,19 @@ if (arg0 === "--plugin-healthcheck") {
   }));
   process.exit(0);
 }
+const VERSION = "0.1.0";
 if (arg0 === "--plugin-schema") {
-  // 自己記述 (PLUGINS.md §3)。params は GUI/ink のフォーム生成に使われる
+  // 自己記述 (PLUGINS.md §3)。params は GUI/ink のフォーム生成に使われる。
+  // roles: 担う価値軸 (閉じた語彙 source|sink|read|search|analyze|keep)。sink が既定。
+  // 破壊的フラグ (削除等) があれば該当 param に destructive: true を付ける (要望書v3)。
   console.log(JSON.stringify({
     pluginApi: ["1"], schemaVersions: ["1.0"], recordTypes: ["*"],
-    name: PLUGIN, version: "0.1.0",
+    name: PLUGIN, version: VERSION,
     description: "TODO: what this plugin does",
     phases: ["write", "verify"],
     platforms: ["macos", "linux", "windows"],
     input: ["stdin-ndjson"],
+    roles: ["sink"],
     params: [
       { name: "--dry-run", type: "boolean", label: "Dry run", description: "Validate without writing" },
     ],
@@ -133,11 +140,12 @@ if (api && api !== "1") {
 const dryRun = arg0 === "--dry-run";
 const jobId = \`${name}-\${new Date().toISOString().replace(/[-:.TZ]/g, "")}-\${process.pid}\`;
 
-/** Emit a receipt line (SCHEMA.md §6). */
+/** Emit a receipt line (SCHEMA.md §6). producedBy = 来歴 (版ズレ検知用・要望書v3). */
 function receipt(phase, count, failedCount, verified) {
   console.log(JSON.stringify({
     schemaVersion: "1.0", recordType: "receipt", plugin: PLUGIN,
     phase, jobId, count, failedCount, verified,
+    producedBy: { plugin: PLUGIN, version: VERSION },
   }));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i-repo",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Modern CLI for ConMas i-Reporter - Built for humans and AI",
   "type": "module",
   "bin": {