@pecot/tools-mcp 1.0.1 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pecot-t",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "pecot-t（pecot-tools）— 許可リストで限定した CLI コマンドを MCP ツールとして提供するプラグイン",
   "author": {
     "name": "pecot"

package/cli/dist/cli.d.ts

@@ -1,8 +1,7 @@
 import { Command } from 'commander';
 export declare function createProgram(): Command;
 /**
-commander の既定である process.exit() 直呼びを止め、例外へ振り替える。
-サブコマンドを足したときに取りこぼさないよう再帰で適用する。
+commander の process.exit() 直呼びを止め、例外へ振り替える。再帰で全サブコマンドに適用する
 */
 export declare function applyExitOverrideRecursively(command: Command): void;
 export declare function main(nodeVersion?: string): void;

package/cli/dist/cli.js

@@ -1,19 +1,17 @@
-// pecot-tools CLI のエントリポイント。MCP サーバの起動 (`mcp`) だけを持つ薄い Command で、
-// MCP SDK の読み込みは action 内の dynamic import に閉じる。
+// pecot-tools CLI のエントリポイント。MCP SDK は action 内の dynamic import に閉じる。
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { Command, CommanderError } from 'commander';
-import { checkNodeRuntime } from './node-runtime.js';
+import { createDiagnostics } from './diagnostics.js';
+import { nodeRuntimeGuidance } from './node-runtime.js';
 import { readVersion } from './version.js';
 export function createProgram() {
     const program = new Command();
     program.name('pecot-tools').version(readVersion());
     const mcp = program
         .command('mcp')
-        .description('MCP サーバとして stdio (stdin/stdout) で待ち受ける');
-    /* c8 ignore start -- action は dynamic import して実 process.stdin/stdout へ接続する。
-       単体テストから起動すると vitest worker の stdout ごと差し替えてしまう。
-       tests/e2e/mcp-stdio.test.ts が実プロセスの spawn で担保する。 */
+        .description('Serve as an MCP server over stdio (stdin/stdout)');
+    /* c8 ignore start -- 実 stdin/stdout へ接続する。tests/e2e/mcp-stdio.test.ts が担保 */
     mcp.action(async () => {
         const { executeMcpServe, mcpServeDefaultDependencies } = await import('./mcp/serve.js');
         executeMcpServe(mcpServeDefaultDependencies);
@@ -22,8 +20,7 @@ export function createProgram() {
     return program;
 }
 /**
-commander の既定である process.exit() 直呼びを止め、例外へ振り替える。
-サブコマンドを足したときに取りこぼさないよう再帰で適用する。
+commander の process.exit() 直呼びを止め、例外へ振り替える。再帰で全サブコマンドに適用する
 */
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- exitOverride() で変更する
 export function applyExitOverrideRecursively(command) {
@@ -32,9 +29,9 @@ export function applyExitOverrideRecursively(command) {
         applyExitOverrideRecursively(child);
 }
 export function main(nodeVersion = process.versions.node) {
-    const runtimeError = checkNodeRuntime(nodeVersion);
+    const runtimeError = nodeRuntimeGuidance(nodeVersion);
     if (runtimeError !== undefined) {
-        process.stderr.write(`pecot-tools: ${runtimeError}\n`);
+        createDiagnostics(process.stderr).error(runtimeError);
         process.exitCode = 1;
         return;
     }
@@ -53,8 +50,7 @@ export function main(nodeVersion = process.versions.node) {
 }
 /* v8 ignore start -- 直接起動時にだけ通る。挙動は tests/e2e/version.test.ts で担保 */
 if (process.argv[1] !== undefined) {
-    // import.meta.url は symlink を解決した実体パスを指すため、argv[1] 側も realpath に揃える。
-    // 揃えないと bin ラッパー等の symlink 経由起動で一致せず、何もせず exit 0 で終わる。
+    // import.meta.url は実体パスなので argv[1] も realpath に揃える。symlink 経由起動で一致しなくなるため。
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- 起動された自分自身のパス
     const selfUrl = pathToFileURL(realpathSync(process.argv[1])).href;
     if (import.meta.url === selfUrl) {

package/cli/dist/diagnostics.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export interface DiagnosticStream {
+    write(text: string): unknown;
+}
+/**
+done の動詞。自由な文字列を受け取らない
+*/
+export declare const DiagnosticVerbSchema: z.ZodEnum<{
+    add: "add";
+    create: "create";
+}>;
+export type DiagnosticVerb = z.infer<typeof DiagnosticVerbSchema>;
+export interface DiagnosticOperation {
+    readonly verb: DiagnosticVerb;
+    readonly target: string;
+}
+export interface Diagnostics {
+    readonly error: (message: string) => void;
+    readonly warning: (message: string) => void;
+    /**
+    情報の診断だけに使う。進捗の行には使わない
+    */
+    readonly note: (message: string) => void;
+    /**
+    実行した操作を `<過去分詞>: <target>` で出す
+    */
+    readonly done: (operation: DiagnosticOperation) => void;
+}
+export declare function createDiagnostics(stderr: DiagnosticStream): Diagnostics;
+/**
+結果の本体を stdout にそのまま出す。末尾に改行が無ければ 1 つ足す
+*/
+export declare function writeData(stdout: DiagnosticStream, text: string): void;
+/**
+commander が組み立てた使い方エラー・ヘルプの枠を、手を加えずに書く。commander が `error: ` を付ける
+*/
+export declare function passthrough(stream: DiagnosticStream, text: string): void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/cli/dist/diagnostics.js

@@ -0,0 +1,46 @@
+// stderr の診断行と stdout のデータを書く、唯一の場所。
+// 行の形は specs/021-cli-output-functions/contracts/output-lines.md が決める。
+// 期待の行は tests/diagnostics-cases.json に置く。
+import { z } from 'zod';
+/**
+done の動詞。自由な文字列を受け取らない
+*/
+export const DiagnosticVerbSchema = z.enum(['create', 'add']);
+function pastOf(verb) {
+    switch (verb) {
+        case 'create': {
+            return 'created';
+        }
+        case 'add': {
+            return 'added';
+        }
+    }
+}
+/**
+末尾の改行を取り除き、2 行目以降の先頭に空白 2 つを付け、末尾に改行を 1 つ付ける
+*/
+function formatMessage(prefix, message) {
+    const lines = message.replace(/\n+$/, '').split('\n');
+    return `${prefix}: ${lines.join('\n  ')}\n`;
+}
+export function createDiagnostics(stderr) {
+    return {
+        error: (message) => { stderr.write(formatMessage('error', message)); },
+        warning: (message) => { stderr.write(formatMessage('warning', message)); },
+        note: (message) => { stderr.write(formatMessage('note', message)); },
+        done: ({ verb, target }) => { stderr.write(`${pastOf(verb)}: ${target}\n`); },
+    };
+}
+/**
+結果の本体を stdout にそのまま出す。末尾に改行が無ければ 1 つ足す
+*/
+export function writeData(stdout, text) {
+    stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+}
+/**
+commander が組み立てた使い方エラー・ヘルプの枠を、手を加えずに書く。commander が `error: ` を付ける
+*/
+export function passthrough(stream, text) {
+    stream.write(text);
+}
+//# sourceMappingURL=diagnostics.js.map

package/cli/dist/domain/arguments.d.ts

@@ -14,24 +14,11 @@ export interface CommonOptions {
     readonly region?: string;
 }
 /**
-入力を検証する。問題があれば invalid-input を、無ければ undefined を返す。
-
-profile / region も同じ処理で検証する（別扱いにすると書式検証が抜ける）。
+入力を検証する。問題があれば invalid-input を、無ければ undefined を返す。profile / region も同じ処理で検証する。
 */
 export declare function validateInput(entry: Readonly<AllowlistEntry>, input: Readonly<Record<string, unknown>>): InvalidInput | undefined;
 /**
-awscli へ渡す引数配列を組み立てる。
-
-並びは `<service> <subcommand> <位置引数…> <フラグ…> --output json --no-cli-pager
---profile <p> --region <r>`。位置引数を先・フラグを後に置くと、string-list（nargs が貪欲）と
-位置引数が同居しても awscli v2 の argparse が取り違えない（動作確認済み）。
-
-`--no-cli-pager` は jsonOutput の有無に依らず常に付ける（非 tty では無害で、分岐を持たない方が単純）。
-
-`--profile` / `--region` は末尾で 1 度だけ付ける。エントリ側が inputs に同名を宣言していても
-フラグ列挙では飛ばす。
-
-値が '-' で始まる string は `--flag=value` の 1 トークンにする（flagTokens）。
+awscli へ渡す引数配列を組み立てる。位置引数を先・フラグを後に置くと、nargs が貪欲な string-list と同居しても取り違えない。
 */
 export declare function buildArguments(entry: Readonly<AllowlistEntry>, input: Readonly<Record<string, unknown>>, common?: Readonly<CommonOptions>): string[];
 //# sourceMappingURL=arguments.d.ts.map

package/cli/dist/domain/arguments.js

@@ -1,29 +1,13 @@
 // 入力の検証と awscli 引数配列の組み立て。
-//
-// shell を介さず spawn するため、利用者の値は必ず 1 要素 1 値で配列へ入れる。
-// 値が '-' で始まると awscli の引数解析でオプションと解釈され得るので、原則として先頭 '-' を
-// 拒否する（research R3）。例外はフラグで渡す 1 値の string だけで、こちらは
-// `--flag=value` の 1 トークン形にして渡す（doesAllowLeadingDash / flagTokens）。
-//
-// shorthand-list（`--dimensions` / `--filters` / `--image-ids`）は JSON.stringify で 1 トークンに
-// する。awscli はこれらのフラグを shorthand と JSON の双方で受ける。
-// JSON を選べば区切り文字の解釈がエスケープに閉じ、利用者の値が構文へ漏れる余地が無くなる（`,` を含むタグ値も渡せる）。
+// 先頭 '-' の値は原則拒否し、例外の string は `--flag=value` の 1 トークンで渡す（research R3）。
 import { PROFILE_INPUT, REGION_INPUT } from './allowlist.js';
 import { validateLocalPath, validateS3ListUri, validateS3Uri } from './s3-input.js';
 /**
-shorthand の構成要素の値に混入すると構文として解釈される文字。
-
-awscli の shorthand は `Key=value,Key=value` の書式。
-構成要素の値に `,` や `=` を含めると、契約に無いキー（`ExpectedBucketOwner` 等）を後ろに足せる。
-実 awscli が受理することを動作確認済みなので、組み立て前に弾く。対象は文字列を連結する `shorthand`（Athena / ECR の
-`--filter`）だけで、JSON で組み立てる `shorthand-list` には要らない。
+shorthand の値に混入すると構文になる文字。`,` や `=` で契約外のキーを足せるため、組み立て前に弾く。
 */
 const SHORTHAND_SYNTAX = /[,={}]/;
 /**
-制御文字（U+0000〜U+001F と U+007F）を含むか。
-
-argv に NUL を載せると spawn が同期 throw し、ExecutionResult を伴わない応答になる。
-他の制御文字も awscli の解釈が値ごとに変わるため、検証の段階で invalid-input にする。
+制御文字（U+0000〜U+001F と U+007F）を含むか。NUL は spawn が同期 throw するため、検証で弾く。
 */
 function hasControlCharacter(text) {
     for (const character of text) {
@@ -34,10 +18,7 @@ function hasControlCharacter(text) {
     return false;
 }
 /**
-共通入力として末尾で付与するフラグ。
-
-エントリ側が同じフラグを inputs に宣言していても、付与箇所は末尾の 1 本に絞る
-（フラグ列挙でも出すと `--profile x --profile x` が並ぶ）。
+共通入力として末尾で付与するフラグ。inputs 側の宣言と重複して並ばないよう、付与は末尾の 1 本に絞る。
 */
 const COMMON_FLAGS = new Set([PROFILE_INPUT.awsFlag, REGION_INPUT.awsFlag].filter(flag => flag !== undefined));
 /**
@@ -108,17 +89,7 @@ function kindPredicate(kind, value) {
     }
 }
 /**
-値の先頭 '-' を許す入力か。
-
-対象はフラグで渡す `kind: 'string'` の 1 値だけ。CloudWatch Logs の除外パターン（`-INFO`）の
-ように、先頭 '-' に意味を持つ値が実在する。
-実 awscli 2.36.40 では `--filter-pattern=-INFO` が受理される（`--filter-pattern -INFO` は 252）。組み立ては buildArguments が
-`--flag=value` の 1 トークン形で行うため、オプション注入にはならない。
-
-string-list は nargs が貪欲で、1 トークン形へ畳めない。
-位置引数には `--flag=value` の逃がし先が無い。
-そのため、いずれも従来どおり拒否する（enum は許容値が許可リストの静的宣言なので、
-そもそも利用者の値が本判定に届かない）。
+値の先頭 '-' を許す入力か。対象はフラグで渡す string の 1 値だけで、`--flag=value` の 1 トークンで組み立てる。
 */
 function doesAllowLeadingDash(spec) {
     return spec.kind === 'string' && spec.awsFlag !== undefined && spec.positional === undefined;
@@ -128,65 +99,55 @@ string 系 1 値の検証。制御文字・先頭 '-' 拒否と kind 固有の
 */
 function validateStringValue(spec, value) {
     if (hasControlCharacter(value)) {
-        return invalid(`${spec.name} は制御文字を含まない値で指定してください`);
+        return invalid(`${spec.name} must not contain control characters`);
     }
     if (value.startsWith('-') && !doesAllowLeadingDash(spec)) {
-        return invalid(`${spec.name} の値は '-' で始められません: ${value}`);
+        return invalid(`${spec.name} must not start with '-': ${value}`);
     }
     const predicate = kindPredicate(spec.kind, value);
     if (predicate !== undefined) {
         return invalid(`${spec.name} ${predicate}: ${value}`);
     }
     if (spec.pattern !== undefined && !spec.pattern.test(value)) {
-        return invalid(`${spec.name} の形式が不正です: ${value}`);
+        return invalid(`${spec.name} has an invalid format: ${value}`);
     }
     return undefined;
 }
 /**
-shorthand の構成要素として載る値を検証する。
-
-shorthand 自身は入力レコードから読まない（利用者は指定できない）。見るのは構成要素の
-取得元入力の値だけで、取得元自体の型・書式は通常の入力として別途検証されている。
+shorthand の構成要素の値を検証する。shorthand 自身は読まず、取得元入力の値だけを見る。
 */
 function validateShorthandParts(spec, input) {
     const declaredParts = spec.parts ?? [];
     for (const part of declaredParts) {
         const value = readInput(input, part.from);
         if (typeof value === 'string' && SHORTHAND_SYNTAX.test(value)) {
-            return invalid(`${part.from} に , = { } は含められません: ${value}`);
+            return invalid(`${part.from} must not contain , = { }: ${value}`);
         }
     }
     return undefined;
 }
 /**
-shorthand-list の構成要素の値 1 つずつを検証する。
-
-区切り文字（`, = { }`）は見ない。組み立てが JSON.stringify で、値はエスケープされて JSON の
-文字列リテラルに収まるため、要素の中へ契約外のキーを足す手段が無い。
-空文字は awscli が空値として解釈するので弾く。制御文字は spawn へ届く前にここで拒否する。
+shorthand-list の構成要素の値を検証する。JSON.stringify がエスケープするので、区切り文字は見ない。
 */
 function validateElementTexts(spec, field, texts) {
     for (const text of texts) {
         if (text === '')
-            return invalid(`${spec.name} の ${field} に空文字は指定できません`);
+            return invalid(`${spec.name} ${field} must not be empty`);
         if (hasControlCharacter(text)) {
-            return invalid(`${spec.name} の ${field} は制御文字を含まない値で指定してください`);
+            return invalid(`${spec.name} ${field} must not contain control characters`);
         }
     }
     return undefined;
 }
 /**
-shorthand-list の要素 1 件を検証する。
-
-値を持つ構成要素が 1 つも無い要素は拒否する。`--filters` に空の要素を渡すと awscli が
-空トークンを受け取り、意図しない絞り込みになるため。
+shorthand-list の要素 1 件を検証する。値を持つ構成要素が無い要素は、意図しない絞り込みになるので拒否する。
 */
 function validateShorthandListElement(spec, element) {
     const parts = spec.elements ?? [];
     /* c8 ignore start -- inputSchema の z.strictObject が入力検証エラーで先に落とすため到達しない（二重防御） */
     for (const key of Object.keys(element)) {
         if (parts.every(part => part.field !== key)) {
-            return invalid(`${spec.name} の要素に指定できないキーです: ${key}`);
+            return invalid(`${spec.name} element has an unsupported key: ${key}`);
         }
     }
     /* c8 ignore stop */
@@ -198,16 +159,16 @@ function validateShorthandListElement(spec, element) {
         let texts;
         if (part.list === true) {
             if (!isStringArray(value)) {
-                return invalid(`${spec.name} の ${part.field} は文字列の配列で指定してください`);
+                return invalid(`${spec.name} ${part.field} must be an array of strings`);
             }
             if (value.length === 0) {
-                return invalid(`${spec.name} の ${part.field} は 1 つ以上の値で指定してください`);
+                return invalid(`${spec.name} ${part.field} must have at least one value`);
             }
             texts = value;
         }
         else {
             if (typeof value !== 'string') {
-                return invalid(`${spec.name} の ${part.field} は文字列で指定してください`);
+                return invalid(`${spec.name} ${part.field} must be a string`);
             }
             texts = [value];
         }
@@ -216,17 +177,17 @@ function validateShorthandListElement(spec, element) {
             return rejected;
         filled += 1;
     }
-    return filled === 0 ? invalid(`${spec.name} の要素は ${parts.map(part => part.field).join(' / ')} のいずれかで指定してください`) : undefined;
+    return filled === 0 ? invalid(`${spec.name} element must have at least one of ${parts.map(part => part.field).join(' / ')}`) : undefined;
 }
 /**
 shorthand-list の値（オブジェクトの配列）を検証する。
 */
 function validateShorthandList(spec, value) {
     if (!Array.isArray(value))
-        return invalid(`${spec.name} はオブジェクトの配列で指定してください`);
+        return invalid(`${spec.name} must be an array of objects`);
     for (const element of value) {
         if (!isElementRecord(element)) {
-            return invalid(`${spec.name} の要素はオブジェクトで指定してください`);
+            return invalid(`${spec.name} element must be an object`);
         }
         const rejected = validateShorthandListElement(spec, element);
         if (rejected !== undefined)
@@ -240,11 +201,11 @@ function validateValue(spec, value) {
         case 'abs-path':
         case 's3-uri':
         case 's3-list-uri': {
-            return typeof value === 'string' ? validateStringValue(spec, value) : invalid(`${spec.name} は文字列で指定してください`);
+            return typeof value === 'string' ? validateStringValue(spec, value) : invalid(`${spec.name} must be a string`);
         }
         case 'string-list': {
             if (!isStringArray(value))
-                return invalid(`${spec.name} は文字列の配列で指定してください`);
+                return invalid(`${spec.name} must be an array of strings`);
             for (const element of value) {
                 const rejected = validateStringValue(spec, element);
                 if (rejected !== undefined)
@@ -252,31 +213,31 @@ function validateValue(spec, value) {
                 // 列挙を持つ string-list（--statistics 等）は要素ごとに比較する。awscli は列挙を
                 // クライアント側で検証しないため、ここを抜くと綴り違いがそのまま API へ届く。
                 if (spec.values !== undefined && !spec.values.includes(element)) {
-                    return invalid(`${spec.name} に指定できない値です: ${element}`);
+                    return invalid(`${spec.name} has an unsupported value: ${element}`);
                 }
             }
             return undefined;
         }
         case 'integer': {
             if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
-                return invalid(`${spec.name} は整数で指定してください`);
+                return invalid(`${spec.name} must be an integer`);
             }
             if (spec.min !== undefined && value < spec.min) {
-                return invalid(`${spec.name} は ${String(spec.min)} 以上で指定してください: ${String(value)}`);
+                return invalid(`${spec.name} must be at least ${String(spec.min)}: ${String(value)}`);
             }
             if (spec.max !== undefined && value > spec.max) {
-                return invalid(`${spec.name} は ${String(spec.max)} 以下で指定してください: ${String(value)}`);
+                return invalid(`${spec.name} must be at most ${String(spec.max)}: ${String(value)}`);
             }
             return undefined;
         }
         case 'boolean': {
-            return typeof value === 'boolean' ? undefined : invalid(`${spec.name} は true / false で指定してください`);
+            return typeof value === 'boolean' ? undefined : invalid(`${spec.name} must be true or false`);
         }
         case 'enum': {
             if (typeof value !== 'string')
-                return invalid(`${spec.name} は文字列で指定してください`);
+                return invalid(`${spec.name} must be a string`);
             if (spec.values?.includes(value) !== true) {
-                return invalid(`${spec.name} に指定できない値です: ${value}`);
+                return invalid(`${spec.name} has an unsupported value: ${value}`);
             }
             return undefined;
         }
@@ -285,15 +246,13 @@ function validateValue(spec, value) {
         }
         /* c8 ignore start -- shorthand は validateInput が先に分岐するため到達しない。switch の網羅性のために置く */
         case 'shorthand': {
-            return invalid(`${spec.name} は直接指定できません`);
+            return invalid(`${spec.name} cannot be specified directly`);
         }
         /* c8 ignore stop */
     }
 }
 /**
-入力を検証する。問題があれば invalid-input を、無ければ undefined を返す。
-
-profile / region も同じ処理で検証する（別扱いにすると書式検証が抜ける）。
+入力を検証する。問題があれば invalid-input を、無ければ undefined を返す。profile / region も同じ処理で検証する。
 */
 export function validateInput(entry, input) {
     for (const spec of specsOf(entry)) {
@@ -306,7 +265,7 @@ export function validateInput(entry, input) {
         const value = readInput(input, spec.name);
         if (value === undefined) {
             if (spec.required)
-                return invalid(`${spec.name} は必須です`);
+                return invalid(`${spec.name} is required`);
             continue;
         }
         const rejected = validateValue(spec, value);
@@ -317,7 +276,7 @@ export function validateInput(entry, input) {
     for (const group of exclusiveGroups) {
         const specified = group.filter(name => readInput(input, name) !== undefined);
         if (specified.length > 1) {
-            return invalid(`${specified.join(' と ')} は同時に指定できません`);
+            return invalid(`${specified.join(' and ')} cannot be combined`);
         }
     }
     return undefined;
@@ -330,9 +289,7 @@ function effectiveValue(spec, input) {
     return isInputValue(value) ? value : undefined;
 }
 /**
-shorthand フラグに載せる `Key=value,…` を組み立てる。
-
-値を持つ構成要素だけを並べ、1 つも無ければ undefined（= フラグごと省く）。
+shorthand フラグに載せる `Key=value,…` を組み立てる。値を持つ構成要素が無ければ undefined（フラグごと省く）。
 */
 function shorthandValue(spec, input) {
     const parts = [];
@@ -345,11 +302,7 @@ function shorthandValue(spec, input) {
     return parts.length === 0 ? undefined : parts.join(',');
 }
 /**
-shorthand-list フラグに載せる JSON 1 トークンを組み立てる。
-
-配列全体が `[{"Name":"…","Value":"…"}]` の 1 トークンになり、`list` の構成要素は JSON の配列のまま載せる。
-値を持つ構成要素が無い要素は落とす。要素が 1 つも残らなければ undefined
-（= フラグごと省く）。
+shorthand-list フラグに載せる JSON 1 トークンを組み立てる。要素が 1 つも残らなければ undefined。
 */
 function shorthandListToken(spec, input) {
     const value = readInput(input, spec.name);
@@ -384,27 +337,13 @@ function valueTexts(value) {
     return [typeof value === 'string' ? value : String(value)];
 }
 /**
-フラグ 1 つ分のトークン列。値が '-' で始まる string のときだけ `--flag=value` の 1 トークンにする。
-
-別トークンで渡すと awscli の argparse が値をオプションとして読む。`=` 連結は shell を
-介さない配列渡しなので、別トークンへ割れることも別コマンドへ委譲されることも無い。
+フラグ 1 つ分のトークン列。値が '-' で始まる string は、argparse の誤読を避けて `--flag=value` の 1 トークンにする。
 */
 function flagTokens(flag, value) {
     return typeof value === 'string' && value.startsWith('-') ? [`${flag}=${value}`] : [flag, ...valueTexts(value)];
 }
 /**
-awscli へ渡す引数配列を組み立てる。
-
-並びは `<service> <subcommand> <位置引数…> <フラグ…> --output json --no-cli-pager
---profile <p> --region <r>`。位置引数を先・フラグを後に置くと、string-list（nargs が貪欲）と
-位置引数が同居しても awscli v2 の argparse が取り違えない（動作確認済み）。
-
-`--no-cli-pager` は jsonOutput の有無に依らず常に付ける（非 tty では無害で、分岐を持たない方が単純）。
-
-`--profile` / `--region` は末尾で 1 度だけ付ける。エントリ側が inputs に同名を宣言していても
-フラグ列挙では飛ばす。
-
-値が '-' で始まる string は `--flag=value` の 1 トークンにする（flagTokens）。
+awscli へ渡す引数配列を組み立てる。位置引数を先・フラグを後に置くと、nargs が貪欲な string-list と同居しても取り違えない。
 */
 export function buildArguments(entry, input, common = {}) {
     const argv = [entry.service, entry.subcommand];

package/cli/dist/domain/athena-query.d.ts

@@ -1,8 +1,5 @@
 /**
-拒否理由。message は呼び出し元エージェントへそのまま返す。
-
-`unterminated`（引用符・コメントが閉じていない）を `not-read-only` と分けるのは、reason だけを
-見る呼び出し元が「変更系だから拒否」と誤読しないようにするため。倒す先はどちらも拒否で同じ。
+拒否理由。message は呼び出し元へそのまま返す。unterminated を分けるのは、変更系と誤読させないため。
 */
 export type AthenaQueryRejectionReason = 'empty' | 'multi-statement' | 'not-read-only' | 'unterminated';
 export type AthenaQueryClassification = {
@@ -13,10 +10,7 @@ export type AthenaQueryClassification = {
     readonly message: string;
 };
 /**
-クエリを参照専用 / 拒否に分類する。
-
-判定順は 未終端 → 複文 → 空 → 先頭キーワード。複文を空より先に見るのは、
-`; SELECT 1` のように 1 文目が空の入力を「空」ではなく「複文」と伝えるため。
+クエリを参照専用 / 拒否に分類する。複文を空より先に見るのは、`; SELECT 1` を「複文」と伝えるため。
 */
 export declare function classifyAthenaQuery(query: string): AthenaQueryClassification;
 //# sourceMappingURL=athena-query.d.ts.map

package/cli/dist/domain/athena-query.js

@@ -1,12 +1,5 @@
 // Athena に投げるクエリが参照専用かの判定（FR-008 / research R6）。
-//
-// 完全な SQL パーサは持たない。目的は「変更系と複文を awscli 起動前に落とす」ことなので、
-// 判定できない入力（未終端の引用符・コメント）は許可側ではなく拒否側へ倒す。
-// 判定は Trino 構文を前提にする。Athena では `WITH` で始まる文は必ず問い合わせで、
-// `INSERT INTO … WITH` / `CREATE TABLE … AS WITH` の `WITH` は先頭に来ない。
-// STG1 での確認（2026-09-07）: `WITH … INSERT` は StartQueryExecution 自体が失敗する。
-// 失敗の内容は InvalidRequestException / MALFORMED_QUERY で、実行に至らない。
-// 例外は内側の文を実際に実行する `EXPLAIN ANALYZE` だけで、これは `EXPLAIN` を剥がす反復で塞ぐ。
+// 判定できない入力は拒否側へ倒す。`EXPLAIN ANALYZE` は内側の文を実行するので、`EXPLAIN` を剥がす反復で塞ぐ。
 /**
 参照専用として受け付ける先頭キーワード。判定は大小文字を区別しない。
 */
@@ -20,10 +13,10 @@ const EXPLAIN_MODIFIERS = new Set(['ANALYZE', 'VERBOSE']);
 */
 const LEADING_WORD = /^\s*[A-Z]+/i;
 const REJECTION_MESSAGES = {
-    'empty': 'query_string が空です。参照クエリを指定してください',
-    'multi-statement': '複数の文は実行できません。; の後ろに文を続けず 1 文だけ指定してください',
-    'not-read-only': '参照クエリ（SELECT / WITH / SHOW / DESCRIBE / EXPLAIN）だけを実行できます',
-    'unterminated': '引用符またはコメントが閉じていないため、参照クエリだと判定できません',
+    'empty': 'query_string is empty. Specify a read-only query',
+    'multi-statement': 'Multiple statements are not allowed. Specify a single statement with nothing after the ;',
+    'not-read-only': 'Only read-only queries (SELECT / WITH / SHOW / DESCRIBE / EXPLAIN) can be executed',
+    'unterminated': 'Cannot confirm the query is read-only because a quote or comment is not closed',
 };
 function reject(reason, message) {
     return { allowed: false, reason, message };
@@ -43,11 +36,7 @@ function skipBlockComment(query, start) {
     return end === -1 ? undefined : end + 2;
 }
 /**
-引用の終端（閉じ引用符の次）。start は開き引用符の次を指す。
-
-`'…'` 文字列リテラルと `"…"` 引用識別子のエスケープは、同じ引用符の 2 重化だけ。
-Trino では `\` は文字列リテラル中でも普通の文字なので、`'\'` は「閉じていない」ではなく
-「バックスラッシュ 1 文字のリテラル」になる。
+引用の終端（閉じ引用符の次）。エスケープは引用符の 2 重化だけで、Trino では `\` は普通の文字。
 */
 function skipQuoted(query, start, quote) {
     let index = start;
@@ -65,11 +54,7 @@ function skipQuoted(query, start, quote) {
     return undefined;
 }
 /**
-コメントを空白へ、引用の中身を空の引用へ均す。
-
-中身を捨てるのは、後段が見るのは「リテラル外の `;`」と「先頭キーワード」だけだから。
-リテラルの内容は判定材料にならない。均しておけばリテラル内の `;` や `--` が
-後段の単純な文字列走査に引っ掛からない。
+コメントを空白へ、引用の中身を空の引用へ均す。リテラル内の `;` や `--` を後段の走査に拾わせないため。
 */
 function scan(query) {
     let code = '';
@@ -126,10 +111,7 @@ function afterLeadingWord(text) {
     return matched === undefined ? text : text.slice(matched[0].length);
 }
 /**
-先頭が `(` ならその対応括弧までを剥がす（`EXPLAIN (TYPE DISTRIBUTED) SELECT …`）。
-
-対応する `)` が無い場合は剥がさずに返す。剥がせないと、後段の語判定は左括弧を見て
-語を取れず、拒否側へ倒れる。
+先頭が `(` ならその対応括弧までを剥がす。対応する `)` が無ければ剥がさず、拒否側へ倒す。
 */
 function afterOptionGroup(text) {
     const trimmed = text.trimStart();
@@ -149,11 +131,7 @@ function afterOptionGroup(text) {
     return trimmed;
 }
 /**
-1 文が参照専用か。
-
-`EXPLAIN` は修飾語とオプション群を剥がして内側を見直す。1 周ごとに必ず `EXPLAIN` の 1 語を
-消費するので停止する。再帰ではなくループにするのは、`EXPLAIN` を数万段重ねた入力で
-コールスタックを溢れさせないため（溢れると失敗種別の外の例外になる）。
+1 文が参照専用か。再帰でなくループなのは、`EXPLAIN` を重ねた入力でコールスタックを溢れさせないため。
 */
 function isReadOnlyStatement(statement) {
     let current = statement;
@@ -169,10 +147,7 @@ function isReadOnlyStatement(statement) {
     return READ_ONLY_KEYWORDS.has(word);
 }
 /**
-クエリを参照専用 / 拒否に分類する。
-
-判定順は 未終端 → 複文 → 空 → 先頭キーワード。複文を空より先に見るのは、
-`; SELECT 1` のように 1 文目が空の入力を「空」ではなく「複文」と伝えるため。
+クエリを参照専用 / 拒否に分類する。複文を空より先に見るのは、`; SELECT 1` を「複文」と伝えるため。
 */
 export function classifyAthenaQuery(query) {
     const scanned = scan(query);

package/cli/dist/domain/s3-input.d.ts

@@ -1,9 +1,5 @@
 /**
-`s3://<bucket>/<key>` 形式か。
-
-空白を含む値は拒否しない。引数は shell を介さず、1 要素 1 値で awscli へ渡る。
-そのため `s3://b/k --recursive` のような値は「そういう名前のキー」として扱われ、
-別オプションには化けない（research R3）。
+`s3://<bucket>/<key>` 形式か。空白を含む値は、shell を介さず 1 値で渡るので拒否しない（research R3）。
 */
 export declare function validateS3Uri(value: string): string | undefined;
 /**
@@ -11,10 +7,7 @@ export declare function validateS3Uri(value: string): string | undefined;
 */
 export declare function validateS3ListUri(value: string): string | undefined;
 /**
-書き出し先のローカルパスとして妥当か。
-
-`s3://…` を先に見るのは、絶対パスの検証だけでも弾けるが「相対パスだ」という案内になり、
-取得元と書き出し先を取り違えた利用者に誤った直し方を促すため。
+書き出し先のローカルパスとして妥当か。`s3://…` を先に弾くのは、取得元と取り違えた利用者に誤案内しないため。
 */
 export declare function validateLocalPath(value: string): string | undefined;
 //# sourceMappingURL=s3-input.d.ts.map