feat: --scopes オプションのヘルプに有効なスコープ一覧を追加 (#73)

* feat: --scopes オプションのヘルプに有効なスコープ一覧を追加

help.ts に addNotes() 機能を追加し、--scopes を持つコマンド
(me oauth-clients create, me api-keys create, admin api-keys create/update)
の NOTES セクションに全16リソーススコープと包含関係を表示。

* fix: E2E テストの config を v2 フォーマットで統一し認証フレーキーテストを修正

writeConfig() に v1→v2 自動ラップを追加し、CLI プロセスでの
auto-migration（ファイル再書き込み）を不要にした。
これにより別プロセス間のファイル I/O タイミング問題を解消。

* docs: CHANGELOG に E2E フレーキーテスト修正を追記

Author: miya0001

CHANGELOG.md

@@ -7,6 +7,12 @@
 
 ## [Unreleased]
 
+### 2026-03-17
+- **Feat**: `--scopes` オプションを持つコマンドのヘルプに有効なスコープ一覧を NOTES セクションとして追加 (#73)
+- **Docs**: README の Valid Scopes セクションを全18スコープに更新、包含関係と特殊スコープの説明を追加 (#73)
+- **Fix**: `admin api-keys create` の例で誤ったスコープ形式 (`entities:read`) を正しい形式 (`read:entities`) に修正 (#73)
+- **Fix**: E2E テストの config を v2 フォーマットで統一し、CLI プロセスでの auto-migration による認証フレーキーテストを修正 (#73)
+
 ## [0.6.2] - 2026-03-17
 
 ### 2026-03-17

README.md

@@ -564,7 +564,11 @@ When both a Bearer token and an API key are configured, both headers are sent (t
 
 ### Valid Scopes
 
-`read:entities`, `write:entities`, `read:subscriptions`, `write:subscriptions`, `read:registrations`, `write:registrations`
+`read:entities`, `write:entities`, `read:subscriptions`, `write:subscriptions`, `read:registrations`, `write:registrations`, `read:rules`, `write:rules`, `read:custom-data-models`, `write:custom-data-models`, `admin:users`, `admin:tenants`, `admin:policies`, `admin:oauth-clients`, `admin:api-keys`, `admin:metrics`
+
+`write:X` implies `read:X`. `admin:X` implies both `read:X` and `write:X`.
+
+Special scopes: `permanent` (no token expiry), `jwt` (JWT format token).
 
 ### Entity Type Restrictions
 

src/commands/admin/api-keys.ts

@@ -3,7 +3,8 @@ import { withErrorHandler, createClient, resolveOptions, getFormat, outputRespon
 import { loadConfig, saveConfig } from "../../config.js";
 import { parseJsonInput } from "../../input.js";
 import { printError, printWarning } from "../../output.js";
-import { addExamples } from "../help.js";
+import { addExamples, addNotes } from "../help.js";
+import { SCOPES_HELP_NOTES } from "../../helpers.js";
 
 function validateOrigins(body: unknown, opts: Record<string, unknown>): void {
   // Validate origins if provided via flags
@@ -173,10 +174,12 @@ export function registerApiKeysCommand(parent: Command): void {
       }),
     );
 
+  addNotes(create, SCOPES_HELP_NOTES);
+
   addExamples(create, [
     {
       description: "Create an API key with flags",
-      command: "geonic admin api-keys create --name my-key --scopes entities:read,entities:write --origins '*'",
+      command: "geonic admin api-keys create --name my-key --scopes read:entities,write:entities --origins '*'",
     },
     {
       description: "Create an API key with DPoP required",
@@ -237,6 +240,8 @@ export function registerApiKeysCommand(parent: Command): void {
       ),
     );
 
+  addNotes(update, SCOPES_HELP_NOTES);
+
   addExamples(update, [
     {
       description: "Update an API key name",

src/commands/help.ts

@@ -7,11 +7,16 @@ interface Example {
 }
 
 const examplesMap = new WeakMap<Command, Example[]>();
+const notesMap = new WeakMap<Command, string[]>();
 
 export function addExamples(cmd: Command, examples: Example[]): void {
   examplesMap.set(cmd, examples);
 }
 
+export function addNotes(cmd: Command, notes: string[]): void {
+  notesMap.set(cmd, notes);
+}
+
 function header(title: string): string {
   return chalk.yellow.bold(title);
 }
@@ -197,6 +202,17 @@ export function formatCommandDetails(
     }
   }
 
+  // NOTES
+  const notes = notesMap.get(cmd);
+  if (notes && notes.length > 0) {
+    lines.push("");
+    lines.push(header("NOTES"));
+    lines.push("");
+    for (const note of notes) {
+      lines.push(`  ${note}`);
+    }
+  }
+
   // GLOBAL PARAMETERS
   lines.push("");
   lines.push(formatGlobalParameters(program));

src/commands/me-api-keys.ts

@@ -3,7 +3,8 @@ import { withErrorHandler, createClient, resolveOptions, getFormat, outputRespon
 import { loadConfig, saveConfig } from "../config.js";
 import { parseJsonInput } from "../input.js";
 import { printError, printWarning } from "../output.js";
-import { addExamples } from "./help.js";
+import { addExamples, addNotes } from "./help.js";
+import { SCOPES_HELP_NOTES } from "../helpers.js";
 
 export function addMeApiKeysSubcommand(me: Command): void {
   const apiKeys = me
@@ -127,6 +128,8 @@ export function addMeApiKeysSubcommand(me: Command): void {
       }),
     );
 
+  addNotes(create, SCOPES_HELP_NOTES);
+
   addExamples(create, [
     {
       description: "Create an API key with flags",

src/commands/me-oauth-clients.ts

@@ -4,7 +4,8 @@ import { loadConfig, saveConfig, validateUrl } from "../config.js";
 import { parseJsonInput } from "../input.js";
 import { printSuccess, printError, printInfo, printWarning } from "../output.js";
 import { clientCredentialsGrant } from "../oauth.js";
-import { addExamples } from "./help.js";
+import { addExamples, addNotes } from "./help.js";
+import { SCOPES_HELP_NOTES } from "../helpers.js";
 
 export function addMeOAuthClientsSubcommand(me: Command): void {
   const oauthClients = me
@@ -106,6 +107,8 @@ export function addMeOAuthClientsSubcommand(me: Command): void {
       }),
     );
 
+  addNotes(create, SCOPES_HELP_NOTES);
+
   addExamples(create, [
     {
       description: "Create an OAuth client with flags",

src/helpers.ts

@@ -4,6 +4,20 @@ import { DryRunSignal, GdbClient, GdbClientError } from "./client.js";
 import { printError, printOutput, printCount } from "./output.js";
 import type { ClientResponse, GlobalOptions, OutputFormat } from "./types.js";
 
+/**
+ * Valid scope values for --scopes option help text.
+ */
+export const SCOPES_HELP_NOTES = [
+  "Valid scopes:",
+  "  read:entities, write:entities, read:subscriptions, write:subscriptions,",
+  "  read:registrations, write:registrations, read:rules, write:rules,",
+  "  read:custom-data-models, write:custom-data-models,",
+  "  admin:users, admin:tenants, admin:policies, admin:oauth-clients,",
+  "  admin:api-keys, admin:metrics",
+  "",
+  "write:X implies read:X. admin:X implies both read:X and write:X.",
+];
+
 /**
  * Resolve merged options from config + CLI flags.
  */

tests/admin-api-keys.test.ts

@@ -7,6 +7,7 @@ vi.mock("../src/helpers.js", () => ({
   getFormat: vi.fn(),
   outputResponse: vi.fn(),
   withErrorHandler: (fn: (...args: unknown[]) => unknown) => fn,
+  SCOPES_HELP_NOTES: [],
   resolveOptions: vi.fn().mockReturnValue({ profile: "default" }),
 }));
 
@@ -25,6 +26,7 @@ vi.mock("../src/output.js", () => ({
 
 vi.mock("../src/commands/help.js", () => ({
   addExamples: vi.fn(),
+  addNotes: vi.fn(),
 }));
 
 vi.mock("../src/config.js", () => ({

tests/admin-oauth-clients.test.ts

@@ -7,6 +7,7 @@ vi.mock("../src/helpers.js", () => ({
   getFormat: vi.fn(),
   outputResponse: vi.fn(),
   withErrorHandler: (fn: (...args: unknown[]) => unknown) => fn,
+  SCOPES_HELP_NOTES: [],
   resolveOptions: vi.fn(),
 }));
 
@@ -25,6 +26,7 @@ vi.mock("../src/output.js", () => ({
 
 vi.mock("../src/commands/help.js", () => ({
   addExamples: vi.fn(),
+  addNotes: vi.fn(),
 }));
 
 import { createClient, getFormat, outputResponse } from "../src/helpers.js";

tests/admin-policies.test.ts

@@ -7,6 +7,7 @@ vi.mock("../src/helpers.js", () => ({
   getFormat: vi.fn(),
   outputResponse: vi.fn(),
   withErrorHandler: (fn: (...args: unknown[]) => unknown) => fn,
+  SCOPES_HELP_NOTES: [],
   resolveOptions: vi.fn(),
 }));
 
@@ -25,6 +26,7 @@ vi.mock("../src/output.js", () => ({
 
 vi.mock("../src/commands/help.js", () => ({
   addExamples: vi.fn(),
+  addNotes: vi.fn(),
 }));
 
 import { createClient, getFormat, outputResponse } from "../src/helpers.js";