i-repo 2.4.0 → 2.5.0

package/dist/commands/plugin.js

@@ -91,13 +91,26 @@ pluginCommand
         const row = buildDescribeRow(PLUGIN_PREFIX + name, bin, declared);
         // 人間面 (table/csv) では params を読める1行に整形 (ndjson/json は宣言そのまま —
         // render と同じ「ラベル化は人間面のみ」の流儀)
-        if ((format === "table" || format === "csv") && Array.isArray(row.params)) {
-            row.params = row.params
-                .map((p) => {
-                const choices = Array.isArray(p.choices) ? `:${p.choices.join("|")}` : "";
-                return `${String(p.name)} <${String(p.type)}${choices}>${p.required ? " (required)" : ""}`;
-            })
-                .join(", ");
+        if (format === "table" || format === "csv") {
+            if (Array.isArray(row.params)) {
+                // label は GUI の関心事 — CLI は実フラグ名を見せる
+                row.params = row.params
+                    .map((p) => {
+                    const choices = Array.isArray(p.choices) ? `:${p.choices.join("|")}` : "";
+                    const markers = `${p.required ? " (required)" : ""}${p.secret ? " (secret)" : ""}` +
+                        `${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.subcommands)) {
+                row.subcommands = row.subcommands
+                    .map((s) => (s.description ? `${String(s.name)} (${String(s.description)})` : String(s.name)))
+                    .join(", ");
+            }
         }
         formatOutput(row, {
             format,

package/dist/plugins/describe.d.ts

@@ -13,6 +13,14 @@
  * すべて任意 (非破壊追加)。ただし宣言した以上は正しい形であること —
  * 壊れた宣言を黙って受理するとフォーム生成側が実行時に壊れる (fail loudly)。
  */
+/**
+ * platforms の閉じた語彙。process.platform ではなく人間向けの名前で宣言する
+ * (シェルスクリプトのプラグイン作者が "darwin" を知っている必要はない)。
+ */
+export declare const KNOWN_PLATFORMS: readonly ["macos", "linux", "windows"];
+export type PluginPlatform = (typeof KNOWN_PLATFORMS)[number];
+/** process.platform → platforms 語彙。未知の OS は null (= ゲート対象外) */
+export declare function platformKeywordFor(p: NodeJS.Platform): PluginPlatform | null;
 /** params の1エントリ。GUI/ink がフォーム部品へ写像できる最小集合に絞る */
 export interface PluginParam {
     /** フラグ名 (例: "--bucket") */
@@ -23,6 +31,19 @@ export interface PluginParam {
     choices?: string[];
     default?: string | number | boolean;
     description?: string;
+    /** 機密値 (APIキー等)。GUI は伏字入力にし、値を表示・記録しない */
+    secret?: boolean;
+    /** フォーム表示名 (未設定 = name をそのまま表示) */
+    label?: string;
+    /** 入力欄のプレースホルダ */
+    placeholder?: string;
+    /** 属するサブコマンド (subcommands のいずれかの name)。未設定 = 全サブコマンド共通 */
+    subcommand?: string;
+}
+/** サブコマンドの宣言 (要望5)。params[].subcommand がここの name を参照する */
+export interface PluginSubcommand {
+    name: string;
+    description?: string;
 }
 /** --plugin-schema 応答の全体形 (基本 + 拡張。未知フィールドは無視) */
 export interface PluginDescribe {
@@ -35,6 +56,9 @@ export interface PluginDescribe {
     /** 発行する receipt の phase (SCHEMA.md §6) */
     phases?: string[];
     params?: PluginParam[];
+    /** 対応 OS。未宣言 = 制限なし。宣言があり現在の OS が含まれない場合、dispatch は実行を拒否する */
+    platforms?: PluginPlatform[];
+    subcommands?: PluginSubcommand[];
 }
 /**
  * plugin describe の表示行を組む。plugin/path は CLI が解決した事実 —
@@ -50,6 +74,17 @@ export declare function buildDescribeRow(resolvedPluginName: string, resolvedPat
  * 壊れた宣言の明示診断は plugin verify / plugin describe の仕事）。
  */
 export declare function probeDescribe(bin: string, timeoutMs?: number): Promise<PluginDescribe | null>;
+/**
+ * dispatch のプラットフォームゲート専用の寛容な platforms 読み取り。
+ * null = 「制限を確認できない」(schema 未対応・タイムアウト・壊れた応答・
+ * 語彙違反) — このとき呼び出し側は絶対にブロックしない (fail-open)。
+ * ゲートが信頼するのは完全に well-formed な宣言だけ: ["mac"] のような
+ * 語彙違反をそのまま返すと「現OSが含まれない」と誤読して typo した
+ * プラグインを遮断してしまう (codex P2)。意図的に validateDescribe は
+ * 通さない: 無関係な params の宣言ミスで日常の実行を止めない
+ * (壊れた宣言の明示診断は plugin verify / describe の仕事)。
+ */
+export declare function probePlatforms(bin: string, timeoutMs?: number): Promise<PluginPlatform[] | null>;
 /** 拡張フィールドのいずれかを宣言しているか */
 export declare function hasDescribeFields(row: Record<string, unknown>): boolean;
 /**

package/dist/plugins/describe.js

@@ -16,6 +16,21 @@
 import { execFile } from "node:child_process";
 import { tmpdir } from "node:os";
 import { buildPluginEnv, buildWindowsShimArgv } from "./dispatch.js";
+/**
+ * platforms の閉じた語彙。process.platform ではなく人間向けの名前で宣言する
+ * (シェルスクリプトのプラグイン作者が "darwin" を知っている必要はない)。
+ */
+export const KNOWN_PLATFORMS = ["macos", "linux", "windows"];
+/** process.platform → platforms 語彙。未知の OS は null (= ゲート対象外) */
+export function platformKeywordFor(p) {
+    if (p === "darwin")
+        return "macos";
+    if (p === "win32")
+        return "windows";
+    if (p === "linux")
+        return "linux";
+    return null;
+}
 const PARAM_TYPES = new Set(["string", "number", "boolean", "select"]);
 /**
  * plugin describe の表示行を組む。plugin/path は CLI が解決した事実 —
@@ -33,6 +48,16 @@ export function buildDescribeRow(resolvedPluginName, resolvedPath, declared) {
  * 壊れた宣言の明示診断は plugin verify / plugin describe の仕事）。
  */
 export function probeDescribe(bin, timeoutMs = 1500) {
+    return probeSchemaRow(bin, timeoutMs).then((row) => {
+        if (!row || !Array.isArray(row.pluginApi))
+            return null;
+        if (validateDescribe(row).length > 0)
+            return null;
+        return row;
+    });
+}
+/** --plugin-schema を1回だけ聞き、最初の JSON 行を返す (失敗/タイムアウト/非JSON = null) */
+function probeSchemaRow(bin, timeoutMs) {
     return new Promise((resolve) => {
         const isShim = process.platform === "win32" && /\.(cmd|bat)$/i.test(bin);
         const [cmd, args] = isShim
@@ -51,11 +76,9 @@ export function probeDescribe(bin, timeoutMs = 1500) {
                 return resolve(null);
             try {
                 const row = JSON.parse(stdout.trim().split("\n")[0]);
-                if (!Array.isArray(row.pluginApi))
-                    return resolve(null);
-                if (validateDescribe(row).length > 0)
-                    return resolve(null);
-                resolve(row);
+                resolve(row !== null && typeof row === "object" && !Array.isArray(row)
+                    ? row
+                    : null);
             }
             catch {
                 resolve(null);
@@ -63,9 +86,33 @@ export function probeDescribe(bin, timeoutMs = 1500) {
         });
     });
 }
+/**
+ * dispatch のプラットフォームゲート専用の寛容な platforms 読み取り。
+ * null = 「制限を確認できない」(schema 未対応・タイムアウト・壊れた応答・
+ * 語彙違反) — このとき呼び出し側は絶対にブロックしない (fail-open)。
+ * ゲートが信頼するのは完全に well-formed な宣言だけ: ["mac"] のような
+ * 語彙違反をそのまま返すと「現OSが含まれない」と誤読して typo した
+ * プラグインを遮断してしまう (codex P2)。意図的に validateDescribe は
+ * 通さない: 無関係な params の宣言ミスで日常の実行を止めない
+ * (壊れた宣言の明示診断は plugin verify / describe の仕事)。
+ */
+export async function probePlatforms(bin, timeoutMs = 1500) {
+    const row = await probeSchemaRow(bin, timeoutMs);
+    // schema 応答であることの確認 (copilot M1): pluginApi[] を欠く JSON は
+    // --plugin-schema への応答ではない — 偶然 platforms を含む別の出力で
+    // ゲートを作動させない
+    if (!row || !Array.isArray(row.pluginApi))
+        return null;
+    const p = row.platforms;
+    return Array.isArray(p) &&
+        p.length > 0 &&
+        p.every((v) => KNOWN_PLATFORMS.includes(v))
+        ? p
+        : null;
+}
 /** 拡張フィールドのいずれかを宣言しているか */
 export function hasDescribeFields(row) {
-    return ["name", "version", "description", "phases", "params"].some((k) => k in row);
+    return ["name", "version", "description", "phases", "params", "platforms", "subcommands"].some((k) => k in row);
 }
 /**
  * 宣言の形式検査。問題の説明文を返す (空配列 = 適合)。
@@ -84,6 +131,46 @@ export function validateDescribe(row) {
             problems.push("phases must be an array of strings");
         }
     }
+    if ("platforms" in row) {
+        // 閉じた語彙を強制する: "mac" や "darwin" のような typo を受理すると
+        // 実行ゲートに一度もマッチせず「宣言したのに効かない」沈黙の失敗になる。
+        // 空配列は「どこでも動かない」= 宣言ミス扱い。
+        const p = row.platforms;
+        if (!Array.isArray(p) ||
+            p.length === 0 ||
+            !p.every((v) => typeof v === "string" && KNOWN_PLATFORMS.includes(v))) {
+            problems.push(`platforms must be a non-empty array of ${KNOWN_PLATFORMS.map((k) => `"${k}"`).join(" | ")}`);
+        }
+    }
+    let declaredSubs = null;
+    if ("subcommands" in row) {
+        const subs = row.subcommands;
+        if (!Array.isArray(subs)) {
+            problems.push("subcommands must be an array");
+        }
+        else {
+            declaredSubs = new Set();
+            subs.forEach((entry, i) => {
+                if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+                    problems.push(`subcommands[${i}] must be an object`);
+                    return;
+                }
+                const s = entry;
+                if (typeof s.name !== "string" || s.name.length === 0) {
+                    problems.push(`subcommands[${i}].name must be a non-empty string`);
+                }
+                else if (declaredSubs.has(s.name)) {
+                    problems.push(`subcommands has duplicate name "${s.name}"`);
+                }
+                else {
+                    declaredSubs.add(s.name);
+                }
+                if ("description" in s && typeof s.description !== "string") {
+                    problems.push(`subcommands[${i}].description must be a string`);
+                }
+            });
+        }
+    }
     if ("params" in row) {
         const params = row.params;
         if (!Array.isArray(params)) {
@@ -137,6 +224,24 @@ export function validateDescribe(row) {
                 if ("description" in p && typeof p.description !== "string") {
                     problems.push(`params[${i}].description must be a string`);
                 }
+                if ("secret" in p && typeof p.secret !== "boolean") {
+                    problems.push(`params[${i}].secret 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`);
+                    }
+                }
+                if ("subcommand" in p) {
+                    if (typeof p.subcommand !== "string" || p.subcommand.length === 0) {
+                        problems.push(`params[${i}].subcommand must be a non-empty string`);
+                    }
+                    else if (declaredSubs !== null && !declaredSubs.has(p.subcommand)) {
+                        // subcommands 一覧を宣言した以上、参照は必ず解決すること —
+                        // 解決しない紐付けを通すと GUI がその項目をどの画面にも出せない
+                        problems.push(`params[${i}].subcommand "${p.subcommand}" is not in declared subcommands`);
+                    }
+                }
             });
         }
     }

package/dist/plugins/dispatch.js

@@ -256,6 +256,27 @@ export async function dispatchPlugin(name, args, ctx) {
     const bin = findPlugin(name);
     if (!bin)
         return null;
+    // プラットフォームゲート (PLUGINS.md §3): platforms を宣言したプラグインを
+    // 非対応 OS で実行しようとしたら、起動前に明確に拒否する (黙って壊れる
+    // より早い失敗)。宣言が「確認できた」ときのみ拒否し、schema 未対応・
+    // タイムアウト・壊れた応答では絶対にブロックしない (fail-open — 既存
+    // プラグインに退行経路を作らない)。メタデータ照会 (--plugin-schema /
+    // --plugin-healthcheck) はバイパス: GUI が platforms を知る手段そのもの
+    // であり、ここを塞ぐと非対応 OS から自己記述が読めなくなる。
+    const isMetadataProbe = args[0] === "--plugin-schema" || args[0] === "--plugin-healthcheck";
+    if (!isMetadataProbe) {
+        const { platformKeywordFor, probePlatforms } = await import("./describe.js");
+        const host = platformKeywordFor(process.platform);
+        if (host) {
+            const declared = await probePlatforms(bin);
+            if (declared && !declared.includes(host)) {
+                process.stderr.write(`Refusing to run plugin "${name}": it declares platforms ${JSON.stringify(declared)} ` +
+                    `and does not support ${host}.\n` +
+                    `See "i-repo plugin describe ${name}".\n`);
+                return 1;
+            }
+        }
+    }
     const env = buildPluginEnv(ctx);
     // Windows .cmd/.bat shims (e.g. npm-installed plugins) cannot be executed
     // directly by spawn() — Node requires cmd.exe for batch files. We invoke

package/dist/plugins/templates.js

@@ -20,11 +20,12 @@ set -eu
 case "\${1:-}" in
   --plugin-healthcheck)
     # TODO: check your sink's reachability here (no writes!)
-    printf '{"ok":true,"checks":[{"name":"ready","ok":true}]}\\n'
+    # severity: required | optional | required-for:<phase|subcommand>。hint は失敗時の対処メッセージ
+    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"],"params":[{"name":"--dry-run","type":"boolean","description":"Validate without writing"}]}\\n'
+    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"],"params":[{"name":"--dry-run","type":"boolean","label":"Dry run","description":"Validate without writing"}]}\\n'
     exit 0 ;;
 esac
 
@@ -99,7 +100,11 @@ const PLUGIN = "i-repo-${name}";
 const arg0 = process.argv[2];
 if (arg0 === "--plugin-healthcheck") {
   // TODO: check your sink's reachability here (no writes!)
-  console.log(JSON.stringify({ ok: true, checks: [{ name: "ready", ok: true }] }));
+  // severity: required | optional | required-for:<phase|subcommand>。hint は失敗時の対処メッセージ
+  console.log(JSON.stringify({
+    ok: true,
+    checks: [{ name: "ready", ok: true, severity: "required", hint: "TODO: how to fix when this fails" }],
+  }));
   process.exit(0);
 }
 if (arg0 === "--plugin-schema") {
@@ -109,8 +114,9 @@ if (arg0 === "--plugin-schema") {
     name: PLUGIN, version: "0.1.0",
     description: "TODO: what this plugin does",
     phases: ["write", "verify"],
+    platforms: ["macos", "linux", "windows"],
     params: [
-      { name: "--dry-run", type: "boolean", description: "Validate without writing" },
+      { name: "--dry-run", type: "boolean", label: "Dry run", description: "Validate without writing" },
     ],
   }));
   process.exit(0);

package/dist/plugins/verify.d.ts

@@ -23,6 +23,13 @@ export declare function parseLines(stdout: string): {
     rows: Record<string, unknown>[];
     invalid: string[];
 };
+/**
+ * healthcheck 応答の checks[] の形式検査 (PLUGINS.md §3)。
+ * 各 entry は {name: string, ok: boolean, severity?, hint?}。severity は
+ * "required" | "optional" | "required-for:<phase|subcommand>"、未設定の既定は
+ * "required" (現行挙動と同じ保守側)。未知の追加フィールドは無視する。
+ */
+export declare function validateHealthChecks(value: unknown): string[];
 /**
  * Run all conformance checks against plugin `name`.
  * Returns null when the plugin is not installed.

package/dist/plugins/verify.js

@@ -16,7 +16,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { buildEnvelope, buildStreamEnd } from "../ui/formatters/envelope.js";
 import { buildPluginEnv, buildWindowsShimArgv, findPlugin } from "./dispatch.js";
-import { hasDescribeFields, validateDescribe } from "./describe.js";
+import { KNOWN_PLATFORMS, hasDescribeFields, platformKeywordFor, validateDescribe, } from "./describe.js";
 /** Sample envelope stream (3 records + stream-end), generated from the real implementation. */
 export function sampleStream() {
     const spec = { recordType: "report", idField: "itemId", revField: "revNo" };
@@ -93,6 +93,40 @@ export function parseLines(stdout) {
     }
     return { rows, invalid };
 }
+// required-for: の後は単一の非空白トークン (phase / subcommand 名)。
+// 空白入りを許すと severity を単一トークンとしてパースする消費側が壊れる
+const SEVERITY_RE = /^(required|optional|required-for:\S+)$/;
+/**
+ * healthcheck 応答の checks[] の形式検査 (PLUGINS.md §3)。
+ * 各 entry は {name: string, ok: boolean, severity?, hint?}。severity は
+ * "required" | "optional" | "required-for:<phase|subcommand>"、未設定の既定は
+ * "required" (現行挙動と同じ保守側)。未知の追加フィールドは無視する。
+ */
+export function validateHealthChecks(value) {
+    const problems = [];
+    if (!Array.isArray(value))
+        return ["checks must be an array"];
+    value.forEach((entry, i) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            problems.push(`checks[${i}] must be an object`);
+            return;
+        }
+        const c = entry;
+        if (typeof c.name !== "string" || c.name.length === 0) {
+            problems.push(`checks[${i}].name must be a non-empty string`);
+        }
+        if (typeof c.ok !== "boolean") {
+            problems.push(`checks[${i}].ok must be a boolean`);
+        }
+        if ("severity" in c && (typeof c.severity !== "string" || !SEVERITY_RE.test(c.severity))) {
+            problems.push(`checks[${i}].severity must be "required" | "optional" | "required-for:<phase|subcommand>"`);
+        }
+        if ("hint" in c && typeof c.hint !== "string") {
+            problems.push(`checks[${i}].hint must be a string`);
+        }
+    });
+    return problems;
+}
 const RECEIPT_REQUIRED = [
     "schemaVersion",
     "recordType",
@@ -140,6 +174,27 @@ export function verifyPlugin(name) {
                         ? "self-description fields are well-formed"
                         : problems[0],
                 });
+                // platforms 宣言と現在の OS の照合は警告のみ — 他 OS 向けプラグインを
+                // ビルドマシンで verify するのは正当 (語彙の誤りは describe-shape が
+                // required 違反として捕捉済み)。実行ゲートは dispatch 側。
+                // well-formed な宣言のみ報告する (copilot M2): 語彙違反/空配列では
+                // dispatch は fail-open で拒否しないため、「dispatch will refuse」の
+                // note が嘘になる (壊れた宣言自体は上の describe-shape が required 違反)
+                const platforms = rows[0].platforms;
+                const host = platformKeywordFor(process.platform);
+                if (Array.isArray(platforms) &&
+                    platforms.length > 0 &&
+                    platforms.every((v) => KNOWN_PLATFORMS.includes(v))) {
+                    const supported = host === null || platforms.includes(host);
+                    checks.push({
+                        check: "platform-support",
+                        ok: supported,
+                        required: false,
+                        note: supported
+                            ? `declares platforms ${JSON.stringify(platforms)}; current OS (${host ?? "unknown"}) is supported`
+                            : `declares platforms ${JSON.stringify(platforms)}; current OS is ${host} — dispatch will refuse to run it here`,
+                    });
+                }
             }
         }
         else {
@@ -155,14 +210,36 @@ export function verifyPlugin(name) {
         if (health.status === 0 || health.status === 1) {
             const { rows, invalid } = parseLines(health.stdout);
             const ok = invalid.length === 0 && rows.length === 1 && typeof rows[0]?.ok === "boolean";
+            // ok:false の応答に hint 付きの失敗 check があれば note に併記する —
+            // 「不健康」とだけ言われても直せない。hint が対処メッセージの契約面。
+            let detail = "";
+            if (ok && rows[0].ok === false && Array.isArray(rows[0].checks)) {
+                const failing = rows[0].checks.find((c) => c !== null && typeof c === "object" &&
+                    c.ok === false &&
+                    typeof c.hint === "string");
+                if (failing)
+                    detail = ` — hint: ${String(failing.hint)}`;
+            }
             checks.push({
                 check: "plugin-healthcheck",
                 ok,
                 required: false,
                 note: ok
-                    ? `answered ok=${rows[0].ok} (exit ${health.status})`
+                    ? `answered ok=${rows[0].ok} (exit ${health.status})${detail}`
                     : "exited 0/1 but did not print a single {ok:boolean} JSON line",
             });
+            // checks[] は任意だが、宣言した以上は正しい形であること (describe-shape
+            // と同じ理屈): {name, ok, severity?, hint?}。壊れた checks を黙って通すと
+            // それを信じた GUI の充足判定が壊れる。
+            if (ok && "checks" in rows[0]) {
+                const problems = validateHealthChecks(rows[0].checks);
+                checks.push({
+                    check: "healthcheck-shape",
+                    ok: problems.length === 0,
+                    required: true,
+                    note: problems.length === 0 ? "healthcheck checks[] entries are well-formed" : problems[0],
+                });
+            }
         }
         else {
             checks.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i-repo",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Modern CLI for ConMas i-Reporter - Built for humans and AI",
   "type": "module",
   "bin": {
@@ -62,9 +62,9 @@
   "devDependencies": {
     "@types/gradient-string": "1.1.6",
     "@types/node": "24.13.0",
-    "@types/react": "19.2.16",
+    "@types/react": "19.2.17",
     "typescript": "5.9.3",
-    "vitest": "4.1.7"
+    "vitest": "4.1.8"
   },
   "overrides": {
     "ws": "8.21.0"