@kjanat/dreamcli 2.5.0 → 3.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/CHANGELOG.md +153 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.mjs +214 -1
  4. package/dist/core/cli/help-links.mjs +41 -1
  5. package/dist/core/cli/index.d.mts +109 -16
  6. package/dist/core/cli/index.mjs +901 -1
  7. package/dist/core/cli/planner.d.mts +27 -5
  8. package/dist/core/cli/planner.mjs +300 -1
  9. package/dist/core/cli/plugin.mjs +41 -1
  10. package/dist/core/cli/propagate.mjs +57 -1
  11. package/dist/core/cli/root-help.d.mts +16 -2
  12. package/dist/core/cli/root-help.mjs +208 -6
  13. package/dist/core/cli/root-surface.d.mts +18 -3
  14. package/dist/core/cli/root-surface.mjs +27 -1
  15. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  16. package/dist/core/cli/runtime-preflight.mjs +168 -1
  17. package/dist/core/completion/index.d.mts +32 -1
  18. package/dist/core/completion/index.mjs +90 -1
  19. package/dist/core/completion/shells/bash.mjs +304 -3
  20. package/dist/core/completion/shells/fish.mjs +159 -2
  21. package/dist/core/completion/shells/powershell.mjs +353 -2
  22. package/dist/core/completion/shells/shared.d.mts +10 -0
  23. package/dist/core/completion/shells/shared.mjs +154 -1
  24. package/dist/core/completion/shells/zsh.mjs +244 -2
  25. package/dist/core/config/index.mjs +246 -1
  26. package/dist/core/config/package-json.mjs +385 -3
  27. package/dist/core/errors/index.mjs +87 -1
  28. package/dist/core/execution/index.mjs +189 -1
  29. package/dist/core/help/ansi.mjs +122 -2
  30. package/dist/core/help/index.d.mts +45 -1
  31. package/dist/core/help/index.mjs +329 -7
  32. package/dist/core/json-schema/index.mjs +487 -9
  33. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  34. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  35. package/dist/core/output/activity.mjs +452 -1
  36. package/dist/core/output/bind.mjs +56 -1
  37. package/dist/core/output/contracts.mjs +57 -1
  38. package/dist/core/output/display-value.mjs +32 -1
  39. package/dist/core/output/index.d.mts +21 -0
  40. package/dist/core/output/index.mjs +442 -2
  41. package/dist/core/output/renderers.mjs +46 -1
  42. package/dist/core/output/writer.mjs +12 -1
  43. package/dist/core/parse/index.d.mts +15 -1
  44. package/dist/core/parse/index.mjs +555 -1
  45. package/dist/core/prompt/index.d.mts +11 -4
  46. package/dist/core/prompt/index.mjs +348 -6
  47. package/dist/core/resolve/args.mjs +105 -1
  48. package/dist/core/resolve/coerce.mjs +279 -1
  49. package/dist/core/resolve/config.mjs +19 -1
  50. package/dist/core/resolve/errors.mjs +140 -2
  51. package/dist/core/resolve/flags.mjs +196 -1
  52. package/dist/core/resolve/index.mjs +85 -1
  53. package/dist/core/resolve/property.d.mts +2 -1
  54. package/dist/core/resolve/property.mjs +45 -1
  55. package/dist/core/schema/arg.d.mts +90 -10
  56. package/dist/core/schema/arg.mjs +463 -1
  57. package/dist/core/schema/command.d.mts +21 -1
  58. package/dist/core/schema/command.mjs +712 -1
  59. package/dist/core/schema/flag.d.mts +92 -2
  60. package/dist/core/schema/flag.mjs +453 -1
  61. package/dist/core/schema/index.d.mts +2 -1
  62. package/dist/core/schema/middleware.mjs +41 -1
  63. package/dist/core/schema/number-constraints.d.mts +96 -0
  64. package/dist/core/schema/number-constraints.mjs +60 -0
  65. package/dist/core/schema/prompt.d.mts +15 -0
  66. package/dist/core/schema/run.d.mts +4 -4
  67. package/dist/core/schema-dsl/runtime.mjs +271 -2
  68. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  69. package/dist/core/testkit/index.d.mts +9 -5
  70. package/dist/core/testkit/index.mjs +83 -1
  71. package/dist/index.d.mts +3 -1
  72. package/dist/index.mjs +22 -1
  73. package/dist/runtime/adapter.mjs +82 -1
  74. package/dist/runtime/auto.mjs +46 -1
  75. package/dist/runtime/bun.mjs +28 -1
  76. package/dist/runtime/deno.mjs +217 -2
  77. package/dist/runtime/detect.mjs +45 -1
  78. package/dist/runtime/node.mjs +169 -2
  79. package/dist/runtime/paths.mjs +48 -1
  80. package/dist/runtime.mjs +7 -1
  81. package/dist/strings.mjs +22 -1
  82. package/dist/testkit.mjs +5 -1
  83. package/dist/version.mjs +7 -1
  84. package/examples/basic.ts +5 -1
  85. package/examples/gh/package.json +2 -7
  86. package/examples/pwsh-demo/package.json +1 -7
  87. package/examples/pwsh-demo/src/main.test.ts +1 -4
  88. package/examples/pwsh-demo/src/main.ts +14 -4
  89. package/examples/transport-launcher.ts +85 -0
  90. package/package.json +23 -41
  91. package/dist/runtime/support.d.mts +0 -42
  92. package/dist/runtime/support.mjs +0 -1
  93. package/src/core/cli/dispatch.ts +0 -349
  94. package/src/core/cli/help-links.ts +0 -82
  95. package/src/core/cli/index.ts +0 -1413
  96. package/src/core/cli/planner.ts +0 -487
  97. package/src/core/cli/plugin.ts +0 -117
  98. package/src/core/cli/propagate.ts +0 -97
  99. package/src/core/cli/root-help.ts +0 -252
  100. package/src/core/cli/root-surface.ts +0 -74
  101. package/src/core/cli/runtime-preflight.ts +0 -438
  102. package/src/core/completion/index.ts +0 -88
  103. package/src/core/completion/shells/bash.ts +0 -459
  104. package/src/core/completion/shells/fish.ts +0 -259
  105. package/src/core/completion/shells/powershell.ts +0 -439
  106. package/src/core/completion/shells/shared.ts +0 -283
  107. package/src/core/completion/shells/zsh.ts +0 -381
  108. package/src/core/config/index.ts +0 -417
  109. package/src/core/config/package-json.ts +0 -560
  110. package/src/core/errors/index.ts +0 -193
  111. package/src/core/execution/index.ts +0 -268
  112. package/src/core/help/ansi.ts +0 -144
  113. package/src/core/help/index.ts +0 -516
  114. package/src/core/json-schema/index.ts +0 -891
  115. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  116. package/src/core/output/activity.ts +0 -575
  117. package/src/core/output/bind.ts +0 -59
  118. package/src/core/output/contracts.ts +0 -194
  119. package/src/core/output/display-value.ts +0 -48
  120. package/src/core/output/index.ts +0 -704
  121. package/src/core/output/renderers.ts +0 -125
  122. package/src/core/output/writer.ts +0 -46
  123. package/src/core/parse/index.ts +0 -681
  124. package/src/core/prompt/index.ts +0 -583
  125. package/src/core/resolve/args.ts +0 -144
  126. package/src/core/resolve/coerce.ts +0 -432
  127. package/src/core/resolve/config.ts +0 -26
  128. package/src/core/resolve/contracts.ts +0 -135
  129. package/src/core/resolve/errors.ts +0 -227
  130. package/src/core/resolve/flags.ts +0 -255
  131. package/src/core/resolve/index.ts +0 -108
  132. package/src/core/resolve/property.ts +0 -99
  133. package/src/core/schema/activity.ts +0 -240
  134. package/src/core/schema/arg.ts +0 -719
  135. package/src/core/schema/command.ts +0 -1498
  136. package/src/core/schema/flag.ts +0 -801
  137. package/src/core/schema/index.ts +0 -91
  138. package/src/core/schema/middleware.ts +0 -171
  139. package/src/core/schema/prompt.ts +0 -156
  140. package/src/core/schema/run.ts +0 -198
  141. package/src/core/schema-dsl/index.ts +0 -109
  142. package/src/core/schema-dsl/parse.ts +0 -262
  143. package/src/core/schema-dsl/runtime.ts +0 -609
  144. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  145. package/src/core/testkit/index.ts +0 -123
  146. package/src/index.ts +0 -179
  147. package/src/runtime/adapter.ts +0 -303
  148. package/src/runtime/auto.ts +0 -110
  149. package/src/runtime/bun.ts +0 -55
  150. package/src/runtime/deno.ts +0 -369
  151. package/src/runtime/detect.ts +0 -105
  152. package/src/runtime/index.ts +0 -21
  153. package/src/runtime/node-builtins.d.ts +0 -27
  154. package/src/runtime/node.ts +0 -300
  155. package/src/runtime/paths.ts +0 -64
  156. package/src/runtime/support.ts +0 -135
  157. package/src/runtime.ts +0 -31
  158. package/src/strings.ts +0 -34
  159. package/src/testkit.ts +0 -25
  160. package/src/version.ts +0 -20
@@ -1,2 +1,353 @@
1
- import{getFlagAliasNames as e}from"../../schema/flag.mjs";import{resolveRootCompletionSurface as t,sanitizeShellIdentifier as n,versionTag as r,walkCommandTree as i}from"./shared.mjs";function a(e,a){let s=`__${n(a?.functionPrefix??e.name)}_completions`,u=`${s}_paths`,d=t(e,a?.rootMode),f=d.visibleCommands,p=i(f),m=[];return m.push(`# PowerShell completion for ${e.name}`),m.push(`# Generated by ${r()}`),m.push(`#`),m.push(`# Install for the current session:`),m.push(`# ${e.name} completions powershell | Out-String | Invoke-Expression`),m.push(`#`),m.push(`# Install permanently:`),m.push(`# ${e.name} completions powershell > $PROFILE.CurrentUserCurrentHost`),m.push(``),m.push(`using namespace System.Management.Automation`),m.push(`using namespace System.Management.Automation.Language`),m.push(``),o(m,u,d,p),m.push(``),c(m,s,u),m.push(``),m.push(`Register-ArgumentCompleter -Native -CommandName ${l(e.name)} -ScriptBlock {`),m.push(` param($wordToComplete, $commandAst, $cursorPosition)`),m.push(`\t$state = ${s}_GetState -CommandAst $commandAst -CursorPosition $cursorPosition`),m.push(` if ($null -eq $state.PathData) {`),m.push(` return`),m.push(` }`),m.push(``),m.push(` $results = [System.Collections.Generic.List[CompletionResult]]::new()`),m.push(` if ($state.AfterSeparator) {`),m.push(` return $results`),m.push(` }`),m.push(``),m.push(` $wordPrefix = if ([string]::IsNullOrEmpty($wordToComplete)) { '' } else { $wordToComplete }`),m.push(``),m.push(` if ($state.ExpectingValue) {`),m.push(`\t\t${s}_AddEnumResults -Results $results -Flag $state.ValueFlag -WordToComplete $wordPrefix`),m.push(` return $results`),m.push(` }`),m.push(``),m.push(`\t$inlineValue = ${s}_ResolveInlineValueCompletion -PathData $state.PathData -WordToComplete $wordPrefix`),m.push(` if ($null -ne $inlineValue) {`),m.push(`\t\t${s}_AddInlineEnumResults -Results $results -InlineValue $inlineValue -WordToComplete $wordPrefix`),m.push(` return $results`),m.push(` }`),m.push(``),m.push(` if ($wordPrefix.StartsWith('-')) {`),m.push(`\t\t${s}_AddFlagResults -Results $results -PathData $state.PathData -WordToComplete $wordPrefix`),m.push(` return $results`),m.push(` }`),m.push(``),m.push(`\t${s}_AddCommandResults -Results $results -PathData $state.PathData -WordToComplete $wordPrefix`),m.push(`\t${s}_AddFlagResults -Results $results -PathData $state.PathData -WordToComplete $wordPrefix`),m.push(` return $results`),m.push(`}`),m.join(`
2
- `)}function o(e,t,n,r){e.push(`$script:${t} = @{`),s(e,``,n.visibleCommands,{...n.rootFlags,...n.includeDefaultFlags?n.defaultFlags:{}});for(let t of r)s(e,t.path.join(` `),t.children,t.mergedFlags);e.push(`}`)}function s(t,n,r,i){t.push(`\t${l(n)} = @{`),t.push(` Commands = @(`);for(let e of r)t.push(` @{`),t.push(`\t\t\t\tCanonicalName = ${l(e.name)}`),t.push(`\t\t\t\tNames = ${u([e.name,...e.aliases])}`),t.push(`\t\t\t\tDescription = ${l(e.description??e.name)}`),t.push(` }`);t.push(` )`),t.push(` Flags = @(`);for(let[n,r]of Object.entries(i)){let i=d([`--${n}`,...e(r,{kind:`short`}).map(e=>`-${e}`),...e(r,{kind:`long`}).map(e=>`--${e}`)]),a=d([`--${n}`,...e(r,{kind:`short`,includeHidden:!0}).map(e=>`-${e}`),...e(r,{kind:`long`,includeHidden:!0}).map(e=>`--${e}`)]);t.push(` @{`),t.push(`\t\t\t\tCanonicalName = ${l(n)}`),t.push(`\t\t\t\tForms = ${u(i)}`),t.push(`\t\t\t\tParseForms = ${u(a)}`),t.push(`\t\t\t\tRequiresValue = ${r.kind===`boolean`?`$false`:`$true`}`),t.push(`\t\t\t\tDescription = ${l(r.description??n)}`),t.push(`\t\t\t\tEnumValues = ${u(r.enumValues??[])}`),t.push(` }`)}t.push(` )`),t.push(` }`)}function c(e,t,n){e.push(`function ${t}_UnquoteToken {`),e.push(` param([string]$TokenText)`),e.push(` if ($TokenText.Length -lt 2) {`),e.push(` return $TokenText`),e.push(` }`),e.push(``),e.push(` if (($TokenText.StartsWith("'") -and $TokenText.EndsWith("'")) -or`),e.push(` ($TokenText.StartsWith('"') -and $TokenText.EndsWith('"'))) {`),e.push(` return $TokenText.Substring(1, $TokenText.Length - 2)`),e.push(` }`),e.push(``),e.push(` return $TokenText`),e.push(`}`),e.push(``),e.push(`function ${t}_FindCommand {`),e.push(` param($PathData, [string]$Token)`),e.push(` foreach ($command in $PathData.Commands) {`),e.push(` foreach ($name in $command.Names) {`),e.push(` if ($name -eq $Token) {`),e.push(` return $command`),e.push(` }`),e.push(` }`),e.push(` }`),e.push(` return $null`),e.push(`}`),e.push(``),e.push(`function ${t}_ResolveFlagToken {`),e.push(` param($PathData, [string]$Token)`),e.push(` foreach ($flag in $PathData.Flags) {`),e.push(` foreach ($form in $flag.ParseForms) {`),e.push(` if ($Token -eq $form) {`),e.push(` return @{ Flag = $flag; InlinePrefix = $null }`),e.push(` }`),e.push(``),e.push(` if (-not $flag.RequiresValue) {`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` if ($form.StartsWith('--') -and $Token.StartsWith("$form=")) {`),e.push(` return @{ Flag = $flag; InlinePrefix = "$form=" }`),e.push(` }`),e.push(``),e.push(` if ($form.StartsWith('-') -and -not $form.StartsWith('--') -and $Token.StartsWith($form) -and $Token.Length -gt $form.Length) {`),e.push(` return @{ Flag = $flag; InlinePrefix = $form }`),e.push(` }`),e.push(` }`),e.push(` }`),e.push(` return $null`),e.push(`}`),e.push(``),e.push(`function ${t}_GetState {`),e.push(` param([CommandAst]$CommandAst, [int]$CursorPosition)`),e.push(`\t$pathData = $script:${n}[${l(``)}]`),e.push(` $path = ""`),e.push(` $afterSeparator = $false`),e.push(` $expectingValue = $false`),e.push(` $valueFlag = $null`),e.push(` $tokens = [System.Collections.Generic.List[string]]::new()`),e.push(``),e.push(` foreach ($element in $CommandAst.CommandElements | Select-Object -Skip 1) {`),e.push(` if ($element.Extent.EndOffset -ge $CursorPosition) {`),e.push(` break`),e.push(` }`),e.push(`\t\t$tokenText = ${t}_UnquoteToken $element.Extent.Text`),e.push(` [void]$tokens.Add($tokenText)`),e.push(` }`),e.push(``),e.push(` foreach ($token in $tokens) {`),e.push(` if ($expectingValue) {`),e.push(` $expectingValue = $false`),e.push(` $valueFlag = $null`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` if ($token -eq '--') {`),e.push(` $afterSeparator = $true`),e.push(` break`),e.push(` }`),e.push(``),e.push(`\t\t$flagMatch = ${t}_ResolveFlagToken -PathData $pathData -Token $token`),e.push(` if ($null -ne $flagMatch) {`),e.push(` if ($flagMatch.InlinePrefix -eq $null -and $flagMatch.Flag.RequiresValue) {`),e.push(` $expectingValue = $true`),e.push(` $valueFlag = $flagMatch.Flag`),e.push(` }`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` if ($token.StartsWith('-')) {`),e.push(` continue`),e.push(` }`),e.push(``),e.push(`\t\t$command = ${t}_FindCommand -PathData $pathData -Token $token`),e.push(` if ($null -eq $command) {`),e.push(` break`),e.push(` }`),e.push(``),e.push(` $path = if ([string]::IsNullOrEmpty($path)) {`),e.push(` $command.CanonicalName`),e.push(` } else {`),e.push(` "$path $($command.CanonicalName)"`),e.push(` }`),e.push(`\t\t$nextPathData = $script:${n}[$path]`),e.push(` if ($null -eq $nextPathData) {`),e.push(` break`),e.push(` }`),e.push(` $pathData = $nextPathData`),e.push(` }`),e.push(``),e.push(` return @{`),e.push(` Path = $path`),e.push(` PathData = $pathData`),e.push(` AfterSeparator = $afterSeparator`),e.push(` ExpectingValue = $expectingValue`),e.push(` ValueFlag = $valueFlag`),e.push(` }`),e.push(`}`),e.push(``),e.push(`function ${t}_ResolveInlineValueCompletion {`),e.push(` param($PathData, [string]$WordToComplete)`),e.push(`\t$flagMatch = ${t}_ResolveFlagToken -PathData $PathData -Token $WordToComplete`),e.push(` if ($null -eq $flagMatch -or $flagMatch.InlinePrefix -eq $null) {`),e.push(` return $null`),e.push(` }`),e.push(` return $flagMatch`),e.push(`}`),e.push(``),e.push(`function ${t}_FormatCompletionValue {`),e.push(` param([string]$Value)`),e.push(` if ($Value.Length -eq 0) {`),e.push(` return "''"`),e.push(` }`),e.push(``),e.push(` if ($Value -match '^[a-zA-Z0-9_./:\\\\-]+$') {`),e.push(` return $Value`),e.push(` }`),e.push(``),e.push(` return "'$([CodeGeneration]::EscapeSingleQuotedStringContent($Value))'"`),e.push(`}`),e.push(``),e.push(`function ${t}_MatchesCompletionPrefix {`),e.push(` param([string]$WordToComplete, [string]$RawText, [string]$CompletionText)`),e.push(` if ([string]::IsNullOrEmpty($WordToComplete)) {`),e.push(` return $true`),e.push(` }`),e.push(``),e.push(` return $RawText.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase) -or $CompletionText.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase)`),e.push(`}`),e.push(``),e.push(`function ${t}_AddCommandResults {`),e.push(` param($Results, $PathData, [string]$WordToComplete)`),e.push(` foreach ($command in $PathData.Commands) {`),e.push(` foreach ($name in $command.Names) {`),e.push(` if (-not [string]::IsNullOrEmpty($WordToComplete) -and -not $name.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase)) {`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` $Results.Add([CompletionResult]::new(`),e.push(` $name,`),e.push(` $name,`),e.push(` [CompletionResultType]::Command,`),e.push(` $command.Description`),e.push(` ))`),e.push(` }`),e.push(` }`),e.push(`}`),e.push(``),e.push(`function ${t}_AddFlagResults {`),e.push(` param($Results, $PathData, [string]$WordToComplete)`),e.push(` foreach ($flag in $PathData.Flags) {`),e.push(` foreach ($form in $flag.Forms) {`),e.push(` if (-not [string]::IsNullOrEmpty($WordToComplete) -and -not $form.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase)) {`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` $Results.Add([CompletionResult]::new(`),e.push(` $form,`),e.push(` $form,`),e.push(` [CompletionResultType]::ParameterName,`),e.push(` $flag.Description`),e.push(` ))`),e.push(` }`),e.push(` }`),e.push(`}`),e.push(``),e.push(`function ${t}_AddEnumResults {`),e.push(` param($Results, $Flag, [string]$WordToComplete)`),e.push(` foreach ($value in $Flag.EnumValues) {`),e.push(`\t\t$completionText = ${t}_FormatCompletionValue -Value $value`),e.push(`\t\tif (-not (${t}_MatchesCompletionPrefix -WordToComplete $WordToComplete -RawText $value -CompletionText $completionText)) {`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` $Results.Add([CompletionResult]::new(`),e.push(` $completionText,`),e.push(` $value,`),e.push(` [CompletionResultType]::ParameterValue,`),e.push(` $Flag.Description`),e.push(` ))`),e.push(` }`),e.push(`}`),e.push(``),e.push(`function ${t}_AddInlineEnumResults {`),e.push(` param($Results, $InlineValue, [string]$WordToComplete)`),e.push(` foreach ($value in $InlineValue.Flag.EnumValues) {`),e.push(` $rawCompletion = "$($InlineValue.InlinePrefix)$value"`),e.push(`\t\t$formattedValue = ${t}_FormatCompletionValue -Value $value`),e.push(` $completionText = "$($InlineValue.InlinePrefix)$formattedValue"`),e.push(`\t\tif (-not (${t}_MatchesCompletionPrefix -WordToComplete $WordToComplete -RawText $rawCompletion -CompletionText $completionText)) {`),e.push(` continue`),e.push(` }`),e.push(``),e.push(` $Results.Add([CompletionResult]::new(`),e.push(` $completionText,`),e.push(` $value,`),e.push(` [CompletionResultType]::ParameterValue,`),e.push(` $InlineValue.Flag.Description`),e.push(` ))`),e.push(` }`),e.push(`}`)}function l(e){return`'${e.replace(/'/g,`''`)}'`}function u(e){return e.length===0?`@()`:`@(${e.map(l).join(`, `)})`}function d(e){return[...new Set(e)]}export{a as generatePowerShellCompletion};
1
+ import { getFlagAliasNames } from "../../schema/flag.mjs";
2
+ import { resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
+ //#region src/core/completion/shells/powershell.ts
4
+ /**
5
+ * Generate a PowerShell completion script for the CLI.
6
+ *
7
+ * @param schema - The CLI schema.
8
+ * @param options - Optional generator configuration.
9
+ * @returns A complete PowerShell completion script.
10
+ */
11
+ function generatePowerShellCompletion(schema, options) {
12
+ const helperPrefix = `__${sanitizeShellIdentifier(options?.functionPrefix ?? schema.name)}_completions`;
13
+ const dataVarName = `${helperPrefix}_paths`;
14
+ const rootSurface = resolveRootCompletionSurface(schema, options?.rootMode);
15
+ const visibleCommands = rootSurface.visibleCommands;
16
+ const nodes = walkCommandTree(visibleCommands);
17
+ const lines = [];
18
+ lines.push(`# PowerShell completion for ${schema.name}`);
19
+ lines.push(`# Generated by ${versionTag()}`);
20
+ lines.push("#");
21
+ lines.push("# Install for the current session:");
22
+ lines.push(`# ${schema.name} completions powershell | Out-String | Invoke-Expression`);
23
+ lines.push("#");
24
+ lines.push("# Install permanently:");
25
+ lines.push(`# ${schema.name} completions powershell > $PROFILE.CurrentUserCurrentHost`);
26
+ lines.push("");
27
+ lines.push("using namespace System.Management.Automation");
28
+ lines.push("using namespace System.Management.Automation.Language");
29
+ lines.push("");
30
+ emitPowerShellPathTable(lines, dataVarName, rootSurface, nodes);
31
+ lines.push("");
32
+ emitPowerShellHelpers(lines, helperPrefix, dataVarName);
33
+ lines.push("");
34
+ lines.push(`Register-ArgumentCompleter -Native -CommandName ${quotePowerShellString(schema.name)} -ScriptBlock {`);
35
+ lines.push(" param($wordToComplete, $commandAst, $cursorPosition)");
36
+ lines.push(`\t$state = ${helperPrefix}_GetState -CommandAst $commandAst -CursorPosition $cursorPosition`);
37
+ lines.push(" if ($null -eq $state.PathData) {");
38
+ lines.push(" return");
39
+ lines.push(" }");
40
+ lines.push("");
41
+ lines.push(" $results = [System.Collections.Generic.List[CompletionResult]]::new()");
42
+ lines.push(" if ($state.AfterSeparator) {");
43
+ lines.push(" return $results");
44
+ lines.push(" }");
45
+ lines.push("");
46
+ lines.push(`\t$wordPrefix = if ([string]::IsNullOrEmpty($wordToComplete)) { '' } else { $wordToComplete }`);
47
+ lines.push("");
48
+ lines.push(" if ($state.ExpectingValue) {");
49
+ lines.push(`\t\t${helperPrefix}_AddEnumResults -Results $results -Flag $state.ValueFlag -WordToComplete $wordPrefix`);
50
+ lines.push(" return $results");
51
+ lines.push(" }");
52
+ lines.push("");
53
+ lines.push(`\t$inlineValue = ${helperPrefix}_ResolveInlineValueCompletion -PathData $state.PathData -WordToComplete $wordPrefix`);
54
+ lines.push(" if ($null -ne $inlineValue) {");
55
+ lines.push(`\t\t${helperPrefix}_AddInlineEnumResults -Results $results -InlineValue $inlineValue -WordToComplete $wordPrefix`);
56
+ lines.push(" return $results");
57
+ lines.push(" }");
58
+ lines.push("");
59
+ lines.push(" if ($wordPrefix.StartsWith('-')) {");
60
+ lines.push(`\t\t${helperPrefix}_AddFlagResults -Results $results -PathData $state.PathData -WordToComplete $wordPrefix`);
61
+ lines.push(" return $results");
62
+ lines.push(" }");
63
+ lines.push("");
64
+ lines.push(`\t${helperPrefix}_AddCommandResults -Results $results -PathData $state.PathData -WordToComplete $wordPrefix`);
65
+ lines.push(`\t${helperPrefix}_AddFlagResults -Results $results -PathData $state.PathData -WordToComplete $wordPrefix`);
66
+ lines.push(" return $results");
67
+ lines.push("}");
68
+ return lines.join("\n");
69
+ }
70
+ function emitPowerShellPathTable(lines, dataVarName, rootSurface, nodes) {
71
+ lines.push(`$script:${dataVarName} = @{`);
72
+ appendPowerShellPathEntry(lines, "", rootSurface.visibleCommands, {
73
+ ...rootSurface.rootFlags,
74
+ ...rootSurface.includeDefaultFlags ? rootSurface.defaultFlags : {}
75
+ });
76
+ for (const node of nodes) appendPowerShellPathEntry(lines, node.path.join(" "), node.children, node.mergedFlags);
77
+ lines.push("}");
78
+ }
79
+ function appendPowerShellPathEntry(lines, path, commands, flags) {
80
+ lines.push(`\t${quotePowerShellString(path)} = @{`);
81
+ lines.push(" Commands = @(");
82
+ for (const command of commands) {
83
+ lines.push(" @{");
84
+ lines.push(`\t\t\t\tCanonicalName = ${quotePowerShellString(command.name)}`);
85
+ lines.push(`\t\t\t\tNames = ${formatPowerShellArray([command.name, ...command.aliases])}`);
86
+ lines.push(`\t\t\t\tDescription = ${quotePowerShellString(command.description ?? command.name)}`);
87
+ lines.push(" }");
88
+ }
89
+ lines.push(" )");
90
+ lines.push(" Flags = @(");
91
+ for (const [name, schema] of Object.entries(flags)) {
92
+ const forms = dedupeValues([
93
+ `--${name}`,
94
+ ...getFlagAliasNames(schema, { kind: "short" }).map((alias) => `-${alias}`),
95
+ ...getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`)
96
+ ]);
97
+ const parseForms = dedupeValues([
98
+ `--${name}`,
99
+ ...getFlagAliasNames(schema, {
100
+ kind: "short",
101
+ includeHidden: true
102
+ }).map((alias) => `-${alias}`),
103
+ ...getFlagAliasNames(schema, {
104
+ kind: "long",
105
+ includeHidden: true
106
+ }).map((alias) => `--${alias}`)
107
+ ]);
108
+ lines.push(" @{");
109
+ lines.push(`\t\t\t\tCanonicalName = ${quotePowerShellString(name)}`);
110
+ lines.push(`\t\t\t\tForms = ${formatPowerShellArray(forms)}`);
111
+ lines.push(`\t\t\t\tParseForms = ${formatPowerShellArray(parseForms)}`);
112
+ lines.push(`\t\t\t\tRequiresValue = ${schema.kind === "boolean" ? "$false" : "$true"}`);
113
+ lines.push(`\t\t\t\tDescription = ${quotePowerShellString(schema.description ?? name)}`);
114
+ lines.push(`\t\t\t\tEnumValues = ${formatPowerShellArray(schema.enumValues ?? [])}`);
115
+ lines.push(" }");
116
+ }
117
+ lines.push(" )");
118
+ lines.push(" }");
119
+ }
120
+ function emitPowerShellHelpers(lines, helperPrefix, dataVarName) {
121
+ lines.push(`function ${helperPrefix}_UnquoteToken {`);
122
+ lines.push(" param([string]$TokenText)");
123
+ lines.push(" if ($TokenText.Length -lt 2) {");
124
+ lines.push(" return $TokenText");
125
+ lines.push(" }");
126
+ lines.push("");
127
+ lines.push(" if (($TokenText.StartsWith(\"'\") -and $TokenText.EndsWith(\"'\")) -or");
128
+ lines.push(" ($TokenText.StartsWith('\"') -and $TokenText.EndsWith('\"'))) {");
129
+ lines.push(" return $TokenText.Substring(1, $TokenText.Length - 2)");
130
+ lines.push(" }");
131
+ lines.push("");
132
+ lines.push(" return $TokenText");
133
+ lines.push("}");
134
+ lines.push("");
135
+ lines.push(`function ${helperPrefix}_FindCommand {`);
136
+ lines.push(" param($PathData, [string]$Token)");
137
+ lines.push(" foreach ($command in $PathData.Commands) {");
138
+ lines.push(" foreach ($name in $command.Names) {");
139
+ lines.push(" if ($name -eq $Token) {");
140
+ lines.push(" return $command");
141
+ lines.push(" }");
142
+ lines.push(" }");
143
+ lines.push(" }");
144
+ lines.push(" return $null");
145
+ lines.push("}");
146
+ lines.push("");
147
+ lines.push(`function ${helperPrefix}_ResolveFlagToken {`);
148
+ lines.push(" param($PathData, [string]$Token)");
149
+ lines.push(" foreach ($flag in $PathData.Flags) {");
150
+ lines.push(" foreach ($form in $flag.ParseForms) {");
151
+ lines.push(" if ($Token -eq $form) {");
152
+ lines.push(" return @{ Flag = $flag; InlinePrefix = $null }");
153
+ lines.push(" }");
154
+ lines.push("");
155
+ lines.push(" if (-not $flag.RequiresValue) {");
156
+ lines.push(" continue");
157
+ lines.push(" }");
158
+ lines.push("");
159
+ lines.push(" if ($form.StartsWith('--') -and $Token.StartsWith(\"$form=\")) {");
160
+ lines.push(" return @{ Flag = $flag; InlinePrefix = \"$form=\" }");
161
+ lines.push(" }");
162
+ lines.push("");
163
+ lines.push(" if ($form.StartsWith('-') -and -not $form.StartsWith('--') -and $Token.StartsWith($form) -and $Token.Length -gt $form.Length) {");
164
+ lines.push(" return @{ Flag = $flag; InlinePrefix = $form }");
165
+ lines.push(" }");
166
+ lines.push(" }");
167
+ lines.push(" }");
168
+ lines.push(" return $null");
169
+ lines.push("}");
170
+ lines.push("");
171
+ lines.push(`function ${helperPrefix}_GetState {`);
172
+ lines.push(" param([CommandAst]$CommandAst, [int]$CursorPosition)");
173
+ lines.push(`\t$pathData = $script:${dataVarName}[${quotePowerShellString("")}]`);
174
+ lines.push(" $path = \"\"");
175
+ lines.push(" $afterSeparator = $false");
176
+ lines.push(" $expectingValue = $false");
177
+ lines.push(" $valueFlag = $null");
178
+ lines.push(" $tokens = [System.Collections.Generic.List[string]]::new()");
179
+ lines.push("");
180
+ lines.push(" foreach ($element in $CommandAst.CommandElements | Select-Object -Skip 1) {");
181
+ lines.push(" if ($element.Extent.EndOffset -ge $CursorPosition) {");
182
+ lines.push(" break");
183
+ lines.push(" }");
184
+ lines.push(`\t\t$tokenText = ${helperPrefix}_UnquoteToken $element.Extent.Text`);
185
+ lines.push(" [void]$tokens.Add($tokenText)");
186
+ lines.push(" }");
187
+ lines.push("");
188
+ lines.push(" foreach ($token in $tokens) {");
189
+ lines.push(" if ($expectingValue) {");
190
+ lines.push(" $expectingValue = $false");
191
+ lines.push(" $valueFlag = $null");
192
+ lines.push(" continue");
193
+ lines.push(" }");
194
+ lines.push("");
195
+ lines.push(" if ($token -eq '--') {");
196
+ lines.push(" $afterSeparator = $true");
197
+ lines.push(" break");
198
+ lines.push(" }");
199
+ lines.push("");
200
+ lines.push(`\t\t$flagMatch = ${helperPrefix}_ResolveFlagToken -PathData $pathData -Token $token`);
201
+ lines.push(" if ($null -ne $flagMatch) {");
202
+ lines.push(" if ($flagMatch.InlinePrefix -eq $null -and $flagMatch.Flag.RequiresValue) {");
203
+ lines.push(" $expectingValue = $true");
204
+ lines.push(" $valueFlag = $flagMatch.Flag");
205
+ lines.push(" }");
206
+ lines.push(" continue");
207
+ lines.push(" }");
208
+ lines.push("");
209
+ lines.push(" if ($token.StartsWith('-')) {");
210
+ lines.push(" continue");
211
+ lines.push(" }");
212
+ lines.push("");
213
+ lines.push(`\t\t$command = ${helperPrefix}_FindCommand -PathData $pathData -Token $token`);
214
+ lines.push(" if ($null -eq $command) {");
215
+ lines.push(" break");
216
+ lines.push(" }");
217
+ lines.push("");
218
+ lines.push(" $path = if ([string]::IsNullOrEmpty($path)) {");
219
+ lines.push(" $command.CanonicalName");
220
+ lines.push(" } else {");
221
+ lines.push(" \"$path $($command.CanonicalName)\"");
222
+ lines.push(" }");
223
+ lines.push(`\t\t$nextPathData = $script:${dataVarName}[$path]`);
224
+ lines.push(" if ($null -eq $nextPathData) {");
225
+ lines.push(" break");
226
+ lines.push(" }");
227
+ lines.push(" $pathData = $nextPathData");
228
+ lines.push(" }");
229
+ lines.push("");
230
+ lines.push(" return @{");
231
+ lines.push(" Path = $path");
232
+ lines.push(" PathData = $pathData");
233
+ lines.push(" AfterSeparator = $afterSeparator");
234
+ lines.push(" ExpectingValue = $expectingValue");
235
+ lines.push(" ValueFlag = $valueFlag");
236
+ lines.push(" }");
237
+ lines.push("}");
238
+ lines.push("");
239
+ lines.push(`function ${helperPrefix}_ResolveInlineValueCompletion {`);
240
+ lines.push(" param($PathData, [string]$WordToComplete)");
241
+ lines.push(`\t$flagMatch = ${helperPrefix}_ResolveFlagToken -PathData $PathData -Token $WordToComplete`);
242
+ lines.push(" if ($null -eq $flagMatch -or $flagMatch.InlinePrefix -eq $null) {");
243
+ lines.push(" return $null");
244
+ lines.push(" }");
245
+ lines.push(" return $flagMatch");
246
+ lines.push("}");
247
+ lines.push("");
248
+ lines.push(`function ${helperPrefix}_FormatCompletionValue {`);
249
+ lines.push(" param([string]$Value)");
250
+ lines.push(" if ($Value.Length -eq 0) {");
251
+ lines.push(" return \"''\"");
252
+ lines.push(" }");
253
+ lines.push("");
254
+ lines.push(" if ($Value -match '^[a-zA-Z0-9_./:\\\\-]+$') {");
255
+ lines.push(" return $Value");
256
+ lines.push(" }");
257
+ lines.push("");
258
+ lines.push(" return \"'$([CodeGeneration]::EscapeSingleQuotedStringContent($Value))'\"");
259
+ lines.push("}");
260
+ lines.push("");
261
+ lines.push(`function ${helperPrefix}_MatchesCompletionPrefix {`);
262
+ lines.push(" param([string]$WordToComplete, [string]$RawText, [string]$CompletionText)");
263
+ lines.push(" if ([string]::IsNullOrEmpty($WordToComplete)) {");
264
+ lines.push(" return $true");
265
+ lines.push(" }");
266
+ lines.push("");
267
+ lines.push(" return $RawText.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase) -or $CompletionText.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase)");
268
+ lines.push("}");
269
+ lines.push("");
270
+ lines.push(`function ${helperPrefix}_AddCommandResults {`);
271
+ lines.push(" param($Results, $PathData, [string]$WordToComplete)");
272
+ lines.push(" foreach ($command in $PathData.Commands) {");
273
+ lines.push(" foreach ($name in $command.Names) {");
274
+ lines.push(" if (-not [string]::IsNullOrEmpty($WordToComplete) -and -not $name.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase)) {");
275
+ lines.push(" continue");
276
+ lines.push(" }");
277
+ lines.push("");
278
+ lines.push(" $Results.Add([CompletionResult]::new(");
279
+ lines.push(" $name,");
280
+ lines.push(" $name,");
281
+ lines.push(" [CompletionResultType]::Command,");
282
+ lines.push(" $command.Description");
283
+ lines.push(" ))");
284
+ lines.push(" }");
285
+ lines.push(" }");
286
+ lines.push("}");
287
+ lines.push("");
288
+ lines.push(`function ${helperPrefix}_AddFlagResults {`);
289
+ lines.push(" param($Results, $PathData, [string]$WordToComplete)");
290
+ lines.push(" foreach ($flag in $PathData.Flags) {");
291
+ lines.push(" foreach ($form in $flag.Forms) {");
292
+ lines.push(" if (-not [string]::IsNullOrEmpty($WordToComplete) -and -not $form.StartsWith($WordToComplete, [System.StringComparison]::OrdinalIgnoreCase)) {");
293
+ lines.push(" continue");
294
+ lines.push(" }");
295
+ lines.push("");
296
+ lines.push(" $Results.Add([CompletionResult]::new(");
297
+ lines.push(" $form,");
298
+ lines.push(" $form,");
299
+ lines.push(" [CompletionResultType]::ParameterName,");
300
+ lines.push(" $flag.Description");
301
+ lines.push(" ))");
302
+ lines.push(" }");
303
+ lines.push(" }");
304
+ lines.push("}");
305
+ lines.push("");
306
+ lines.push(`function ${helperPrefix}_AddEnumResults {`);
307
+ lines.push(" param($Results, $Flag, [string]$WordToComplete)");
308
+ lines.push(" foreach ($value in $Flag.EnumValues) {");
309
+ lines.push(`\t\t$completionText = ${helperPrefix}_FormatCompletionValue -Value $value`);
310
+ lines.push(`\t\tif (-not (${helperPrefix}_MatchesCompletionPrefix -WordToComplete $WordToComplete -RawText $value -CompletionText $completionText)) {`);
311
+ lines.push(" continue");
312
+ lines.push(" }");
313
+ lines.push("");
314
+ lines.push(" $Results.Add([CompletionResult]::new(");
315
+ lines.push(" $completionText,");
316
+ lines.push(" $value,");
317
+ lines.push(" [CompletionResultType]::ParameterValue,");
318
+ lines.push(" $Flag.Description");
319
+ lines.push(" ))");
320
+ lines.push(" }");
321
+ lines.push("}");
322
+ lines.push("");
323
+ lines.push(`function ${helperPrefix}_AddInlineEnumResults {`);
324
+ lines.push(" param($Results, $InlineValue, [string]$WordToComplete)");
325
+ lines.push(" foreach ($value in $InlineValue.Flag.EnumValues) {");
326
+ lines.push(" $rawCompletion = \"$($InlineValue.InlinePrefix)$value\"");
327
+ lines.push(`\t\t$formattedValue = ${helperPrefix}_FormatCompletionValue -Value $value`);
328
+ lines.push(" $completionText = \"$($InlineValue.InlinePrefix)$formattedValue\"");
329
+ lines.push(`\t\tif (-not (${helperPrefix}_MatchesCompletionPrefix -WordToComplete $WordToComplete -RawText $rawCompletion -CompletionText $completionText)) {`);
330
+ lines.push(" continue");
331
+ lines.push(" }");
332
+ lines.push("");
333
+ lines.push(" $Results.Add([CompletionResult]::new(");
334
+ lines.push(" $completionText,");
335
+ lines.push(" $value,");
336
+ lines.push(" [CompletionResultType]::ParameterValue,");
337
+ lines.push(" $InlineValue.Flag.Description");
338
+ lines.push(" ))");
339
+ lines.push(" }");
340
+ lines.push("}");
341
+ }
342
+ function quotePowerShellString(value) {
343
+ return `'${value.replace(/'/g, "''")}'`;
344
+ }
345
+ function formatPowerShellArray(values) {
346
+ if (values.length === 0) return "@()";
347
+ return `@(${values.map(quotePowerShellString).join(", ")})`;
348
+ }
349
+ function dedupeValues(values) {
350
+ return [...new Set(values)];
351
+ }
352
+ //#endregion
353
+ export { generatePowerShellCompletion };
@@ -33,6 +33,16 @@ interface CompletionOptions {
33
33
  * ```
34
34
  */
35
35
  readonly functionPrefix?: string;
36
+ /**
37
+ * Where the built-in shell completion is exposed.
38
+ *
39
+ * - `'command'` registers a `completions` subcommand (the default).
40
+ * - `'flag'` exposes an eager `--completions <shell>` flag on the CLI root
41
+ * instead, keeping the root free of a `completions` subcommand.
42
+ *
43
+ * @defaultValue `'command'`
44
+ */
45
+ readonly as?: 'command' | 'flag';
36
46
  /**
37
47
  * Controls which root-level surface shell completion exposes when a
38
48
  * default command exists.
@@ -1 +1,154 @@
1
- import{collectPropagatedFlags as e}from"../../cli/propagate.mjs";import{resolveRootSurface as t}from"../../cli/root-surface.mjs";import{DREAMCLI_REVISION as n,DREAMCLI_VERSION as r}from"../../../version.mjs";function i(){return`@kjanat/dreamcli v${r}${` (${n})`}`}function a(e,n=`subcommands`){let r=t(e),i=o(e.version!==void 0),a=r.visibleDefaultCommand?.flags??{},s=n===`surface`?r.visibleDefaultCommand!==void 0:r.hasSingleVisibleDefault;return{visibleCommands:r.visibleCommands,visibleDefaultCommand:r.visibleDefaultCommand,rootFlags:i,defaultFlags:a,includeDefaultFlags:s}}function o(e){return{help:s(`Show help text`),...e?{version:s(`Show version`)}:{}}}function s(e){return{kind:`boolean`,presence:`optional`,defaultValue:void 0,aliases:[],envVar:void 0,configPath:void 0,description:e,enumValues:void 0,elementSchema:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1}}function c(t,n=[]){let r=[];for(let i of t){if(i.hidden)continue;let t=[...n,i],a=e(t),o={...a,...i.flags},s=i.commands.filter(e=>!e.hidden);r.push({path:t.map(e=>e.name),schema:i,propagatedFlags:a,mergedFlags:o,children:s}),s.length>0&&r.push(...c(s,t))}return r}function l(e){let t=e.replace(/[^a-zA-Z0-9_]/g,`_`);if(t===e)return t;let n=2166136261;for(let t=0;t<e.length;t+=1)n^=e.charCodeAt(t),n=Math.imul(n,16777619);return`${t}_${(n>>>0).toString(16).padStart(8,`0`)}`}function u(e){return/^[a-zA-Z0-9_\-.]+$/.test(e)?e:`'${e.replace(/'/g,`'\\''`)}'`}export{u as quoteShellArg,a as resolveRootCompletionSurface,l as sanitizeShellIdentifier,i as versionTag,c as walkCommandTree};
1
+ import { collectPropagatedFlags } from "../../cli/propagate.mjs";
2
+ import { resolveRootSurface } from "../../cli/root-surface.mjs";
3
+ import { DREAMCLI_REVISION, DREAMCLI_VERSION } from "../../../version.mjs";
4
+ //#region src/core/completion/shells/shared.ts
5
+ /**
6
+ * Shared infrastructure for shell completion generators.
7
+ *
8
+ * Provides the command tree walker, shell escaping utilities, and
9
+ * the version tag used in generated script headers. Consumed by
10
+ * the per-shell generators in sibling files.
11
+ *
12
+ * @module dreamcli/core/completion/shells/shared
13
+ * @internal
14
+ */
15
+ /**
16
+ * Format a version tag for generated completion script headers.
17
+ *
18
+ * Produces e.g. `"@kjanat/dreamcli v0.9.1 (f9b5f1a)"` when built, or
19
+ * `"@kjanat/dreamcli"` when running unbundled in development.
20
+ *
21
+ * @internal
22
+ */
23
+ function versionTag() {
24
+ return `@kjanat/dreamcli v${DREAMCLI_VERSION}${` (${DREAMCLI_REVISION})`}`;
25
+ }
26
+ /**
27
+ * Resolve the root-level completion surface from the CLI schema and policy.
28
+ *
29
+ * @internal
30
+ */
31
+ function resolveRootCompletionSurface(schema, rootMode = "subcommands") {
32
+ const rootSurface = resolveRootSurface(schema);
33
+ const rootFlags = createRootFlags(schema.version !== void 0);
34
+ const defaultFlags = rootSurface.visibleDefaultCommand?.flags ?? {};
35
+ const includeDefaultFlags = rootMode === "surface" ? rootSurface.hasVisibleDefault : rootSurface.hasVisibleDefault && !rootSurface.hasVisibleSubcommands;
36
+ const defaultCommand = rootSurface.visibleDefaultCommand;
37
+ const alreadyListed = defaultCommand !== void 0 && rootSurface.visibleCommands.some((c) => c.name === defaultCommand.name);
38
+ return {
39
+ visibleCommands: defaultCommand !== void 0 && !alreadyListed ? [defaultCommand, ...rootSurface.visibleCommands] : rootSurface.visibleCommands,
40
+ visibleDefaultCommand: rootSurface.visibleDefaultCommand,
41
+ rootFlags,
42
+ defaultFlags,
43
+ includeDefaultFlags
44
+ };
45
+ }
46
+ /**
47
+ * Build the synthetic root-level flags (`--help`, optionally `--version`).
48
+ *
49
+ * @param hasVersion - Whether to include a `--version` flag.
50
+ * @returns A record of root flag schemas.
51
+ * @internal
52
+ */
53
+ function createRootFlags(hasVersion) {
54
+ return {
55
+ help: createSyntheticRootFlag("Show help text"),
56
+ ...hasVersion ? { version: createSyntheticRootFlag("Show version") } : {}
57
+ };
58
+ }
59
+ /**
60
+ * Create a minimal boolean {@link FlagSchema} for a synthetic root flag.
61
+ *
62
+ * @param description - Help text for the flag.
63
+ * @returns A complete flag schema with all optional fields defaulted.
64
+ * @internal
65
+ */
66
+ function createSyntheticRootFlag(description) {
67
+ return {
68
+ kind: "boolean",
69
+ presence: "optional",
70
+ defaultValue: void 0,
71
+ aliases: [],
72
+ envVar: void 0,
73
+ configPath: void 0,
74
+ description,
75
+ enumValues: void 0,
76
+ numberConstraints: void 0,
77
+ elementSchema: void 0,
78
+ prompt: void 0,
79
+ parseFn: void 0,
80
+ deprecated: void 0,
81
+ propagate: false
82
+ };
83
+ }
84
+ /**
85
+ * Walk the command tree depth-first, producing a flat list of
86
+ * {@link CommandNode}s with propagated flag context.
87
+ *
88
+ * @param topLevel - Top-level visible command schemas.
89
+ * @param ancestorSchemas - Schema path from root (for propagation calculation).
90
+ * @returns Flat list of all visible nodes in the tree.
91
+ *
92
+ * @internal
93
+ */
94
+ function walkCommandTree(topLevel, ancestorSchemas = []) {
95
+ const nodes = [];
96
+ for (const schema of topLevel) {
97
+ if (schema.hidden) continue;
98
+ const fullPath = [...ancestorSchemas, schema];
99
+ const propagatedFlags = collectPropagatedFlags(fullPath);
100
+ const mergedFlags = {
101
+ ...propagatedFlags,
102
+ ...schema.flags
103
+ };
104
+ const children = schema.commands.filter((c) => !c.hidden);
105
+ nodes.push({
106
+ path: fullPath.map((s) => s.name),
107
+ schema,
108
+ propagatedFlags,
109
+ mergedFlags,
110
+ children
111
+ });
112
+ if (children.length > 0) nodes.push(...walkCommandTree(children, fullPath));
113
+ }
114
+ return nodes;
115
+ }
116
+ /**
117
+ * Sanitize a string for use as a shell function identifier.
118
+ * Replaces non-alphanumeric/underscore characters with underscores.
119
+ * When sanitization changes the name, appends a short stable hash suffix so
120
+ * distinct originals cannot collide on the same helper identifier.
121
+ * Used by both bash and zsh generators.
122
+ *
123
+ * @internal
124
+ */
125
+ function sanitizeShellIdentifier(name) {
126
+ const sanitized = name.replace(/[^a-zA-Z0-9_]/g, "_");
127
+ if (sanitized === name) return sanitized;
128
+ let hash = 2166136261;
129
+ for (let i = 0; i < name.length; i += 1) {
130
+ hash ^= name.charCodeAt(i);
131
+ hash = Math.imul(hash, 16777619);
132
+ }
133
+ return `${sanitized}_${(hash >>> 0).toString(16).padStart(8, "0")}`;
134
+ }
135
+ /**
136
+ * Quote a string for safe interpolation into a shell script.
137
+ *
138
+ * Uses single-quote wrapping with the standard `'\''` idiom for
139
+ * embedded single quotes. This prevents shell injection from CLI
140
+ * names containing spaces, semicolons, backticks, or other
141
+ * special characters.
142
+ *
143
+ * Returns the input unquoted if it consists only of shell-safe
144
+ * characters (`[a-zA-Z0-9_\-.]`), avoiding unnecessary noise
145
+ * in generated scripts for common CLI names like `my-cli` or `app.v2`.
146
+ *
147
+ * @internal
148
+ */
149
+ function quoteShellArg(value) {
150
+ if (/^[a-zA-Z0-9_\-.]+$/.test(value)) return value;
151
+ return `'${value.replace(/'/g, "'\\''")}'`;
152
+ }
153
+ //#endregion
154
+ export { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };