i-repo 2.4.0 → 2.6.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/commands/reports/download.js

@@ -1,5 +1,5 @@
-import { assertNumericId, handleError } from "../../core/errors.js";
-import { saveBinaryDownload, inferFilename } from "../../utils/file.js";
+import { assertNumericId, handleError, ValidationError } from "../../core/errors.js";
+import { saveBinaryDownload, inferFilename, sanitizeServerFilename } from "../../utils/file.js";
 import { withSpinner } from "../../ui/spinner.js";
 import { choiceOption, parsePageSpec } from "../shared-options.js";
 export function registerReportsDownload(parent, getClient) {
@@ -8,12 +8,19 @@ export function registerReportsDownload(parent, getClient) {
         .description("Download report file (PDF/Excel)")
         .argument("<reportId>", "Report ID (numeric)")
         .addOption(choiceOption("--file-type <type>", "File type", ["pdf", "pdfLayer", "excel"]).makeOptionMandatory())
-        .option("-o, --output <path>", "Output file path")
+        .option("-o, --output <path>", "Output file path (default: server-provided filename, else report-<id>)")
         .option("--page <pages>", 'Pages (pdf/pdfLayer only; e.g. "1,3" or "2-4")', parsePageSpec)
-        .option("--file-name <name>", "Output file name")
+        .option("--file-name <name>", "Output file name (also sent to the server's fileName parameter)")
         .action(async (reportId, options, cmd) => {
         try {
             assertNumericId(reportId, "reportId");
+            // --file-name は「ファイル名」専用 — パスは -o/--output の仕事。
+            // 空白のみ (→ 隠しファイル ".pdf") やパス区切り入りは黙って変形せず
+            // ここで明示的に拒否する (API 呼び出し前に早期失敗)。
+            const requestedName = options.fileName?.trim();
+            if (requestedName !== undefined && (requestedName === "" || /[/\\]/.test(requestedName))) {
+                throw new ValidationError(`Invalid --file-name "${options.fileName}": must be a plain file name without path separators (use --output for paths).`);
+            }
             const globalOpts = cmd.optsWithGlobals();
             const client = await getClient(cmd);
             const result = await withSpinner("downloading", async () => {
@@ -21,11 +28,29 @@ export function registerReportsDownload(parent, getClient) {
                     fileType: options.fileType,
                     report: reportId,
                     pageNo: options.page,
-                    fileName: options.fileName,
+                    fileName: requestedName,
                 });
             });
             const ext = options.fileType === "excel" ? "xlsx" : "pdf";
-            const defaultName = `report-${reportId}.${ext}`;
+            // 保存名の優先順位: -o/--output (パスごと明示) ＞ --file-name (明示) ＞
+            // サーバ申告名 (Content-Disposition = ファイル自動出力設定の名称) ＞
+            // 従来の report-<ID>.<ext>。ユーザーの明示指定は、サーバが fileName
+            // パラメータを無視/正規化して別名を申告してきても負けない。
+            // --file-name / サーバ名とも、拡張子付きならそのまま・無ければ .<ext>
+            // を補う ("foo.pdf" を "foo.pdf.pdf" にしない。--file-type で拡張子は
+            // 確定しているので、octet-stream 応答でも拡張子なし保存にしない)。
+            // サーバ名は無害化してから使う。
+            // 末尾のドット/空白は Windows のファイルシステムが黙って剥がす — 先に
+            // 剥がしてから拡張子判定する ("foo." / "foo.pdf " を誤判定して、要求と
+            // 違う名前でディスクに載るのを防ぐ。"foo." → "foo.pdf")
+            const withExt = (name) => {
+                const base = name.replace(/[. ]+$/, "");
+                return base.lastIndexOf(".") > 0 ? base : `${base}.${ext}`;
+            };
+            const serverBase = sanitizeServerFilename(result.fileName);
+            const serverName = serverBase ? withExt(serverBase) : undefined;
+            const explicitName = requestedName ? withExt(requestedName) : undefined;
+            const defaultName = explicitName ?? serverName ?? `report-${reportId}.${ext}`;
             const filename = inferFilename(result.contentType, defaultName);
             await saveBinaryDownload(result, options.output, filename, globalOpts.quiet);
         }

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/dist/sdk/api/report.d.ts

@@ -53,11 +53,13 @@ export declare class ReportApi extends BaseApi {
     copyReport(params: CopyReportParams): Promise<CopyReportResponse>;
     /**
      * 帳票ファイル (PDF/Excel) をバイナリとして取得する
-     * @returns バイナリデータとContentType
+     * @returns バイナリデータとContentType。fileName はサーバが Content-Disposition で
+     *          申告した出力名（ファイル自動出力設定の名称。無ければ undefined）
      */
     getReportFile(params: GetReportFileParams): Promise<{
         data: ArrayBuffer;
         contentType: string;
+        fileName?: string;
     }>;
     /**
      * クラスター値を取得する。

package/dist/sdk/api/report.js

@@ -132,7 +132,8 @@ export class ReportApi extends BaseApi {
     }
     /**
      * 帳票ファイル (PDF/Excel) をバイナリとして取得する
-     * @returns バイナリデータとContentType
+     * @returns バイナリデータとContentType。fileName はサーバが Content-Disposition で
+     *          申告した出力名（ファイル自動出力設定の名称。無ければ undefined）
      */
     async getReportFile(params) {
         const reqParams = buildParams({ command: "GetReportFile", fileType: params.fileType }, {

package/dist/sdk/core/base-api.d.ts

@@ -18,6 +18,7 @@ export declare abstract class BaseApi {
     protected executeForBinary(params: Record<string, string>): Promise<{
         data: ArrayBuffer;
         contentType: string;
+        fileName?: string;
     }>;
     /**
      * クラスタ値取得用。XMLレスポンスで `conmas.value` があればテキスト値を

package/dist/sdk/core/base-api.js

@@ -58,7 +58,7 @@ export class BaseApi {
         }
         // Content-Type が xml でなくても、本文が XML エラーなら沈黙保存させない
         this.checkBinaryErrorEnvelope(result.data, params.command);
-        return { data: result.data, contentType: result.contentType };
+        return { data: result.data, contentType: result.contentType, fileName: result.fileName };
     }
     /**
      * クラスタ値取得用。XMLレスポンスで `conmas.value` があればテキスト値を

package/dist/sdk/core/http-client.d.ts

@@ -1,4 +1,18 @@
 import type { IReporterConfig } from "../types/common.js";
+/** バイナリ応答。fileName は Content-Disposition から得たサーバ提供名 (無ければ undefined) */
+export interface BinaryResponse {
+    data: ArrayBuffer;
+    contentType: string;
+    fileName?: string;
+}
+/**
+ * Content-Disposition からファイル名を取り出す (RFC 6266)。
+ * `filename*=charset''pct-encoded` (RFC 5987) を優先し、無ければ
+ * `filename="..."` / `filename=token`。パースできない・壊れた値は undefined —
+ * 呼び出し側がフォールバック名を使う。値はサーバ申告のまま返す (パス区切り等の
+ * 無害化は保存する側の責務 — SDK はワイヤ忠実)。
+ */
+export declare function parseContentDispositionFilename(header: string | null | undefined): string | undefined;
 /** HTTPクライアント: セッション（Cookie）管理 + POSTリクエスト */
 export declare class HttpClient {
     private readonly baseUrl;
@@ -41,19 +55,14 @@ export declare class HttpClient {
         filename: string;
     }): Promise<string>;
     /** バイナリレスポンスでPOSTリクエスト（ダウンロード用）。画像等を破損させないため arraybuffer で受信 */
-    postForBinary(params: Record<string, string>): Promise<{
-        data: ArrayBuffer;
-        contentType: string;
-    }>;
+    postForBinary(params: Record<string, string>): Promise<BinaryResponse>;
     /** レスポンスがXMLかどうかを判定してXML/バイナリを返す。画像等は arraybuffer で取得するため専用経路を使用 */
     postAutoDetect(params: Record<string, string>): Promise<{
         type: "xml";
         xml: string;
-    } | {
+    } | ({
         type: "binary";
-        data: ArrayBuffer;
-        contentType: string;
-    }>;
+    } & BinaryResponse)>;
     /** multipart/form-data でPOSTし、Content-Typeを判定してXML/バイナリを返す */
     postMultipartForBinary(params: Record<string, string>, file: {
         name: string;

package/dist/sdk/core/http-client.js

@@ -2,6 +2,39 @@ import http from "node:http";
 import https from "node:https";
 import { URL } from "node:url";
 import { HttpError, NetworkError } from "./errors.js";
+/**
+ * Content-Disposition からファイル名を取り出す (RFC 6266)。
+ * `filename*=charset''pct-encoded` (RFC 5987) を優先し、無ければ
+ * `filename="..."` / `filename=token`。パースできない・壊れた値は undefined —
+ * 呼び出し側がフォールバック名を使う。値はサーバ申告のまま返す (パス区切り等の
+ * 無害化は保存する側の責務 — SDK はワイヤ忠実)。
+ */
+export function parseContentDispositionFilename(header) {
+    if (!header)
+        return undefined;
+    // パラメータ名と charset は大文字小文字を区別しない (RFC 6266/5987 — copilot 指摘)
+    // filename*=UTF-8''%E5%B8%B3%E7%A5%A8.pdf (charset は UTF-8 のみ対応)
+    const ext = /filename\*\s*=\s*utf-8''([^;]+)/i.exec(header);
+    if (ext) {
+        try {
+            const decoded = decodeURIComponent(ext[1].trim());
+            if (decoded.length > 0)
+                return decoded;
+        }
+        catch {
+            // 壊れた % エンコード → 素の filename= にフォールバック
+        }
+    }
+    const quoted = /filename\s*=\s*"((?:[^"\\]|\\.)*)"/i.exec(header);
+    if (quoted) {
+        const unescaped = quoted[1].replace(/\\(.)/g, "$1");
+        return unescaped.length > 0 ? unescaped : undefined;
+    }
+    const token = /filename\s*=\s*([^;\s]+)/i.exec(header);
+    if (token && token[1].length > 0)
+        return token[1];
+    return undefined;
+}
 /** HTTPクライアント: セッション（Cookie）管理 + POSTリクエスト */
 export class HttpClient {
     baseUrl;
@@ -142,13 +175,13 @@ export class HttpClient {
     }
     /** レスポンスがXMLかどうかを判定してXML/バイナリを返す。画像等は arraybuffer で取得するため専用経路を使用 */
     async postAutoDetect(params) {
-        const { data, contentType } = await this.postForBinary(params);
+        const { data, contentType, fileName } = await this.postForBinary(params);
         const rawContentType = contentType ?? "";
         if (rawContentType.includes("xml") && !isZipMagic(data)) {
             const xml = new TextDecoder("utf-8").decode(data);
             return { type: "xml", xml };
         }
-        return { type: "binary", data, contentType: rawContentType };
+        return { type: "binary", data, contentType: rawContentType, fileName };
     }
     /** multipart/form-data でPOSTし、Content-Typeを判定してXML/バイナリを返す */
     async postMultipartForBinary(params, file) {
@@ -206,6 +239,7 @@ export class HttpClient {
         return {
             data: await this.readArrayBuffer(response),
             contentType: response.headers.get("content-type") ?? "application/octet-stream",
+            fileName: parseContentDispositionFilename(response.headers.get("content-disposition")),
         };
     }
     /** Node `http`/`https` で URL-encoded を送る（ASP.NET と相性が良い） */
@@ -228,6 +262,7 @@ export class HttpClient {
         return {
             data: u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength),
             contentType,
+            fileName: parseContentDispositionFilename(getIncomingHeader(headers, "content-disposition")),
         };
     }
     async nodePostUrlEncoded(startUrl, bodyString) {

package/dist/sdk/resources/reports.d.ts

@@ -24,6 +24,7 @@ export declare class ReportsResource {
     downloadFile(params: GetReportFileParams): Promise<{
         data: ArrayBuffer;
         contentType: string;
+        fileName?: string;
     }>;
     getClusterValue(params: GetClusterValueParams): Promise<{
         data: ArrayBuffer;

package/dist/utils/file.d.ts

@@ -27,6 +27,15 @@ export declare function saveBinaryDownload(result: {
     data: ArrayBuffer;
     contentType: string;
 }, outputPath: string | undefined, defaultFilename: string, quiet?: boolean): Promise<DownloadResult>;
+/**
+ * サーバ申告のダウンロードファイル名 (Content-Disposition) を保存に安全な
+ * 単一ファイル名へ無害化する。サーバ (または途中の何か) が "../../evil.pdf" や
+ * 制御文字入りの名前を申告しても、保存先ディレクトリの外へ書かせない。
+ * 日本語等の Unicode は保持する (帳票名がそのまま使えることが目的)。
+ * 無害化の結果ファイル名として成立しない場合は undefined — 呼び出し側が
+ * フォールバック名を使う。
+ */
+export declare function sanitizeServerFilename(name: string | undefined): string | undefined;
 /**
  * Infer a filename from content-type header.
  * Falls back to the provided default.

package/dist/utils/file.js

@@ -109,6 +109,34 @@ export async function saveBinaryDownload(result, outputPath, defaultFilename, qu
         size: buffer.byteLength,
     };
 }
+/**
+ * サーバ申告のダウンロードファイル名 (Content-Disposition) を保存に安全な
+ * 単一ファイル名へ無害化する。サーバ (または途中の何か) が "../../evil.pdf" や
+ * 制御文字入りの名前を申告しても、保存先ディレクトリの外へ書かせない。
+ * 日本語等の Unicode は保持する (帳票名がそのまま使えることが目的)。
+ * 無害化の結果ファイル名として成立しない場合は undefined — 呼び出し側が
+ * フォールバック名を使う。
+ */
+export function sanitizeServerFilename(name) {
+    if (!name)
+        return undefined;
+    // パス区切りを越えさせない: 最後のセグメントだけを採用 (\ は Windows 区切り)
+    const lastSegment = name.split(/[/\\]/).pop() ?? "";
+    const cleaned = lastSegment
+        .replace(/[\u0000-\u001f\u007f]/g, "") // 制御文字 (端末・FS 両方に有害)
+        .replace(/[<>:"|?*]/g, "_") // Windows で使えない文字
+        .trim()
+        // Windows は末尾のドット/空白を黙って剥がす — 先にこちらで剥がして
+        // 「指定と違う名前で保存される」を起こさない (copilot 指摘)
+        .replace(/[. ]+$/, "");
+    if (cleaned === "")
+        return undefined;
+    // Windows 予約デバイス名 (NUL / CON.pdf 等) はどの OS でも採用しない —
+    // 保存物が後で Windows に渡ったとき開けない名前を作らない (可搬性)
+    if (isWindowsReservedName(cleaned))
+        return undefined;
+    return cleaned;
+}
 /**
  * Infer a filename from content-type header.
  * Falls back to the provided default.

package/package.json

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