@@ -3,7 +3,7 @@ import { CLI_COMMANDS, findCommand, type CliCommandEntry } from "./registry";
33
44export type HelpResolution =
55 | { kind : "entry" ; entry : CliCommandEntry ; canonicalName : string ; children : readonly Capability [ ] }
6- | { kind : "capability" ; path : string [ ] ; capability : Capability }
6+ | { kind : "capability" ; path : string [ ] ; capability : Capability ; children : readonly Capability [ ] }
77 | { kind : "prefix" ; path : string [ ] ; children : readonly Capability [ ] }
88 | { kind : "models-context" ; path : string [ ] }
99 | { kind : "unavailable" ; path : string [ ] ; parent ?: string [ ] } ;
@@ -22,6 +22,18 @@ function canonicalEntry(entry: CliCommandEntry): CliCommandEntry {
2222 return CLI_COMMANDS . find ( candidate => candidate . aliases ?. includes ( entry . name ) ) ?? entry ;
2323}
2424
25+ /** Help-only aliases from access dispatch; never rewrite execution argv or operands. */
26+ function canonicalHelpPath ( requested : readonly string [ ] , entry : CliCommandEntry ) : string [ ] {
27+ const path = entry . name === "api-key"
28+ ? [ "access" , "key" , ...requested . slice ( 1 ) ]
29+ : [ canonicalEntry ( entry ) . name , ...requested . slice ( 1 ) ] ;
30+ if ( path [ 0 ] === "access" ) {
31+ if ( path [ 1 ] === "keys" ) path [ 1 ] = "key" ;
32+ if ( path [ 1 ] === "key" && path [ 2 ] === "delete" ) path [ 2 ] = "remove" ;
33+ }
34+ return path ;
35+ }
36+
2537export interface HelpRecoveryCandidate {
2638 names : string [ ] ;
2739 path : string [ ] ;
@@ -35,19 +47,24 @@ export function helpRecoveryCandidates(parent: readonly string[] = []): HelpReco
3547 if ( entry . hidden ) continue ;
3648 const canonical = canonicalEntry ( entry ) ;
3749 if ( canonical . hidden ) continue ;
38- const candidate = candidates . get ( canonical . name ) ?? { names : [ ] , path : [ canonical . name ] } ;
50+ const path = canonicalHelpPath ( [ entry . name ] , entry ) ;
51+ const identity = path . join ( " " ) ;
52+ const candidate = candidates . get ( identity ) ?? { names : [ ] , path } ;
3953 candidate . names = [ ...new Set ( [ ...candidate . names , entry . name , ...( entry . aliases ?? [ ] ) ] ) ] ;
40- candidates . set ( canonical . name , candidate ) ;
54+ candidates . set ( identity , candidate ) ;
4155 }
4256 } else {
43- if ( parent . length >= MAX_DOCUMENTED_DEPTH ) return [ ] ;
4457 const entry = findCommand ( parent [ 0 ] ) ;
4558 if ( ! entry || entry . hidden ) return [ ] ;
46- const prefix = [ canonicalEntry ( entry ) . name , ...parent . slice ( 1 ) ] ;
59+ const prefix = canonicalHelpPath ( parent , entry ) ;
60+ if ( prefix . length >= MAX_DOCUMENTED_DEPTH ) return [ ] ;
4761 for ( const documented of DOCUMENTED_PATHS ) {
4862 if ( documented . length <= prefix . length || ! startsWithPath ( documented , prefix ) ) continue ;
4963 const path = documented . slice ( 0 , prefix . length + 1 ) ;
50- candidates . set ( path . join ( " " ) , { names : [ path [ path . length - 1 ] ] , path } ) ;
64+ const names = [ path [ path . length - 1 ] ] ;
65+ if ( path . join ( " " ) === "access key" ) names . push ( "keys" ) ;
66+ if ( path . join ( " " ) === "access key remove" ) names . push ( "delete" ) ;
67+ candidates . set ( path . join ( " " ) , { names, path } ) ;
5168 }
5269 }
5370 return [ ...candidates . values ( ) ] ;
@@ -58,19 +75,18 @@ export function resolveHelpPath(requested: readonly string[]): HelpResolution {
5875 const entry = requested [ 0 ] ? findCommand ( requested [ 0 ] ) : undefined ;
5976 if ( ! entry ) return { kind : "unavailable" , path : [ ...requested ] } ;
6077 // Keep exact-name alias entries for root help; nested topics use the owner.
61- const canonical = canonicalEntry ( entry ) ;
78+ const path = canonicalHelpPath ( requested , entry ) ;
6279 const declared = CAPABILITIES . filter ( capability => ! findCommand ( capability . command [ 0 ] ) ?. hidden ) ;
6380 if ( requested . length === 1 ) return {
64- kind : "entry" , entry, canonicalName : canonical . name ,
65- children : entry . hidden ? [ ] : declared . filter ( candidate => candidate . command . length > 1 && candidate . command [ 0 ] === canonical . name ) ,
81+ kind : "entry" , entry, canonicalName : path . join ( " " ) ,
82+ children : entry . hidden ? [ ] : declared . filter ( candidate => candidate . command . length > path . length && startsWithPath ( candidate . command , path ) ) ,
6683 } ;
67- const path = [ canonical . name , ...requested . slice ( 1 ) ] ;
6884 if ( path . length === 2 && path [ 0 ] === "models" && path [ 1 ] === "context" ) {
6985 return { kind : "models-context" , path } ;
7086 }
7187 const capability = declared . find ( candidate => candidate . command . length === path . length && startsWithPath ( candidate . command , path ) ) ;
72- if ( capability ) return { kind : "capability" , path, capability } ;
73- const children = declared . filter ( candidate => startsWithPath ( candidate . command , path ) ) ;
88+ const children = declared . filter ( candidate => candidate . command . length > path . length && startsWithPath ( candidate . command , path ) ) ;
89+ if ( capability ) return { kind : "capability" , path, capability , children } ;
7490 if ( children . length ) return { kind : "prefix" , path, children } ;
7591
7692 for ( let length = Math . min ( path . length - 1 , MAX_DOCUMENTED_DEPTH ) ; length > 1 ; length -- ) {
@@ -80,5 +96,5 @@ export function resolveHelpPath(requested: readonly string[]): HelpResolution {
8096 return { kind : "unavailable" , path, parent } ;
8197 }
8298 }
83- return { kind : "unavailable" , path, parent : [ canonical . name ] } ;
99+ return { kind : "unavailable" , path, parent : [ path [ 0 ] ] } ;
84100}
0 commit comments