@kjanat/dreamcli 2.4.1 → 3.0.0-rc.1

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 (94) hide show
  1. package/CHANGELOG.md +169 -1
  2. package/README.md +14 -7
  3. package/dist/core/cli/index.d.mts +283 -81
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +31 -5
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/config/index.d.mts +2 -2
  18. package/dist/core/config/package-json.d.mts +93 -20
  19. package/dist/core/config/package-json.mjs +3 -1
  20. package/dist/core/help/index.d.mts +45 -1
  21. package/dist/core/help/index.mjs +6 -6
  22. package/dist/core/json-schema/index.mjs +1 -1
  23. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  24. package/dist/core/parse/index.d.mts +15 -1
  25. package/dist/core/parse/index.mjs +1 -1
  26. package/dist/core/prompt/index.d.mts +11 -3
  27. package/dist/core/prompt/index.mjs +3 -3
  28. package/dist/core/resolve/coerce.mjs +1 -1
  29. package/dist/core/resolve/flags.mjs +1 -1
  30. package/dist/core/resolve/property.d.mts +2 -0
  31. package/dist/core/resolve/property.mjs +1 -1
  32. package/dist/core/schema/arg.d.mts +90 -10
  33. package/dist/core/schema/arg.mjs +1 -1
  34. package/dist/core/schema/command.d.mts +3 -1
  35. package/dist/core/schema/flag.d.mts +92 -2
  36. package/dist/core/schema/flag.mjs +1 -1
  37. package/dist/core/schema/index.d.mts +2 -1
  38. package/dist/core/schema/number-constraints.d.mts +96 -0
  39. package/dist/core/schema/number-constraints.mjs +1 -0
  40. package/dist/core/schema/prompt.d.mts +15 -0
  41. package/dist/core/schema/run.d.mts +4 -4
  42. package/dist/core/testkit/index.d.mts +9 -5
  43. package/dist/core/testkit/index.mjs +1 -1
  44. package/dist/index.d.mts +4 -3
  45. package/dist/index.mjs +1 -1
  46. package/dist/runtime/auto.mjs +1 -1
  47. package/dist/runtime/bun.mjs +1 -1
  48. package/dist/runtime/deno.mjs +2 -2
  49. package/dist/runtime/node.mjs +2 -2
  50. package/dist/version.mjs +1 -1
  51. package/examples/basic.ts +5 -1
  52. package/examples/gh/package.json +2 -7
  53. package/examples/pwsh-demo/package.json +1 -7
  54. package/examples/pwsh-demo/src/main.test.ts +1 -4
  55. package/examples/pwsh-demo/src/main.ts +14 -4
  56. package/examples/transport-launcher.ts +85 -0
  57. package/package.json +15 -24
  58. package/src/core/cli/dispatch.ts +7 -1
  59. package/src/core/cli/index.ts +521 -122
  60. package/src/core/cli/planner.ts +192 -23
  61. package/src/core/cli/root-help.ts +195 -105
  62. package/src/core/cli/root-surface.ts +25 -12
  63. package/src/core/cli/runtime-preflight.ts +43 -8
  64. package/src/core/completion/index.ts +50 -0
  65. package/src/core/completion/shells/powershell.ts +2 -2
  66. package/src/core/completion/shells/shared.ts +30 -3
  67. package/src/core/config/index.ts +12 -2
  68. package/src/core/config/package-json.ts +250 -41
  69. package/src/core/execution/index.ts +1 -4
  70. package/src/core/help/index.ts +57 -10
  71. package/src/core/json-schema/index.ts +23 -4
  72. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  73. package/src/core/parse/index.ts +62 -1
  74. package/src/core/prompt/index.ts +54 -14
  75. package/src/core/resolve/coerce.ts +73 -5
  76. package/src/core/resolve/flags.ts +14 -0
  77. package/src/core/resolve/property.ts +4 -4
  78. package/src/core/schema/arg.ts +125 -3
  79. package/src/core/schema/command.ts +3 -1
  80. package/src/core/schema/flag.ts +120 -4
  81. package/src/core/schema/index.ts +5 -0
  82. package/src/core/schema/number-constraints.ts +153 -0
  83. package/src/core/schema/prompt.ts +15 -0
  84. package/src/core/schema/run.ts +4 -4
  85. package/src/core/testkit/index.ts +32 -8
  86. package/src/index.ts +8 -0
  87. package/src/runtime/auto.ts +0 -24
  88. package/src/runtime/bun.ts +0 -7
  89. package/src/runtime/deno.ts +0 -2
  90. package/src/runtime/node.ts +0 -11
  91. package/src/runtime/support.ts +1 -59
  92. package/src/schema.ts +16 -0
  93. package/dist/runtime/support.d.mts +0 -42
  94. package/dist/runtime/support.mjs +0 -1
@@ -1 +1 @@
1
- import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{buildFlagLookup as r,flagExpectsValue as i,includesBeforeSeparator as a}from"../parse/index.mjs";import{dispatch as o,findClosestCommand as s}from"./dispatch.mjs";function c(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function l(e){let n=new Map,r=(e,r)=>{let i=n.get(e);if(i!==void 0)throw new t(`Duplicate root command route '${e}' (${i.schema.name} and ${r.schema.name})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure root command names and aliases are unique`});n.set(e,r)};for(let t of e){r(t.schema.name,t);for(let e of t.schema.aliases)r(e,t)}return n}function u(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function d(e){return{command:e.command,mergedSchema:u(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function f(e,t,n,r,i,a){return{kind:`match`,plan:d({command:t,commandPath:n,argv:r,meta:c(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function p(e,t){return t===``||e.schema.args.length>0}function m(e,t){let n=r(t);for(let t=0;t<e.length;t++){let r=e[t];if(r===void 0||r===`--`||r===`-`||!r.startsWith(`-`))return;if(r.startsWith(`--`)){let e=r.indexOf(`=`),a=r.slice(2,e===-1?void 0:e),o=n.get(a);if(o===void 0)return e===-1?r:`--${a}`;e===-1&&i(o[1])&&t++;continue}let a=r.slice(1);for(let e=0;e<a.length;e++){let r=a.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(i(o[1])){e===a.length-1&&t++;break}}}}function h(e){let i=e.argv.indexOf(`--`),c=i===-1?e.argv:e.argv.slice(0,i),u=i===-1?[]:e.argv.slice(i),d=c.includes(`--json`)?c.filter(e=>e!==`--json`):c,g=i===-1?d:[...d,...u];if(e.schema.version!==void 0&&(a(e.argv,`--version`)||a(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};let _=g[0];if(_===`--help`||_===`-h`)return{kind:`root-help`,help:e.help};if(_===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=g.slice(1);return t.length===0?{kind:`root-help`,help:e.help}:h({...e,argv:[...t,`--help`]})}if(_===void 0&&e.schema.defaultCommand===void 0)return{kind:`root-help`,help:e.help};if(e.schema.commands.length===0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() before calling .run()`})};let v=e.schema.defaultCommand,y=v===void 0?void 0:r(v.schema.flags),b=o(g,l(e.schema.commands),[],y);switch(b.kind){case`unknown`:{if(v!==void 0&&b.parentPath.length===0){if((b.input===``?void 0:s(b.input,b.candidates))===void 0&&p(v,b.input))return f(e.schema,v,[v.schema],g,e.help,e.output);let t=m(g,v.schema.flags);if(t!==void 0)return{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}if(b.input===``){let t=g.find(e=>e.startsWith(`-`));return t===void 0?{kind:`root-help`,help:e.help}:{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}let t=s(b.input,b.candidates),r=b.parentPath.length>0?`${e.schema.name} ${b.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${b.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=b.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:b.command,commandPath:b.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return f(e.schema,b.command,b.commandPath,b.remainingArgv,e.help,e.output)}}export{h as planInvocation};
1
+ import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{normalizeShell as r}from"../completion/index.mjs";import{buildFlagLookup as i,flagExpectsValue as a,includesBeforeSeparator as o}from"../parse/index.mjs";import{dispatch as s,findClosestCommand as c}from"./dispatch.mjs";function l(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function u(e){let n=new Map,r=(e,r)=>{let i=n.get(e);if(i!==void 0)throw new t(`Duplicate root command route '${e}' (${i.schema.name} and ${r.schema.name})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure root command names and aliases are unique`});n.set(e,r)};for(let t of e){r(t.schema.name,t);for(let e of t.schema.aliases)r(e,t)}return n}function d(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function f(e){return{command:e.command,mergedSchema:d(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function p(e,t,n,r,i,a){return{kind:`match`,plan:f({command:t,commandPath:n,argv:r,meta:l(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function m(e,t){return t===``||e.schema.args.length>0}function h(e,t){let n=i(t);for(let t=0;t<e.length;t++){let r=e[t];if(r===void 0||r===`--`||r===`-`||!r.startsWith(`-`))return;if(r.startsWith(`--`)){let e=r.indexOf(`=`),i=r.slice(2,e===-1?void 0:e),o=n.get(i);if(o===void 0)return e===-1?r:`--${i}`;e===-1&&a(o[1])&&t++;continue}let i=r.slice(1);for(let e=0;e<i.length;e++){let r=i.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(a(o[1])){e===i.length-1&&t++;break}}}}function g(e,t){for(let n=0;n<e.length;n++){let r=e[n];if(r===void 0)continue;if(r===`--help`||r===`-h`)return{helpBeforeCommand:!0,firstCommandToken:void 0,commandTokenIndex:-1};if(r===`-`||!r.startsWith(`-`))return{helpBeforeCommand:!1,firstCommandToken:r,commandTokenIndex:n};if(r.startsWith(`--`)){let e=r.indexOf(`=`),i=r.slice(2,e===-1?void 0:e),o=t?.get(i);o!==void 0&&e===-1&&a(o[1])&&n++;continue}let i=r.slice(1);for(let e=0;e<i.length;e++){let r=t?.get(i.charAt(e));if(!(r===void 0||!a(r[1]))){e===i.length-1&&n++;break}}}return{helpBeforeCommand:!1,firstCommandToken:void 0,commandTokenIndex:-1}}function _(e,t){let i=e.indexOf(`--`),a=i===-1?e.length:i;for(let i=0;i<a;i++){let o=e[i];if(o===void 0)continue;let s;if(o===`--completions`){let t=i+1<a?e[i+1]:void 0;s=t!==void 0&&!t.startsWith(`-`)?t:void 0}else if(o.startsWith(`--completions=`))s=o.slice(14);else continue;if(s===void 0||s===``)return{kind:`root-completions`,shell:void 0,options:t.options};let c=r(s);return c===void 0||!t.shells.includes(c)?{kind:`dispatch-error`,error:new n(`Unknown shell '${s}'`,{code:`INVALID_VALUE`,suggest:`Valid shells: ${t.shells.join(`, `)}`})}:{kind:`root-completions`,shell:c,options:t.options}}}function v(e){let r=e.argv.indexOf(`--`),a=r===-1?e.argv:e.argv.slice(0,r),l=r===-1?[]:e.argv.slice(r),d=a.includes(`--json`)?a.filter(e=>e!==`--json`):a,f=r===-1?d:[...d,...l],y=e.schema.defaultCommand,b=y===void 0?void 0:i(y.schema.flags);if(e.schema.version!==void 0&&(o(e.argv,`--version`)||o(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};if(e.schema.completionsFlag!==void 0){let t=_(e.argv,e.schema.completionsFlag);if(t!==void 0)return t}let x=g(d,b);if(x.helpBeforeCommand)return{kind:`root-help`,help:e.help};if(x.firstCommandToken===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=f.slice(x.commandTokenIndex+1);return t.length===0?{kind:`root-help`,help:e.help}:v({...e,argv:[...t,`--help`]})}if(e.schema.commands.length===0&&y===void 0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() or .default() before calling .run()`})};if(f.length===0&&y===void 0)return{kind:`root-help`,help:e.help};let S=s(f,u(e.schema.commands),[],b);switch(S.kind){case`unknown`:{if(y!==void 0&&S.parentPath.length===0){if((S.input===``?void 0:c(S.input,S.candidates))===void 0&&m(y,S.input))return p(e.schema,y,[y.schema],f,e.help,e.output);let t=h(f,y.schema.flags);if(t!==void 0)return{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}if(S.input===``){let t=f.find(e=>e.startsWith(`-`));return t===void 0?{kind:`root-help`,help:e.help}:{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}let t=c(S.input,S.candidates),r=S.parentPath.length>0?`${e.schema.name} ${S.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${S.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=S.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:S.command,commandPath:S.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return p(e.schema,S.command,S.commandPath,S.remainingArgv,e.help,e.output)}}export{v as planInvocation};
@@ -17,13 +17,27 @@ interface CLISchemaLike {
17
17
  readonly name: string | undefined;
18
18
  readonly version: string | undefined;
19
19
  } | undefined;
20
+ readonly completionsFlag?: {
21
+ readonly shells: readonly string[];
22
+ } | undefined;
23
+ /**
24
+ * Config discovery settings. Only its presence is read — defined means
25
+ * `.config()` enabled the built-in `--config <path>` flag, so root help
26
+ * advertises it in `Global options:`.
27
+ */
28
+ readonly configSettings?: {
29
+ readonly appName: string;
30
+ } | undefined;
20
31
  }
21
32
  /**
22
33
  * Generate root-level help text for the CLI program.
23
34
  *
24
35
  * Shows program name, version, description, usage line, and available
25
- * commands. When the default command is the only visible top-level
26
- * command, merges the root summary with that command's detailed help.
36
+ * subcommands. The default command is the CLI's root *surface*: its arguments
37
+ * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
38
+ * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
39
+ * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
40
+ * flag is advertised in the `Flags:` section.
27
41
  *
28
42
  * @internal
29
43
  */
@@ -1,6 +1,4 @@
1
- import{resolveRootSurface as e}from"./root-surface.mjs";import{osc8 as t,padEnd as n,wrapText as r}from"../help/ansi.mjs";import{formatHelpSections as i}from"../help/index.mjs";function a(t,n){let r=n?.width??80,a=n?.hyperlinks===!0,s=e(t);if(s.hasSingleVisibleDefault){let e=s.visibleDefaultCommand;if(e!==void 0){let c=o(t,s.visibleCommands,s.visibleDefaultCommand,r,a),l=c.findIndex(e=>e.startsWith(`Usage: `)),d=[...i(e,{...n,binName:t.name,isDefaultHelp:!0})],f=d.shift();return l!==-1&&f!==void 0&&(c[l]=u(c[l]??``,f)),e.description!==void 0&&t.description!==void 0&&e.description===t.description&&d.shift(),c.push(...d),`${c.join(`
1
+ import{resolveRootSurface as e}from"./root-surface.mjs";import{osc8 as t,padEnd as n,wrapText as r}from"../help/ansi.mjs";import{formatFlagEntriesBlock as i,formatHelpSections as a}from"../help/index.mjs";import{command as o}from"../schema/command.mjs";function s(t,n){let r=n?.width??80,i=n?.binName??t.name,o=n?.hyperlinks===!0,s=n?.inlineDefault??!0,l=n?.showDefaultInCommands??!1,m=e(t),h=m.visibleDefaultCommand,g=!m.hasVisibleSubcommands&&t.completionsFlag===void 0,_=s||g?h:void 0,v=c(t,_),y=v!==void 0,b=[u(t,o)];t.description!==void 0&&b.push(t.description);let x=m.hasVisibleSubcommands?h===void 0?`<command>`:`[command]`:``,S=x.length>0?`Usage: ${i} ${x} [options]`:`Usage: ${i} [options]`,C=[];y&&v!==void 0&&(C=[...a(v,{...n,binName:i,isDefaultHelp:!0})]);let w=C.shift();y&&w!==void 0&&_!==void 0?b.push(m.hasVisibleSubcommands?p(S,w):w):b.push(S);let T=l&&h!==void 0?[...m.visibleSubcommands,h]:m.visibleSubcommands;T.length>0&&b.push(d(T,l?h?.name:void 0,r)),y&&v!==void 0&&(v.description!==void 0&&v.description===t.description&&C[0]===v.description&&C.shift(),b.push(...C));let E=f(t,r);if(E.length>0&&b.push(E),n?.footer??m.hasVisibleSubcommands){let e=m.hasVisibleSubcommands?h===void 0?` <command>`:` [command]`:``;b.push(`Run '${i}${e} --help' for more information.`)}return`${b.join(`
2
2
 
3
- `)}\n`}}let l=o(t,s.visibleCommands,s.visibleDefaultCommand,r,a),d=c(s.visibleCommands,s.visibleDefaultCommand);return l.push(d.length>0?`Run '${t.name} ${d} --help' for more information.`:`Run '${t.name} --help' for more information.`),`${l.join(`
4
-
5
- `)}\n`}function o(e,t,n,r,i){let a=[];a.push(s(e,i)),e.description!==void 0&&a.push(e.description);let o=c(t,n);return a.push(o.length>0?`Usage: ${e.name} ${o} [options]`:`Usage: ${e.name} [options]`),t.length>0&&a.push(l(t,n?.name,r)),a}function s(e,n){let r=n?e.helpLinks:void 0,i=r?.name===void 0?e.name:t(r.name,e.name);if(e.version===void 0)return i;let a=`v${e.version}`;return`${i} ${r?.version===void 0?a:t(r.version,a)}`}function c(e,t){return e.length===0&&t===void 0?``:t===void 0?`<command>`:`[command]`}function l(e,t,i){let a=[`Commands:`],o=0;for(let n of e){let e=n.name===t?10:0,r=n.name.length+e;r>o&&(o=r)}let s=2+o+2;for(let o of e){let e=n(` ${o.name===t?`${o.name} (default)`:o.name}`,s),c=o.description??``;c.length===0?a.push(e.trimEnd()):a.push(`${e}${r(c,i,s)}`)}return a.join(`
6
- `)}function u(e,t){let n=t.startsWith(`Usage: `)?t.slice(7):t;return`${e}\n${` `.repeat(7)}${n}`}export{a as formatRootHelp};
3
+ `)}\n`}function c(e,t){if(e.completionsFlag===void 0)return t;let n=t??o(e.name).schema;return{...n,flags:{completions:l(e.completionsFlag.shells),...n.flags}}}function l(e){return{kind:`enum`,presence:`optional`,defaultValue:void 0,aliases:[],envVar:void 0,configPath:void 0,description:`Print a shell completion script and exit`,enumValues:e,elementSchema:void 0,numberConstraints:void 0,prompt:void 0,parseFn:void 0,deprecated:void 0,propagate:!1}}function u(e,n){let r=n?e.helpLinks:void 0,i=r?.name===void 0?e.name:t(r.name,e.name);if(e.version===void 0)return i;let a=`v${e.version}`;return`${i} ${r?.version===void 0?a:t(r.version,a)}`}function d(e,t,i){let a=[`Commands:`],o=0;for(let n of e){let e=n.name===t?10:0,r=n.name.length+e;r>o&&(o=r)}let s=2+o+2;for(let o of e){let e=n(` ${o.name===t?`${o.name} (default)`:o.name}`,s),c=o.description??``;c.length===0?a.push(e.trimEnd()):a.push(`${e}${r(c,i,s)}`)}return a.join(`
4
+ `)}function f(e,t){let n=[{left:`-h, --help`,description:`Show this help message and exit`}];return e.version!==void 0&&n.push({left:`-V, --version`,description:`Print the version number and exit`}),n.push({left:`--json`,description:`Emit machine-readable JSON output`}),e.configSettings!==void 0&&n.push({left:`--config <path>`,description:`Load configuration from the given file`}),i(`Global options:`,n,t)}function p(e,t){let n=t.startsWith(`Usage: `)?t.slice(7):t;return`${e}\n${` `.repeat(7)}${n}`}export{s as formatRootHelp};
@@ -20,20 +20,35 @@ interface RootSurfaceSchemaLike {
20
20
  /**
21
21
  * Normalized root shape shared by help and completion logic.
22
22
  *
23
+ * Since v0.3 the default command is a distinct root *surface* rather than a
24
+ * named subcommand: `.default()` no longer registers it under
25
+ * {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
26
+ * still place the default in the command list (e.g. hand-built test schemas),
27
+ * {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
28
+ * by excluding the default command from the visible command list.
29
+ *
23
30
  * @internal
24
31
  */
25
32
  interface RootSurface {
33
+ /** All visible top-level commands as declared in `schema.commands`. */
26
34
  readonly visibleCommands: readonly CommandSchema[];
35
+ /** Visible real subcommands — `visibleCommands` minus the default command. */
36
+ readonly visibleSubcommands: readonly CommandSchema[];
37
+ /** The visible default command, or `undefined` when none exists or it is hidden. */
27
38
  readonly visibleDefaultCommand: CommandSchema | undefined;
28
- readonly hasSingleVisibleDefault: boolean;
29
- readonly hasVisibleSiblingCommands: boolean;
39
+ /** Whether a visible default command exists. */
40
+ readonly hasVisibleDefault: boolean;
41
+ /** Whether any visible real subcommands exist (the default does not count). */
42
+ readonly hasVisibleSubcommands: boolean;
30
43
  }
31
44
  /**
32
45
  * Resolve the visible shape of the CLI root.
33
46
  *
34
47
  * Hidden commands are excluded from the visible command list. Hidden
35
48
  * default commands remain executable, but are not surfaced through
36
- * help or completions.
49
+ * help or completions. The default command is reported separately from the
50
+ * real subcommands so help and completion can render it as the root surface
51
+ * instead of echoing it as a pseudo-subcommand.
37
52
  *
38
53
  * @internal
39
54
  */
@@ -1 +1 @@
1
- function e(e){let t=e.commands.map(e=>e.schema).filter(e=>!e.hidden),n=e.defaultCommand?.schema,r=n!==void 0&&!n.hidden?n:void 0;return{visibleCommands:t,visibleDefaultCommand:r,hasSingleVisibleDefault:r!==void 0&&t.length===1&&t[0]?.name===r.name,hasVisibleSiblingCommands:r!==void 0&&t.some(e=>e.name!==r.name)}}export{e as resolveRootSurface};
1
+ function e(e){let t=e.commands.map(e=>e.schema).filter(e=>!e.hidden),n=e.defaultCommand?.schema,r=n!==void 0&&!n.hidden?n:void 0,i=r===void 0?t:t.filter(e=>e.name!==r.name);return{visibleCommands:t,visibleSubcommands:i,visibleDefaultCommand:r,hasVisibleDefault:r!==void 0,hasVisibleSubcommands:i.length>0}}export{e as resolveRootSurface};
@@ -6,6 +6,8 @@ import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
6
6
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
7
7
  import { PackageJsonData } from "../config/package-json.mjs";
8
8
  import { HelpLinks } from "./help-links.mjs";
9
+ import { CompletionOptions } from "../completion/shells/shared.mjs";
10
+ import { Shell } from "../completion/index.mjs";
9
11
  import { FormatLoader } from "../config/index.mjs";
10
12
 
11
13
  //#region src/core/cli/runtime-preflight.d.ts
@@ -16,12 +18,23 @@ interface RuntimeConfigSettings {
16
18
  /** Optional format loaders (JSON/YAML/TOML); `undefined` uses built-in JSON. */
17
19
  readonly loaders: readonly FormatLoader[] | undefined;
18
20
  }
19
- /** Package.json discovery settings extracted from CLISchema. @internal */
20
- interface RuntimePackageJsonSettings {
21
- /** Whether to infer the CLI binary name from `package.json` `bin` field. */
21
+ /**
22
+ * Manifest discovery settings extracted from CLISchema for preflight use.
23
+ *
24
+ * Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
25
+ * named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
26
+ * sibling and avoid colliding with the exported public type.
27
+ * @internal
28
+ */
29
+ interface RuntimeManifestSettings {
30
+ /** Whether to infer the CLI binary name from `bin` keys or `name`. */
22
31
  readonly inferName: boolean;
32
+ /** Strip a leading `@scope/` from the inferred `name` fallback. */
33
+ readonly stripScope: boolean;
23
34
  /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
24
35
  readonly from: string | undefined;
36
+ /** Candidate manifest filenames in priority order. */
37
+ readonly files: readonly string[];
25
38
  /** Pre-loaded data; when set, discovery is skipped entirely. */
26
39
  readonly data: PackageJsonData | undefined;
27
40
  }
@@ -48,11 +61,24 @@ interface RuntimePreflightSchemaLike {
48
61
  /** Config file discovery settings; `undefined` disables config loading. */
49
62
  readonly configSettings: RuntimeConfigSettings | undefined;
50
63
  /** Package.json discovery settings; `undefined` disables package.json inference. */
51
- readonly packageJsonSettings: RuntimePackageJsonSettings | undefined;
64
+ readonly packageJsonSettings: RuntimeManifestSettings | undefined;
52
65
  /** Root-help header link targets; `undefined` fields may be derived from package.json. */
53
66
  readonly helpLinks: HelpLinks | undefined;
54
- /** Whether `.completions()` registered the built-in completions command. */
67
+ /** Whether `.completions()` registered the built-in completions command/flag. */
55
68
  readonly hasBuiltInCompletions: boolean;
69
+ /** Eager `--completions <shell>` flag config; `undefined` disables interception. */
70
+ readonly completionsFlag: {
71
+ readonly shells: readonly Shell[];
72
+ readonly options: CompletionOptions | undefined;
73
+ } | undefined;
74
+ /** Consumer-configured root-help defaults. */
75
+ readonly helpConfig: {
76
+ readonly inlineDefault?: boolean;
77
+ readonly showDefaultInCommands?: boolean;
78
+ readonly footer?: boolean;
79
+ readonly width?: number;
80
+ readonly hyperlinks?: boolean;
81
+ } | undefined;
56
82
  /** Plugins forwarded into the execution pipeline. */
57
83
  readonly plugins: readonly CLIPlugin[];
58
84
  }
@@ -1 +1 @@
1
- import{CLIError as e,ParseError as t}from"../errors/index.mjs";import{parse as n}from"../parse/index.mjs";import{createTerminalPrompter as r}from"../prompt/index.mjs";import{discoverPackageJson as i,inferCliName as a}from"../config/package-json.mjs";import{deriveHelpLinks as o}from"./help-links.mjs";import{planInvocation as s}from"./planner.mjs";import{discoverConfig as c}from"../config/index.mjs";const l={jsonMode:!1,isTTY:!1,verbosity:`normal`};function u(e){let t=[],n;for(let r=0;r<e.length;r+=1){let i=e[r];if(i!==void 0){if(i===`--`){t.push(...e.slice(r));break}if(n===void 0&&i.startsWith(`--config=`)){let e=i.slice(9);if(e.length>0){n=e;continue}t.push(i);continue}if(n===void 0&&i===`--config`){let a=e[r+1];if(a!==void 0&&!a.startsWith(`-`)&&a!==`--`){n=a,r+=1;continue}t.push(i);continue}t.push(i)}}return{configPath:n,filteredArgv:t}}function d(e,r){if(r.includes(`--help`)||r.includes(`-h`))return!1;try{let t=n(e,r);return e.args.some(({name:e,schema:n})=>{let r=t.args[e];return n.stdinMode&&(r===void 0||r===`-`)})}catch(e){if(e instanceof t)return!1;throw e}}function f(e,t){let n=s({schema:e,argv:t,help:{binName:e.name},output:l});switch(n.kind){case`match`:return d(n.plan.mergedSchema,n.plan.argv);case`dispatch-error`:case`needs-subcommand`:case`root-help`:case`root-version`:return!1}}function p(e,t){if(!e.hasBuiltInCompletions)return!1;let n=s({schema:e,argv:t,help:{binName:e.name},output:l});return n.kind===`match`&&n.plan.command.schema.name===`completions`}async function m(e,t,n,r){let s=e.packageJsonSettings,c=s!==void 0&&!r?await(async()=>{let n=s.data??await i(t,s.from);if(n===null)return e;let r=s.inferName?a(n):void 0;return{...e,...e.version===void 0&&n.version!==void 0?{version:n.version}:{},...e.description===void 0&&n.description!==void 0?{description:n.description}:{},...r===void 0?{}:{name:r},helpLinks:o(e.helpLinks,n,e.version??n.version)}})():e;return n===void 0?c:{...c,name:n}}async function h(t,n,r,i,a){if(t.configSettings===void 0||i||a!==void 0)return a;try{let e=await c(t.configSettings.appName,n,{...r===void 0?{}:{configPath:r},...t.configSettings.loaders===void 0?{}:{loaders:t.configSettings.loaders}});return e.found?e.data:void 0}catch(t){if(t instanceof e)return t;throw t}}async function g(t){let n=t.adapter.argv.slice(2),{configPath:i,filteredArgv:a}=t.schema.configSettings===void 0?{configPath:void 0,filteredArgv:n}:u(n),o=a.includes(`--json`)||t.options?.jsonMode===!0,s=p(t.schema,a),c=await m(t.schema,t.adapter,t.inheritedName,s),l=await h(c,t.adapter,i,s,t.options?.config);if(l instanceof e)return{kind:`config-error`,error:l,jsonMode:o};let d=t.options?.prompter===void 0&&t.adapter.stdinIsTTY?r(t.adapter.stdin,t.adapter.stderr):void 0,g=t.options?.stdinData===void 0&&f(c,a)?await t.adapter.readStdin():t.options?.stdinData;return{kind:`ready`,schema:c,filteredArgv:a,inputs:{env:t.options?.env??t.adapter.env,isTTY:t.options?.isTTY??t.adapter.isTTY,jsonMode:o,verbosity:t.options?.verbosity??`normal`,...g===void 0?{}:{stdinData:g},...t.options?.prompter===void 0?d===void 0?{}:{prompter:d}:{prompter:t.options.prompter},...l===void 0?{}:{config:l}}}}export{g as prepareRuntimePreflight};
1
+ import{CLIError as e,ParseError as t}from"../errors/index.mjs";import{parse as n}from"../parse/index.mjs";import{createTerminalPrompter as r}from"../prompt/index.mjs";import{discoverManifest as i,inferCliName as a}from"../config/package-json.mjs";import{deriveHelpLinks as o}from"./help-links.mjs";import{planInvocation as s}from"./planner.mjs";import{discoverConfig as c}from"../config/index.mjs";const l={jsonMode:!1,isTTY:!1,verbosity:`normal`};function u(e){let t=[],n;for(let r=0;r<e.length;r+=1){let i=e[r];if(i!==void 0){if(i===`--`){t.push(...e.slice(r));break}if(n===void 0&&i.startsWith(`--config=`)){let e=i.slice(9);if(e.length>0){n=e;continue}t.push(i);continue}if(n===void 0&&i===`--config`){let a=e[r+1];if(a!==void 0&&!a.startsWith(`-`)&&a!==`--`){n=a,r+=1;continue}t.push(i);continue}t.push(i)}}return{configPath:n,filteredArgv:t}}function d(e,r){if(r.includes(`--help`)||r.includes(`-h`))return!1;try{let t=n(e,r);return e.args.some(({name:e,schema:n})=>{let r=t.args[e];return n.stdinMode&&(r===void 0||r===`-`)})}catch(e){if(e instanceof t)return!1;throw e}}function f(e,t){let n=s({schema:e,argv:t,help:{binName:e.name},output:l});switch(n.kind){case`match`:return d(n.plan.mergedSchema,n.plan.argv);case`dispatch-error`:case`needs-subcommand`:case`root-help`:case`root-version`:case`root-completions`:return!1}}function p(e,t){if(!e.hasBuiltInCompletions)return!1;let n=s({schema:e,argv:t,help:{binName:e.name},output:l});return n.kind===`match`&&n.plan.command.schema.name===`completions`}async function m(e,t,n,r){let s=e.packageJsonSettings,c=s!==void 0&&!r?await(async()=>{let n=s.data??await i(t,{...s.from===void 0?{}:{startDir:s.from},files:s.files});if(n===null)return e;let r=s.inferName?a(n,{stripScope:s.stripScope}):void 0;return{...e,...e.version===void 0&&n.version!==void 0?{version:n.version}:{},...e.description===void 0&&n.description!==void 0?{description:n.description}:{},...r===void 0?{}:{name:r},helpLinks:o(e.helpLinks,n,e.version??n.version)}})():e;return n===void 0?c:{...c,name:n}}async function h(t,n,r,i,a){if(t.configSettings===void 0||i||a!==void 0)return a;try{let e=await c(t.configSettings.appName,n,{...r===void 0?{}:{configPath:r},...t.configSettings.loaders===void 0?{}:{loaders:t.configSettings.loaders}});return e.found?e.data:void 0}catch(t){if(t instanceof e)return t;throw t}}async function g(t){let n=t.adapter.argv.slice(2),{configPath:i,filteredArgv:a}=t.schema.configSettings===void 0?{configPath:void 0,filteredArgv:n}:u(n),o=a.includes(`--json`)||t.options?.jsonMode===!0,s=p(t.schema,a),c=await m(t.schema,t.adapter,t.inheritedName,s),l=await h(c,t.adapter,i,s,t.options?.config);if(l instanceof e)return{kind:`config-error`,error:l,jsonMode:o};let d=t.options?.prompter===void 0&&t.adapter.stdinIsTTY?r(t.adapter.stdin,t.adapter.stderr):void 0,g=t.options?.stdinData===void 0&&f(c,a)?await t.adapter.readStdin():t.options?.stdinData;return{kind:`ready`,schema:c,filteredArgv:a,inputs:{env:t.options?.env??t.adapter.env,isTTY:t.options?.isTTY??t.adapter.isTTY,jsonMode:o,verbosity:t.options?.verbosity??`normal`,...g===void 0?{}:{stdinData:g},...t.options?.prompter===void 0?d===void 0?{}:{prompter:d}:{prompter:t.options.prompter},...l===void 0?{}:{config:l}}}}export{g as prepareRuntimePreflight};
@@ -22,6 +22,37 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
22
22
  * @see {@link Shell} for the union type matching these entries.
23
23
  */
24
24
  declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
25
+ /**
26
+ * Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
27
+ * (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
28
+ * {@link Shell}, or `undefined` when it does not map to one.
29
+ *
30
+ * Mirrors the matching used by the `completions` subcommand so the subcommand
31
+ * and the eager `--completions <shell>` flag accept exactly the same inputs.
32
+ *
33
+ * @param raw - User-supplied shell token or interpreter path.
34
+ * @returns The resolved {@link Shell}, or `undefined` if unrecognized.
35
+ */
36
+ declare function normalizeShell(raw: string): Shell | undefined;
37
+ /**
38
+ * Auto-detect the current shell from environment variables.
39
+ *
40
+ * Resolution order:
41
+ * 1. `$SHELL` parsed as an interpreter path (`/bin/zsh` → `zsh`). It wins when
42
+ * it names a shell we support — a pwsh session launched from bash inherits
43
+ * `SHELL=/bin/bash`, and the login shell the user opted into should be
44
+ * honored over the fallback.
45
+ * 2. Otherwise, the presence of `$PSModulePath` signals PowerShell. PowerShell
46
+ * never sets `$SHELL` on any platform but always exports `PSModulePath` for
47
+ * module discovery, so it is the reliable pwsh signal.
48
+ *
49
+ * Returns `undefined` when no signal resolves, leaving the caller to ask the
50
+ * user for an explicit shell.
51
+ *
52
+ * @param env - Environment record (e.g. `process.env` or an adapter's env).
53
+ * @returns The detected {@link Shell}, or `undefined`.
54
+ */
55
+ declare function detectShell(env: Readonly<Record<string, string | undefined>>): Shell | undefined;
25
56
  /**
26
57
  * Generate a completion script for the given shell.
27
58
  *
@@ -43,4 +74,4 @@ declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
43
74
  */
44
75
  declare function generateCompletion(schema: CLISchema, shell: Shell, options?: CompletionOptions): string;
45
76
  //#endregion
46
- export { type CompletionOptions, SHELLS, type Shell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion };
77
+ export { type CompletionOptions, SHELLS, type Shell, detectShell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion, normalizeShell };
@@ -1 +1 @@
1
- import{generateBashCompletion as e}from"./shells/bash.mjs";import{generateFishCompletion as t}from"./shells/fish.mjs";import{generatePowerShellCompletion as n}from"./shells/powershell.mjs";import{generateZshCompletion as r}from"./shells/zsh.mjs";const i=Object.freeze([`bash`,`zsh`,`fish`,`powershell`]);function a(i,a,o){switch(a){case`bash`:return e(i,o);case`zsh`:return r(i,o);case`fish`:return t(i,o);case`powershell`:return n(i,o)}}export{i as SHELLS,a as generateCompletion};
1
+ import{generateBashCompletion as e}from"./shells/bash.mjs";import{generateFishCompletion as t}from"./shells/fish.mjs";import{generatePowerShellCompletion as n}from"./shells/powershell.mjs";import{generateZshCompletion as r}from"./shells/zsh.mjs";const i=Object.freeze([`bash`,`zsh`,`fish`,`powershell`]);function a(e){let t=e.split(/[\\/]/),n=(t[t.length-1]??e).replace(/\.(?:exe|cmd|bat)$/i,``);return n===`pwsh`?`powershell`:i.includes(n)?n:void 0}function o(e){let t=e.SHELL,n=t!==void 0&&t!==``?a(t):void 0;if(n!==void 0)return n;if(e.PSModulePath!==void 0)return`powershell`}function s(i,a,o){switch(a){case`bash`:return e(i,o);case`zsh`:return r(i,o);case`fish`:return t(i,o);case`powershell`:return n(i,o)}}export{i as SHELLS,o as detectShell,s as generateCompletion,a as normalizeShell};
@@ -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 @@
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 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.hasVisibleDefault:r.hasVisibleDefault&&!r.hasVisibleSubcommands,c=r.visibleDefaultCommand,l=c!==void 0&&r.visibleCommands.some(e=>e.name===c.name);return{visibleCommands:c!==void 0&&!l?[c,...r.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,numberConstraints: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,5 +1,5 @@
1
1
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
- import { PackageJsonAdapter, PackageJsonData, PackageRepository, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
2
+ import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
3
 
4
4
  //#region src/core/config/index.d.ts
5
5
  /**
@@ -158,4 +158,4 @@ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options
158
158
  */
159
159
  declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
160
160
  //#endregion
161
- export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type FormatLoader, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, buildConfigSearchPaths, configFormat, discoverConfig, discoverPackageJson, inferCliName, packageRepositoryUrl };
161
+ export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -39,26 +39,88 @@ interface PackageJsonData {
39
39
  * dependency explicit.
40
40
  */
41
41
  type PackageJsonAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd'>;
42
+ /** Options for {@link discoverManifest}. */
43
+ interface ManifestDiscoveryOptions {
44
+ /**
45
+ * Explicit directory or file path to walk up from. Defaults to
46
+ * `adapter.cwd` when omitted. Pass an absolute path inside your own package
47
+ * (e.g. `fileURLToPath(import.meta.url)`) for installable CLIs whose version
48
+ * should reflect the CLI's own package, not the consumer's working directory.
49
+ *
50
+ * This low-level helper takes a resolved path **string** only. The builder
51
+ * sugar `CLIBuilder.manifest({ from })` exposes the same anchor under the name
52
+ * `from` and additionally accepts a `file:` URL string or `URL` instance,
53
+ * normalizing it to a path first.
54
+ */
55
+ readonly startDir?: string;
56
+ /**
57
+ * Candidate manifest filenames, in per-directory priority order
58
+ * (e.g. `['deno.json', 'jsr.json']`). At each directory the first existing
59
+ * file that carries CLI metadata wins, so the nearest manifest directory
60
+ * always takes precedence over file order. A file that parses but holds no
61
+ * recognised metadata (e.g. a config-only `deno.json` with just
62
+ * `tasks`/`imports`) is skipped, so a sibling `jsr.json` — or a manifest
63
+ * higher up — can still be found. Defaults to `['package.json']`.
64
+ *
65
+ * An empty list is a deliberate no-op: with no candidates to probe, the
66
+ * walk-up reads nothing and resolves to `null` (consistent with the
67
+ * "returns `null` when no manifest is found" contract).
68
+ */
69
+ readonly files?: readonly string[];
70
+ }
71
+ /**
72
+ * Discover the nearest manifest (`package.json`, `deno.json`, `jsr.json`, …)
73
+ * by walking up from `startDir` (or `adapter.cwd` when omitted).
74
+ *
75
+ * Convenience helper behind `CLIBuilder.manifest()`. Most apps should let the
76
+ * CLI runtime discover metadata automatically; call this directly when testing
77
+ * metadata inference or embedding the behavior in custom tooling.
78
+ *
79
+ * Candidate files are parsed as JSON with a JSONC fallback — `package.json`,
80
+ * `deno.json`, `jsr.json`, and `deno.jsonc` all qualify, including files that
81
+ * carry `//` / block comments or trailing commas (common in `deno.json`). A
82
+ * file that fails both parses is skipped, so discovery keeps probing.
83
+ *
84
+ * Returns the parsed metadata on success, `null` when no manifest is found
85
+ * (not an error). Malformed JSON, non-object roots, and config-only manifests
86
+ * that carry no recognised metadata (e.g. a `deno.json` with only `tasks` /
87
+ * `imports`) are all skipped, so discovery keeps probing the remaining
88
+ * candidate files and parent directories — the feature is a convenience, not a
89
+ * hard requirement.
90
+ *
91
+ * @param adapter - Adapter providing `readFile` + `cwd`.
92
+ * @param options - Optional anchor (`startDir`) and candidate filenames (`files`).
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * import { discoverManifest } from '@kjanat/dreamcli';
97
+ *
98
+ * const meta = await discoverManifest(adapter, { files: ['deno.json', 'jsr.json'] });
99
+ * if (meta !== null) {
100
+ * console.log(meta.version); // '1.2.3'
101
+ * }
102
+ * ```
103
+ */
104
+ declare function discoverManifest(adapter: PackageJsonAdapter, options?: ManifestDiscoveryOptions): Promise<PackageJsonData | null>;
42
105
  /**
43
106
  * Discover the nearest `package.json` by walking up from `startDir` (or
44
107
  * `adapter.cwd` when omitted).
45
108
  *
46
- * Convenience helper behind `CLIBuilder.packageJson()`. Most apps should let
47
- * the CLI runtime discover package metadata automatically; call this directly
48
- * when testing metadata inference or embedding the behavior in custom tooling.
109
+ * @deprecated Use {@link discoverManifest} with `{ files: ['package.json'] }`
110
+ * (the default), which also supports `deno.json` / `jsr.json`.
49
111
  *
50
- * Returns the parsed metadata on success, `null` when no `package.json`
51
- * is found (not an error). Malformed JSON and non-object roots also
52
- * return `null` — the feature is a convenience, not a hard requirement.
112
+ * Behavior note (changed by the manifest generalization): a parseable but
113
+ * metadata-less `package.json` — `{}`, or one carrying only non-metadata fields
114
+ * such as `dependencies` / `scripts` / `type` — is no longer treated as a
115
+ * discovery hit. Previously such a file halted the walk-up and resolved to `{}`;
116
+ * now it is skipped and the walk-up CONTINUES to parent directories. In a
117
+ * monorepo this means a metadata-less leaf `package.json` no longer shadows an
118
+ * ancestor manifest, so an ancestor's `version` can surface where the old
119
+ * behavior returned `{}`. Pass pre-loaded `data` (or use {@link discoverManifest}
120
+ * with an explicit `startDir`) when you need to pin discovery to one directory.
53
121
  *
54
122
  * @param adapter - Adapter providing `readFile` + `cwd`.
55
123
  * @param startDir - Optional explicit directory or file path to walk up from.
56
- * Pass an absolute path inside your own package (e.g.
57
- * `fileURLToPath(import.meta.url)`) when authoring an installable CLI whose
58
- * version should reflect the CLI's own package, not the consumer's working
59
- * directory. Defaults to `adapter.cwd` when `undefined`. A file path is
60
- * probed as a directory first (yielding nothing) before the walk-up reaches
61
- * its real parent directory, so passing `import.meta.url` resolves correctly.
62
124
  *
63
125
  * @example
64
126
  * ```ts
@@ -91,23 +153,34 @@ declare function discoverPackageJson(adapter: PackageJsonAdapter, startDir?: str
91
153
  */
92
154
  declare function packageRepositoryUrl(pkg: PackageJsonData): string | undefined;
93
155
  /**
94
- * Infer the CLI binary name from package.json data.
156
+ * Infer the CLI binary name from manifest data.
95
157
  *
96
158
  * Resolution order:
97
159
  * 1. First key of `bin` object (e.g. `{"mycli": "./dist/cli.js"}` → `"mycli"`)
98
- * 2. Package `name` with scope stripped (e.g. `"@scope/mycli"` → `"mycli"`)
160
+ * 2. Package `name`, scope stripped by default (e.g. `"@scope/mycli"` → `"mycli"`);
161
+ * pass `{ stripScope: false }` to keep the full scoped name
99
162
  * 3. `undefined` if neither exists
100
163
  *
164
+ * Note: `bin` keys are never scoped, so `stripScope` only affects the `name`
165
+ * fallback (relevant for `deno.json` / `jsr.json`, which have no `bin` field).
166
+ *
167
+ * @param pkg - Parsed manifest metadata.
168
+ * @param options - `stripScope` (default `true`): strip a leading `@scope/`
169
+ * from the `name` fallback.
170
+ *
101
171
  * @example
102
172
  * ```ts
103
173
  * import { inferCliName } from '@kjanat/dreamcli';
104
174
  *
105
- * inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
106
- * inferCliName({ name: '@scope/mycli' }); // 'mycli'
107
- * inferCliName({ name: 'mycli' }); // 'mycli'
108
- * inferCliName({}); // undefined
175
+ * inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
176
+ * inferCliName({ name: '@scope/mycli' }); // 'mycli'
177
+ * inferCliName({ name: '@scope/mycli' }, { stripScope: false }); // '@scope/mycli'
178
+ * inferCliName({ name: 'mycli' }); // 'mycli'
179
+ * inferCliName({}); // undefined
109
180
  * ```
110
181
  */
111
- declare function inferCliName(pkg: PackageJsonData): string | undefined;
182
+ declare function inferCliName(pkg: PackageJsonData, options?: {
183
+ readonly stripScope?: boolean;
184
+ }): string | undefined;
112
185
  //#endregion
113
- export { type PackageJsonAdapter, type PackageJsonData, type PackageRepository, discoverPackageJson, inferCliName, packageRepositoryUrl };
186
+ export { type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -1 +1,3 @@
1
- import{stripTrailing as e}from"../../strings.mjs";function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e){let t=e.lastIndexOf(`/`),n=e.lastIndexOf(`\\`),r=Math.max(t,n),i=n>t?`\\`:`/`;if(r<0)return;if(r===0)return e.length>1?i:void 0;let a=e.slice(0,r);if(a.length===2&&a[1]===`:`){let t=`${a}${i}`;return t===e?void 0:t}return a}function r(e,t){let n=e.includes(`\\`)?`\\`:`/`;return e.endsWith(n)?`${e}${t}`:`${e}${n}${t}`}async function i(e,t){let i=t??e.cwd;for(;i!==void 0;){let t=null;try{t=await e.readFile(r(i,`package.json`))}catch{}if(t!==null){let e=a(t);if(e!==null)return e}i=n(i)}return null}function a(e){try{let n=JSON.parse(e);if(!t(n))return null;let r=typeof n.name==`string`?n.name:void 0,i=typeof n.version==`string`?n.version:void 0,a=typeof n.description==`string`?n.description:void 0,c=o(n.bin),l=typeof n.homepage==`string`?n.homepage:void 0,u=s(n.repository);return{...r===void 0?{}:{name:r},...i===void 0?{}:{version:i},...a===void 0?{}:{description:a},...c===void 0?{}:{bin:c},...l===void 0?{}:{homepage:l},...u===void 0?{}:{repository:u}}}catch{return null}}function o(e){if(typeof e==`string`)return e;if(!t(e))return;let n={};for(let[t,r]of Object.entries(e)){if(typeof r!=`string`)return;n[t]=r}return n}function s(e){if(typeof e==`string`)return e;if(!t(e))return;let n=typeof e.type==`string`?e.type:void 0,r=typeof e.url==`string`?e.url:void 0,i=typeof e.directory==`string`?e.directory:void 0;if(!(n===void 0&&r===void 0&&i===void 0))return{...n===void 0?{}:{type:n},...r===void 0?{}:{url:r},...i===void 0?{}:{directory:i}}}const c={github:`https://github.com`,gitlab:`https://gitlab.com`,bitbucket:`https://bitbucket.org`};function l(e){return e.endsWith(`.git`)?e.slice(0,-4):e}function u(t){let n=typeof t.repository==`string`?t.repository:t.repository?.url;if(n===void 0)return;let r=n.trim();if(r.length===0)return;let i=/^(github|gitlab|bitbucket):([^/]+\/[^/]+)$/.exec(r);if(i!==null&&i[1]!==void 0&&i[2]!==void 0){let e=c[i[1]];if(e!==void 0)return`${e}/${l(i[2])}`}if(/^[\w.-]+\/[\w.-]+$/.test(r))return`https://github.com/${l(r)}`;r.startsWith(`git+`)&&(r=r.slice(4));let a=/^git@([^:/]+):(.+)$/.exec(r);if(a!==null&&a[1]!==void 0&&a[2]!==void 0)return`https://${a[1]}/${l(e(a[2],[47]))}`;if(/^(?:https?|git|ssh):\/\//.test(r))try{let t=new URL(r),n=l(e(t.pathname,[47]));return`https://${t.hostname}${n}`}catch{return}}function d(e){if(typeof e.bin==`object`){let t=Object.keys(e.bin);if(t.length>0&&t[0]!==void 0)return t[0]}if(e.name!==void 0){let t=e.name.indexOf(`/`);return t>=0?e.name.slice(t+1):e.name}}export{i as discoverPackageJson,d as inferCliName,u as packageRepositoryUrl};
1
+ import{stripTrailing as e}from"../../strings.mjs";function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e){let t=e.lastIndexOf(`/`),n=e.lastIndexOf(`\\`),r=Math.max(t,n),i=n>t?`\\`:`/`;if(r<0)return;if(r===0)return e.length>1?i:void 0;let a=e.slice(0,r);if(a.length===2&&a[1]===`:`){let t=`${a}${i}`;return t===e?void 0:t}return a}function r(e,t){let n=e.includes(`\\`)?`\\`:`/`;return e.endsWith(n)?`${e}${t}`:`${e}${n}${t}`}const i=[`package.json`];function a(e){return e.name!==void 0||e.version!==void 0||e.description!==void 0||e.bin!==void 0||e.homepage!==void 0||e.repository!==void 0}async function o(e,t={}){let o=t.files??i,s=t.startDir??e.cwd;for(;s!==void 0;){for(let t of o){let n=null;try{n=await e.readFile(r(s,t))}catch{}if(n!==null){let e=u(n);if(e!==null&&a(e))return e}}s=n(s)}return null}async function s(e,t){return o(e,t===void 0?{}:{startDir:t})}function c(e){return e===` `||e===` `||e===`
2
+ `||e===`\r`}function l(e){let t=``,n=!1,r=!1;for(let i=0;i<e.length;i+=1){let a=e[i]??``;if(n){t+=a,r?r=!1:a===`\\`?r=!0:a===`"`&&(n=!1);continue}if(a===`"`){n=!0,t+=a;continue}if(a===`/`&&e[i+1]===`/`){for(i+=2;i<e.length&&e[i]!==`
3
+ `;)i+=1;--i;continue}if(a===`/`&&e[i+1]===`*`){for(i+=2;i<e.length&&!(e[i]===`*`&&e[i+1]===`/`);)i+=1;i+=1;continue}t+=a}let i=``;n=!1,r=!1;for(let e=0;e<t.length;e+=1){let a=t[e]??``;if(n){i+=a,r?r=!1:a===`\\`?r=!0:a===`"`&&(n=!1);continue}if(a===`"`){n=!0,i+=a;continue}if(a===`,`){let n=e+1;for(;n<t.length&&c(t[n]??``);)n+=1;let r=t[n];if(r===`}`||r===`]`)continue}i+=a}return i}function u(e){let n;try{n=JSON.parse(e)}catch{try{n=JSON.parse(l(e))}catch{return null}}try{if(!t(n))return null;let e=typeof n.name==`string`?n.name:void 0,r=typeof n.version==`string`?n.version:void 0,i=typeof n.description==`string`?n.description:void 0,a=d(n.bin),o=typeof n.homepage==`string`?n.homepage:void 0,s=f(n.repository);return{...e===void 0?{}:{name:e},...r===void 0?{}:{version:r},...i===void 0?{}:{description:i},...a===void 0?{}:{bin:a},...o===void 0?{}:{homepage:o},...s===void 0?{}:{repository:s}}}catch{return null}}function d(e){if(typeof e==`string`)return e;if(!t(e))return;let n={};for(let[t,r]of Object.entries(e)){if(typeof r!=`string`)return;n[t]=r}return n}function f(e){if(typeof e==`string`)return e;if(!t(e))return;let n=typeof e.type==`string`?e.type:void 0,r=typeof e.url==`string`?e.url:void 0,i=typeof e.directory==`string`?e.directory:void 0;if(!(n===void 0&&r===void 0&&i===void 0))return{...n===void 0?{}:{type:n},...r===void 0?{}:{url:r},...i===void 0?{}:{directory:i}}}const p={github:`https://github.com`,gitlab:`https://gitlab.com`,bitbucket:`https://bitbucket.org`};function m(e){return e.endsWith(`.git`)?e.slice(0,-4):e}function h(t){let n=typeof t.repository==`string`?t.repository:t.repository?.url;if(n===void 0)return;let r=n.trim();if(r.length===0)return;let i=/^(github|gitlab|bitbucket):([^/]+\/[^/]+)$/.exec(r);if(i!==null&&i[1]!==void 0&&i[2]!==void 0){let e=p[i[1]];if(e!==void 0)return`${e}/${m(i[2])}`}if(/^[\w.-]+\/[\w.-]+$/.test(r))return`https://github.com/${m(r)}`;r.startsWith(`git+`)&&(r=r.slice(4));let a=/^git@([^:/]+):(.+)$/.exec(r);if(a!==null&&a[1]!==void 0&&a[2]!==void 0)return`https://${a[1]}/${m(e(a[2],[47]))}`;if(/^(?:https?|git|ssh):\/\//.test(r))try{let t=new URL(r),n=m(e(t.pathname,[47]));return`https://${t.hostname}${n}`}catch{return}}function g(e,t={}){if(typeof e.bin==`object`){let t=Object.keys(e.bin);if(t.length>0&&t[0]!==void 0)return t[0]}if(e.name!==void 0){if(t.stripScope===!1)return e.name;let n=e.name.indexOf(`/`);return n>=0?e.name.slice(n+1):e.name}}export{o as discoverManifest,s as discoverPackageJson,g as inferCliName,h as packageRepositoryUrl};
@@ -15,9 +15,39 @@ interface HelpOptions {
15
15
  * automatically when stdout is a TTY.
16
16
  */
17
17
  readonly hyperlinks?: boolean;
18
+ /**
19
+ * Render the default command's arguments and flags inline in root help.
20
+ *
21
+ * Only affects root-level help. When `false`, root help lists commands and
22
+ * defers default-command details to `<bin> --help`-style hints.
23
+ *
24
+ * @defaultValue `true`
25
+ */
26
+ readonly inlineDefault?: boolean;
27
+ /**
28
+ * List the default command in the root `Commands:` table.
29
+ *
30
+ * By default the default command is treated as the root surface and omitted
31
+ * from the command list (its args/flags render inline instead).
32
+ *
33
+ * @defaultValue `false`
34
+ */
35
+ readonly showDefaultInCommands?: boolean;
36
+ /**
37
+ * Show the `Run '<bin> <command> --help' for more information.` footer.
38
+ *
39
+ * Defaults to showing the hint only when visible subcommands exist; set
40
+ * explicitly to force it on or off.
41
+ */
42
+ readonly footer?: boolean;
18
43
  /** @internal Whether this usage line is being rendered as merged root/default help. */
19
44
  readonly isDefaultHelp?: boolean;
20
45
  }
46
+ /** Formatted flag entry for the flags table. @internal */
47
+ interface FlagEntry {
48
+ readonly left: string;
49
+ readonly description: string;
50
+ }
21
51
  /**
22
52
  * Build the ordered help sections without joining them.
23
53
  *
@@ -53,5 +83,19 @@ declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions
53
83
  * ```
54
84
  */
55
85
  declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
86
+ /**
87
+ * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
88
+ *
89
+ * Shared by the per-command `Flags:` section and the root-help `Global options:`
90
+ * block (built-in flags), so column alignment and description wrapping stay
91
+ * identical across both. Returns `''` when there are no entries.
92
+ *
93
+ * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`).
94
+ * @param entries - Formatted left/description rows.
95
+ * @param width - Terminal width for description wrapping.
96
+ * @returns Multi-line block string, or `''` when `entries` is empty.
97
+ * @internal
98
+ */
99
+ declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
56
100
  //#endregion
57
- export { type HelpOptions, formatHelp, formatHelpSections, osc8, visibleWidth };
101
+ export { type FlagEntry, type HelpOptions, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
@@ -1,7 +1,7 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";import{padEnd as n,wrapText as r}from"./ansi.mjs";function i(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let n=i(t),r=[];r.push(h(e,n)),e.description!==void 0&&r.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&r.push(v(a,n)),e.args.length>0&&r.push(g(e.args,n)),Object.keys(e.flags).length>0&&r.push(_(e.flags,n)),e.examples.length>0&&r.push(y(e.examples)),r}function m(e,t){return`${p(e,t).join(`
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";import{padEnd as n,wrapText as r}from"./ansi.mjs";function i(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let n=i(t),r=[];r.push(h(e,n)),e.description!==void 0&&r.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&r.push(y(a,n)),e.args.length>0&&r.push(g(e.args,n)),Object.keys(e.flags).length>0&&r.push(_(e.flags,n)),e.examples.length>0&&r.push(b(e.examples)),r}function m(e,t){return`${p(e,t).join(`
2
2
 
3
- `)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0||t.isDefaultHelp&&t.binName===e.name?e.name:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let i=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)i.push(e);else{let o=n(e,s),c=r(a,t.width,s);i.push(`${o}${c}`)}return i.join(`
4
- `)}function _(e,t){let i=[`Flags:`],a=u(e);if(a.length===0)return``;let o=0;for(let e of a){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of a){let a=` ${e.left}`;if(e.description.length===0)i.push(a);else{let o=n(a,s),c=r(e.description,t.width,s);i.push(`${o}${c}`)}}return i.join(`
5
- `)}function v(e,t){let i=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)i.push(e);else{let a=n(e,o),c=r(s,t.width,o);i.push(`${a}${c}`)}}return i.join(`
6
- `)}function y(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
7
- `)}export{m as formatHelp,p as formatHelpSections};
3
+ `)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0?e.name:t.isDefaultHelp?t.binName:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let i=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)i.push(e);else{let o=n(e,s),c=r(a,t.width,s);i.push(`${o}${c}`)}return i.join(`
4
+ `)}function _(e,t){return v(`Flags:`,u(e),t.width)}function v(e,t,i){if(t.length===0)return``;let a=[e],o=0;for(let e of t){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of t){let t=` ${e.left}`;if(e.description.length===0)a.push(t);else{let o=n(t,s),c=r(e.description,i,s);a.push(`${o}${c}`)}}return a.join(`
5
+ `)}function y(e,t){let i=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)i.push(e);else{let a=n(e,o),c=r(s,t.width,o);i.push(`${a}${c}`)}}return i.join(`
6
+ `)}function b(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
7
+ `)}export{v as formatFlagEntriesBlock,m as formatHelp,p as formatHelpSections};
@@ -1,4 +1,4 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}from"../schema-dsl/runtime.mjs";import{nodeToJsonSchema as n}from"../schema-dsl/to-json-schema.mjs";import{definitionMetaSchemaDescriptions as r}from"./meta-descriptions.generated.mjs";function i(e){return{includeHidden:e?.includeHidden??!0,includePrompts:e?.includePrompts??!0}}const a=`https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json`,o=`https://json-schema.org/draft/2020-12/schema`;function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e,t){let n=i(t),r={$schema:a,name:e.name};return e.version!==void 0&&(r.version=e.version),e.description!==void 0&&(r.description=e.description),e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)&&(r.defaultCommand=e.defaultCommand.schema.name),r.commands=e.commands.filter(e=>n.includeHidden||!e.schema.hidden).map(e=>l(e.schema,n)),r}function l(e,t){let n={name:e.name};e.description!==void 0&&(n.description=e.description),e.aliases.length>0&&(n.aliases=[...e.aliases]),e.hidden&&(n.hidden=!0),e.examples.length>0&&(n.examples=e.examples.map(m));let r={};for(let[n,i]of Object.entries(e.flags))r[n]=u(i,t);return n.flags=r,n.args=e.args.map(d),n.commands=e.commands.filter(e=>t.includeHidden||!e.hidden).map(e=>l(e,t)),n}function u(t,n){let r={kind:t.kind,presence:t.presence};t.presence===`defaulted`&&w(t.defaultValue)&&(r.defaultValue=t.defaultValue);let i=e(t);return i.length>0&&(r.aliases=[...i]),t.envVar!==void 0&&(r.envVar=t.envVar),t.configPath!==void 0&&(r.configPath=t.configPath),t.description!==void 0&&(r.description=t.description),t.enumValues!==void 0&&(r.enumValues=[...t.enumValues]),t.elementSchema!==void 0&&(r.elementSchema=u(t.elementSchema,n)),n.includePrompts&&t.prompt!==void 0&&(r.prompt=f(t.prompt)),t.deprecated!==void 0&&(r.deprecated=t.deprecated),t.propagate&&(r.propagate=!0),r}function d(e){let{name:t,schema:n}=e,r={name:t,kind:n.kind,presence:n.presence};return n.variadic&&(r.variadic=!0),n.stdinMode&&(r.stdinMode=!0),n.presence===`defaulted`&&w(n.defaultValue)&&(r.defaultValue=n.defaultValue),n.description!==void 0&&(r.description=n.description),n.envVar!==void 0&&(r.envVar=n.envVar),n.enumValues!==void 0&&(r.enumValues=[...n.enumValues]),n.deprecated!==void 0&&(r.deprecated=n.deprecated),r}function f(e){let t={kind:e.kind,message:e.message};switch(e.kind){case`input`:e.placeholder!==void 0&&(t.placeholder=e.placeholder);break;case`select`:e.choices!==void 0&&(t.choices=e.choices.map(p));break;case`multiselect`:e.choices!==void 0&&(t.choices=e.choices.map(p)),e.min!==void 0&&(t.min=e.min),e.max!==void 0&&(t.max=e.max);break;case`confirm`:break}return t}function p(e){let t={value:e.value};return e.label!==void 0&&(t.label=e.label),e.description!==void 0&&(t.description=e.description),t}function m(e){let t={command:e.command};return e.description!==void 0&&(t.description=e.description),t}function h(e,t){let n=i(t);if(g(e))return{$schema:o,...v(e)};let r=[];for(let t of e.commands)!n.includeHidden&&t.schema.hidden||_(t.schema,``,r,n);if(r.length===1)return{$schema:o,...y(r[0]??{})};if(r.length>0){let t=e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)?e.defaultCommand.schema.name:void 0;return{$schema:o,oneOf:t===void 0?r:r.map(e=>b(e)===t?y(e):e)}}return{$schema:o,type:`object`}}function g(e){return`flags`in e&&`args`in e&&`middleware`in e&&`hasAction`in e}function _(e,t,n,r){let i=t?`${t}.${e.name}`:e.name;e.hasAction&&n.push(v(e,i));for(let t of e.commands)!r.includeHidden&&t.hidden||_(t,i,n,r)}function v(e,t){let n={},r=[];t!==void 0&&(n.command={const:t},r.push(`command`));for(let[t,i]of Object.entries(e.flags))n[t]=x(i),i.presence===`required`&&r.push(t);for(let t of e.args)n[t.name]=S(t.schema),t.schema.presence===`required`&&r.push(t.name);let i={type:`object`,properties:n,additionalProperties:!1};return r.length>0&&(i.required=r),i}function y(e){let t=e.properties,n=e.required,r=s(t)?{...t}:void 0,i=Array.isArray(n)?n.filter(e=>typeof e==`string`):void 0;r!==void 0&&delete r.command;let a=i?.filter(e=>e!==`command`),o={...e};return r!==void 0&&(o.properties=r),a!==void 0&&a.length>0?o.required=a:delete o.required,o}function b(e){let t=e.properties;if(!s(t))return;let n=t.command;return s(n)&&typeof n.const==`string`?n.const:void 0}function x(e){let t={};switch(e.kind){case`string`:t.type=`string`;break;case`number`:t.type=`number`;break;case`boolean`:t.type=`boolean`;break;case`enum`:t.type=`string`,e.enumValues!==void 0&&(t.enum=[...e.enumValues]);break;case`array`:t.type=`array`,e.elementSchema!==void 0&&(t.items=x(e.elementSchema));break;case`custom`:break}return e.description!==void 0&&(t.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(t.default=e.defaultValue),e.deprecated!==void 0&&(t.deprecated=e.deprecated),t}function S(e){let t=C(e),n=e.variadic?{type:`array`,items:t}:{...t};return e.description!==void 0&&(n.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(n.default=e.defaultValue),e.deprecated!==void 0&&(n.deprecated=e.deprecated),n}function C(e){switch(e.kind){case`string`:return{type:`string`};case`number`:return{type:`number`};case`enum`:{let t={type:`string`};return e.enumValues!==void 0&&(t.enum=[...e.enumValues]),t}case`custom`:return{}}}function w(e,t=new WeakSet){if(e===void 0)return!1;if(e===null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`||n===`bigint`)return!1;if(Array.isArray(e)){if(t.has(e))return!1;t.add(e);try{return e.every(e=>w(e,t))}finally{t.delete(e)}}if(n===`object`){let n=e;if(!T(n)||t.has(n))return!1;t.add(n);try{return Object.values(n).every(e=>w(e,t))}finally{t.delete(n)}}return!1}function T(e){let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function E(e){return n(t(e))}function D(e,t){let n=e.properties,r=typeof n==`object`&&n&&T(n)&&t.properties!==void 0?Object.fromEntries(Object.entries(n).map(([e,n])=>{let r=t.properties?.[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]})):void 0;return{...e,...t.description===void 0?{}:{description:t.description},...r===void 0?{}:{properties:r}}}function O(e,t){let n=D(e,t.root),r=n.$defs;return typeof r!=`object`||!r||!T(r)?n:{...n,$defs:Object.fromEntries(Object.entries(r).map(([e,n])=>{let r=t.defs[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]}))}}const k=O({$schema:o,$id:a,title:`@kjanat/dreamcli definition schema`,description:`Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.`,...E(`{
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}from"../schema-dsl/runtime.mjs";import{nodeToJsonSchema as n}from"../schema-dsl/to-json-schema.mjs";import{definitionMetaSchemaDescriptions as r}from"./meta-descriptions.generated.mjs";function i(e){return{includeHidden:e?.includeHidden??!0,includePrompts:e?.includePrompts??!0}}const a=`https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json`,o=`https://json-schema.org/draft/2020-12/schema`;function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e,t){let n=i(t),r={$schema:a,name:e.name};return e.version!==void 0&&(r.version=e.version),e.description!==void 0&&(r.description=e.description),e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)&&(r.defaultCommand=e.defaultCommand.schema.name),r.commands=e.commands.filter(e=>n.includeHidden||!e.schema.hidden).map(e=>l(e.schema,n)),r}function l(e,t){let n={name:e.name};e.description!==void 0&&(n.description=e.description),e.aliases.length>0&&(n.aliases=[...e.aliases]),e.hidden&&(n.hidden=!0),e.examples.length>0&&(n.examples=e.examples.map(m));let r={};for(let[n,i]of Object.entries(e.flags))r[n]=u(i,t);return n.flags=r,n.args=e.args.map(d),n.commands=e.commands.filter(e=>t.includeHidden||!e.hidden).map(e=>l(e,t)),n}function u(t,n){let r={kind:t.kind,presence:t.presence};t.presence===`defaulted`&&w(t.defaultValue)&&(r.defaultValue=t.defaultValue);let i=e(t);return i.length>0&&(r.aliases=[...i]),t.envVar!==void 0&&(r.envVar=t.envVar),t.configPath!==void 0&&(r.configPath=t.configPath),t.description!==void 0&&(r.description=t.description),t.enumValues!==void 0&&(r.enumValues=[...t.enumValues]),t.elementSchema!==void 0&&(r.elementSchema=u(t.elementSchema,n)),n.includePrompts&&t.prompt!==void 0&&(r.prompt=f(t.prompt)),t.deprecated!==void 0&&(r.deprecated=t.deprecated),t.propagate&&(r.propagate=!0),r}function d(e){let{name:t,schema:n}=e,r={name:t,kind:n.kind,presence:n.presence};return n.variadic&&(r.variadic=!0),n.stdinMode&&(r.stdinMode=!0),n.presence===`defaulted`&&w(n.defaultValue)&&(r.defaultValue=n.defaultValue),n.description!==void 0&&(r.description=n.description),n.envVar!==void 0&&(r.envVar=n.envVar),n.enumValues!==void 0&&(r.enumValues=[...n.enumValues]),n.deprecated!==void 0&&(r.deprecated=n.deprecated),r}function f(e){let t={kind:e.kind,message:e.message};switch(e.kind){case`input`:e.placeholder!==void 0&&(t.placeholder=e.placeholder);break;case`select`:e.choices!==void 0&&(t.choices=e.choices.map(p));break;case`multiselect`:e.choices!==void 0&&(t.choices=e.choices.map(p)),e.min!==void 0&&(t.min=e.min),e.max!==void 0&&(t.max=e.max);break;case`confirm`:break}return t}function p(e){let t={value:e.value};return e.label!==void 0&&(t.label=e.label),e.description!==void 0&&(t.description=e.description),t}function m(e){let t={command:e.command};return e.description!==void 0&&(t.description=e.description),t}function h(e,t){let n=i(t);if(g(e))return{$schema:o,...v(e)};let r=[];for(let t of e.commands)!n.includeHidden&&t.schema.hidden||_(t.schema,``,r,n);if(r.length===1)return{$schema:o,...y(r[0]??{})};if(r.length>0){let t=e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)?e.defaultCommand.schema.name:void 0;return{$schema:o,oneOf:t===void 0?r:r.map(e=>b(e)===t?y(e):e)}}return{$schema:o,type:`object`}}function g(e){return`flags`in e&&`args`in e&&`middleware`in e&&`hasAction`in e}function _(e,t,n,r){let i=t?`${t}.${e.name}`:e.name;e.hasAction&&n.push(v(e,i));for(let t of e.commands)!r.includeHidden&&t.hidden||_(t,i,n,r)}function v(e,t){let n={},r=[];t!==void 0&&(n.command={const:t},r.push(`command`));for(let[t,i]of Object.entries(e.flags))n[t]=x(i),i.presence===`required`&&r.push(t);for(let t of e.args)n[t.name]=S(t.schema),t.schema.presence===`required`&&r.push(t.name);let i={type:`object`,properties:n,additionalProperties:!1};return r.length>0&&(i.required=r),i}function y(e){let t=e.properties,n=e.required,r=s(t)?{...t}:void 0,i=Array.isArray(n)?n.filter(e=>typeof e==`string`):void 0;r!==void 0&&delete r.command;let a=i?.filter(e=>e!==`command`),o={...e};return r!==void 0&&(o.properties=r),a!==void 0&&a.length>0?o.required=a:delete o.required,o}function b(e){let t=e.properties;if(!s(t))return;let n=t.command;return s(n)&&typeof n.const==`string`?n.const:void 0}function x(e){let t={};switch(e.kind){case`string`:t.type=`string`;break;case`number`:{let n=e.numberConstraints;t.type=n?.int===!0?`integer`:`number`,n?.min!==void 0&&(t.minimum=n.min),n?.max!==void 0&&(t.maximum=n.max);break}case`boolean`:t.type=`boolean`;break;case`enum`:t.type=`string`,e.enumValues!==void 0&&(t.enum=[...e.enumValues]);break;case`array`:t.type=`array`,e.elementSchema!==void 0&&(t.items=x(e.elementSchema));break;case`custom`:break}return e.description!==void 0&&(t.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(t.default=e.defaultValue),e.deprecated!==void 0&&(t.deprecated=e.deprecated),t}function S(e){let t=C(e),n=e.variadic?{type:`array`,items:t}:{...t};return e.description!==void 0&&(n.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(n.default=e.defaultValue),e.deprecated!==void 0&&(n.deprecated=e.deprecated),n}function C(e){switch(e.kind){case`string`:return{type:`string`};case`number`:{let t=e.numberConstraints,n={type:t?.int===!0?`integer`:`number`};return t?.min!==void 0&&(n.minimum=t.min),t?.max!==void 0&&(n.maximum=t.max),n}case`enum`:{let t={type:`string`};return e.enumValues!==void 0&&(t.enum=[...e.enumValues]),t}case`custom`:return{}}}function w(e,t=new WeakSet){if(e===void 0)return!1;if(e===null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`||n===`bigint`)return!1;if(Array.isArray(e)){if(t.has(e))return!1;t.add(e);try{return e.every(e=>w(e,t))}finally{t.delete(e)}}if(n===`object`){let n=e;if(!T(n)||t.has(n))return!1;t.add(n);try{return Object.values(n).every(e=>w(e,t))}finally{t.delete(n)}}return!1}function T(e){let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function E(e){return n(t(e))}function D(e,t){let n=e.properties,r=typeof n==`object`&&n&&T(n)&&t.properties!==void 0?Object.fromEntries(Object.entries(n).map(([e,n])=>{let r=t.properties?.[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]})):void 0;return{...e,...t.description===void 0?{}:{description:t.description},...r===void 0?{}:{properties:r}}}function O(e,t){let n=D(e,t.root),r=n.$defs;return typeof r!=`object`||!r||!T(r)?n:{...n,$defs:Object.fromEntries(Object.entries(r).map(([e,n])=>{let r=t.defs[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]}))}}const k=O({$schema:o,$id:a,title:`@kjanat/dreamcli definition schema`,description:`Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.`,...E(`{
2
2
  $schema: '${a}';
3
3
  name: string;
4
4
  version?: string;