From bf5fcfc034e3e58d6dace28521adc223965520a3 Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Sun, 5 Apr 2026 02:17:50 -0400 Subject: [PATCH] docs(help): add kiro idc flag guidance - add a dedicated 'ccs help kiro' topic with IDC and paste-callback examples - link the providers help topic to the new Kiro-specific help surface --- src/commands/command-catalog.ts | 3 +- src/commands/help-command.ts | 73 +++++++++++++++++++ .../unit/commands/help-command-parity.test.ts | 12 +++ 3 files changed, 87 insertions(+), 1 deletion(-) diff --git a/src/commands/command-catalog.ts b/src/commands/command-catalog.ts index 28bf315d..11f3a984 100644 --- a/src/commands/command-catalog.ts +++ b/src/commands/command-catalog.ts @@ -2,7 +2,7 @@ import { COPILOT_SUBCOMMANDS } from '../copilot/constants'; import { CURSOR_SUBCOMMANDS } from '../cursor/constants'; import { CLIPROXY_PROVIDER_IDS } from '../cliproxy/provider-capabilities'; -export type HelpTopicName = 'profiles' | 'providers' | 'completion' | 'targets'; +export type HelpTopicName = 'profiles' | 'providers' | 'kiro' | 'completion' | 'targets'; export interface HelpTopicEntry { name: HelpTopicName; @@ -25,6 +25,7 @@ export interface ShortcutEntry { export const ROOT_HELP_TOPICS: readonly HelpTopicEntry[] = [ { name: 'profiles', summary: 'Account profiles, API profiles, and CLIProxy variants' }, { name: 'providers', summary: 'Built-in OAuth providers and runtime shortcuts' }, + { name: 'kiro', summary: 'Kiro auth methods, IDC flags, and callback guidance' }, { name: 'completion', summary: 'Shell completion install, refresh, and testing' }, { name: 'targets', summary: 'Claude, Droid, and Codex target routing' }, ] as const; diff --git a/src/commands/help-command.ts b/src/commands/help-command.ts index 88efc512..641a2d2c 100644 --- a/src/commands/help-command.ts +++ b/src/commands/help-command.ts @@ -78,6 +78,7 @@ async function showProvidersHelp(writeLine: HelpWriter): Promise { }, { name: 'ccs api create --preset ', summary: 'Create an API-backed provider profile' }, { name: 'ccs config', summary: 'Use the dashboard for provider and model setup' }, + { name: 'ccs help kiro', summary: 'Kiro-specific auth methods and IDC flags' }, ], writeLine ); @@ -85,6 +86,74 @@ async function showProvidersHelp(writeLine: HelpWriter): Promise { writeLine(''); } +async function showKiroHelp(writeLine: HelpWriter): Promise { + await initUI(); + writeLine(header('CCS Kiro Help')); + writeLine(''); + writeLine(' Kiro supports Builder ID, IDC, and management-only social OAuth flows.'); + writeLine(''); + writeCommandTable( + 'Authentication Methods', + [ + { name: 'ccs kiro --auth', summary: 'Default AWS Builder ID device-code flow' }, + { + name: 'ccs kiro --auth --kiro-auth-method aws-authcode', + summary: 'AWS Builder ID auth-code flow via local callback server', + }, + { + name: 'ccs kiro --auth --kiro-auth-method idc', + summary: 'IAM Identity Center flow; requires IDC start URL', + }, + { + name: 'ccs config', + summary: 'Dashboard flow for GitHub OAuth and account management', + }, + ], + writeLine + ); + writeCommandTable( + 'Kiro Flags', + [ + { + name: '--kiro-auth-method ', + summary: 'Select the Kiro auth method', + }, + { name: '--kiro-idc-start-url ', summary: 'Required IDC start URL when using `idc`' }, + { name: '--kiro-idc-region ', summary: 'Optional IDC region override' }, + { name: '--kiro-idc-flow ', summary: 'IDC flow type; defaults to authcode' }, + { + name: '--paste-callback', + summary: 'Paste the final callback URL for callback-based CLI auth flows', + }, + { name: '--import', summary: 'Import an existing Kiro IDE token instead of starting OAuth' }, + ], + writeLine + ); + writeCommandTable( + 'Examples', + [ + { name: 'ccs kiro --auth', summary: 'Start the default Builder ID device flow' }, + { + name: 'ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback', + summary: 'Use auth-code flow and paste the callback URL manually', + }, + { + name: 'ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start', + summary: 'Start IDC auth with the default authcode flow', + }, + { + name: 'ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start --kiro-idc-flow device', + summary: 'Use IDC device-code flow instead of authcode', + }, + ], + writeLine + ); + writeLine( + ` ${dim('GitHub OAuth is dashboard-only: ccs config -> Accounts -> Add Kiro account')}` + ); + writeLine(''); +} + async function showTargetsHelp(writeLine: HelpWriter): Promise { await initUI(); writeLine(header('CCS Targets Help')); @@ -176,6 +245,10 @@ export async function handleHelpRoute( await showProvidersHelp(writeLine); return; } + if (topic === 'kiro') { + await showKiroHelp(writeLine); + return; + } if (topic === 'targets') { await showTargetsHelp(writeLine); return; diff --git a/tests/unit/commands/help-command-parity.test.ts b/tests/unit/commands/help-command-parity.test.ts index bf830826..017ec18e 100644 --- a/tests/unit/commands/help-command-parity.test.ts +++ b/tests/unit/commands/help-command-parity.test.ts @@ -46,11 +46,23 @@ describe('help command parity', () => { expect(rendered.includes('Built-in OAuth Providers')).toBe(true); expect(rendered.includes('ccs cliproxy --help')).toBe(true); + expect(rendered.includes('ccs help kiro')).toBe(true); expect(rendered.includes('gemini')).toBe(true); expect(rendered.includes('codex')).toBe(true); expect(rendered.includes('ghcp')).toBe(true); }); + test('kiro topic documents IDC and callback flags', async () => { + const rendered = await renderLines((writeLine) => handleHelpRoute(['kiro'], writeLine)); + + expect(rendered.includes('CCS Kiro Help')).toBe(true); + expect(rendered.includes('--kiro-idc-start-url ')).toBe(true); + expect(rendered.includes('--kiro-idc-region ')).toBe(true); + expect(rendered.includes('--kiro-idc-flow ')).toBe(true); + expect(rendered.includes('--paste-callback')).toBe(true); + expect(rendered.includes('GitHub OAuth is dashboard-only')).toBe(true); + }); + test('completion topic documents install and verification paths', async () => { const rendered = await renderLines((writeLine) => handleHelpRoute(['completion'], writeLine));