@kjanat/dreamcli 3.0.0-rc.14 → 3.0.0-rc.15
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.
- package/CHANGELOG.md +13 -1
- package/dist/core/cli/index.d.mts +18 -0
- package/dist/core/help/index.d.mts +18 -0
- package/dist/core/help/index.mjs +33 -18
- package/dist/version.mjs +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [3.0.0-rc.15] - 2026-07-20
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Configurable flag order in help** — `.help({ flagOrder })` controls the
|
|
15
|
+
`Flags:` table order: `'alphabetical'` (default, short-aliased flags first
|
|
16
|
+
then alphabetical) or `'declaration'` (the order `.flag()` was called). For
|
|
17
|
+
full control, `.help({ sortFlags: (a, b) => number })` supplies a custom
|
|
18
|
+
comparator over flag names that wins over `flagOrder`. Both are also
|
|
19
|
+
accepted at runtime via `execute`/`run` `help` options.
|
|
20
|
+
|
|
10
21
|
## [3.0.0-rc.14] - 2026-07-20
|
|
11
22
|
|
|
12
23
|
### Added
|
|
@@ -1289,7 +1300,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
1289
1300
|
- MIT License.
|
|
1290
1301
|
- Markdownlint configuration.
|
|
1291
1302
|
|
|
1292
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.
|
|
1303
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.15...HEAD
|
|
1304
|
+
[3.0.0-rc.15]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.14...v3.0.0-rc.15
|
|
1293
1305
|
[3.0.0-rc.14]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.13...v3.0.0-rc.14
|
|
1294
1306
|
[3.0.0-rc.13]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.12...v3.0.0-rc.13
|
|
1295
1307
|
[3.0.0-rc.12]: https://github.com/kjanat/dreamcli/compare/v3.0.0-rc.11...v3.0.0-rc.12
|
|
@@ -153,6 +153,24 @@ interface HelpConfig {
|
|
|
153
153
|
readonly width?: number;
|
|
154
154
|
/** Emit OSC 8 hyperlinks in the header when supported. */
|
|
155
155
|
readonly hyperlinks?: boolean;
|
|
156
|
+
/**
|
|
157
|
+
* Order of flags in the `Flags:` table.
|
|
158
|
+
*
|
|
159
|
+
* - `'alphabetical'` — short-aliased flags first, then alphabetical by name.
|
|
160
|
+
* - `'declaration'` — the order `.flag()` was called.
|
|
161
|
+
*
|
|
162
|
+
* Ignored when {@link HelpConfig.sortFlags} is set.
|
|
163
|
+
*
|
|
164
|
+
* @defaultValue `'alphabetical'`
|
|
165
|
+
*/
|
|
166
|
+
readonly flagOrder?: 'alphabetical' | 'declaration';
|
|
167
|
+
/**
|
|
168
|
+
* Custom comparator over flag long names for the `Flags:` table. When set,
|
|
169
|
+
* it wins over {@link HelpConfig.flagOrder}.
|
|
170
|
+
*
|
|
171
|
+
* @defaultValue `undefined` (use `flagOrder`)
|
|
172
|
+
*/
|
|
173
|
+
readonly sortFlags?: (a: string, b: string) => number;
|
|
156
174
|
/**
|
|
157
175
|
* Theme overrides for help output, merged over the built-in theme.
|
|
158
176
|
*
|
|
@@ -12,6 +12,24 @@ interface HelpOptions {
|
|
|
12
12
|
readonly binName?: string;
|
|
13
13
|
/** Program version passed to function-form examples as `meta.version`. */
|
|
14
14
|
readonly version?: string;
|
|
15
|
+
/**
|
|
16
|
+
* Order of flags in the `Flags:` table.
|
|
17
|
+
*
|
|
18
|
+
* - `'alphabetical'` — short-aliased flags first, then alphabetical by name.
|
|
19
|
+
* - `'declaration'` — the order `.flag()` was called.
|
|
20
|
+
*
|
|
21
|
+
* Ignored when {@link HelpOptions.sortFlags} is set.
|
|
22
|
+
*
|
|
23
|
+
* @defaultValue `'alphabetical'`
|
|
24
|
+
*/
|
|
25
|
+
readonly flagOrder?: 'alphabetical' | 'declaration';
|
|
26
|
+
/**
|
|
27
|
+
* Custom comparator over flag long names for the `Flags:` table. When set,
|
|
28
|
+
* it wins over {@link HelpOptions.flagOrder}.
|
|
29
|
+
*
|
|
30
|
+
* @defaultValue `undefined` (use `flagOrder`)
|
|
31
|
+
*/
|
|
32
|
+
readonly sortFlags?: (a: string, b: string) => number;
|
|
15
33
|
/**
|
|
16
34
|
* Emit OSC 8 hyperlinks where link metadata is available (currently the
|
|
17
35
|
* root-help header name/version configured via `CLIBuilder.links()`).
|
package/dist/core/help/index.mjs
CHANGED
|
@@ -16,6 +16,8 @@ function resolveOptions(options) {
|
|
|
16
16
|
width: options?.width ?? DEFAULT_WIDTH,
|
|
17
17
|
binName: options?.binName,
|
|
18
18
|
version: options?.version,
|
|
19
|
+
flagOrder: options?.flagOrder ?? "alphabetical",
|
|
20
|
+
sortFlags: options?.sortFlags,
|
|
19
21
|
isDefaultHelp: options?.isDefaultHelp ?? false,
|
|
20
22
|
theme: resolveHelpTheme(options?.colors, options?.theme)
|
|
21
23
|
};
|
|
@@ -98,32 +100,45 @@ function formatFlagDescription(schema, theme) {
|
|
|
98
100
|
return parts.join(" ");
|
|
99
101
|
}
|
|
100
102
|
/**
|
|
101
|
-
*
|
|
103
|
+
* Default flag order: short-aliased flags first, then alphabetical by name.
|
|
104
|
+
*/
|
|
105
|
+
function defaultFlagOrder(a, b, flags) {
|
|
106
|
+
const aSchema = flags[a];
|
|
107
|
+
const bSchema = flags[b];
|
|
108
|
+
if (aSchema === void 0 || bSchema === void 0) return 0;
|
|
109
|
+
const aHasShort = getFlagAliasNames(aSchema, { kind: "short" }).length > 0;
|
|
110
|
+
const bHasShort = getFlagAliasNames(bSchema, { kind: "short" }).length > 0;
|
|
111
|
+
if (aHasShort && !bHasShort) return -1;
|
|
112
|
+
if (!aHasShort && bHasShort) return 1;
|
|
113
|
+
return a.localeCompare(b);
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Order flag names for the table: an explicit `sortFlags` comparator wins,
|
|
117
|
+
* then `'declaration'` preserves `.flag()` call order, otherwise the default
|
|
118
|
+
* short-first alphabetical order.
|
|
119
|
+
*/
|
|
120
|
+
function orderFlagNames(names, flags, opts) {
|
|
121
|
+
if (opts.sortFlags !== void 0) return [...names].sort(opts.sortFlags);
|
|
122
|
+
if (opts.flagOrder === "declaration") return names;
|
|
123
|
+
return [...names].sort((a, b) => defaultFlagOrder(a, b, flags));
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Build the flag entries in the configured order.
|
|
102
127
|
*
|
|
103
128
|
* @param flags - Map of flag names to {@link FlagSchema} definitions.
|
|
104
|
-
* @param
|
|
105
|
-
* @returns
|
|
129
|
+
* @param opts - Resolved help options (theme + flag ordering).
|
|
130
|
+
* @returns Array of {@link FlagEntry} objects for the flags table.
|
|
106
131
|
*/
|
|
107
|
-
function buildFlagEntries(flags,
|
|
132
|
+
function buildFlagEntries(flags, opts) {
|
|
108
133
|
const names = Object.keys(flags);
|
|
109
134
|
if (names.length === 0) return [];
|
|
110
|
-
const sorted = [...names].sort((a, b) => {
|
|
111
|
-
const aSchema = flags[a];
|
|
112
|
-
const bSchema = flags[b];
|
|
113
|
-
if (aSchema === void 0 || bSchema === void 0) return 0;
|
|
114
|
-
const aHasShort = getFlagAliasNames(aSchema, { kind: "short" }).length > 0;
|
|
115
|
-
const bHasShort = getFlagAliasNames(bSchema, { kind: "short" }).length > 0;
|
|
116
|
-
if (aHasShort && !bHasShort) return -1;
|
|
117
|
-
if (!aHasShort && bHasShort) return 1;
|
|
118
|
-
return a.localeCompare(b);
|
|
119
|
-
});
|
|
120
135
|
const entries = [];
|
|
121
|
-
for (const name of
|
|
136
|
+
for (const name of orderFlagNames(names, flags, opts)) {
|
|
122
137
|
const schema = flags[name];
|
|
123
138
|
if (schema === void 0) continue;
|
|
124
139
|
entries.push({
|
|
125
|
-
left: formatFlagLeft(name, schema, theme),
|
|
126
|
-
description: formatFlagDescription(schema, theme)
|
|
140
|
+
left: formatFlagLeft(name, schema, opts.theme),
|
|
141
|
+
description: formatFlagDescription(schema, opts.theme)
|
|
127
142
|
});
|
|
128
143
|
}
|
|
129
144
|
return entries;
|
|
@@ -267,7 +282,7 @@ function formatArgsSection(args, opts) {
|
|
|
267
282
|
* @returns Multi-line flags section string.
|
|
268
283
|
*/
|
|
269
284
|
function formatFlagsSection(flags, opts) {
|
|
270
|
-
return formatFlagEntriesBlock(opts.theme.sectionTitle("Flags:"), buildFlagEntries(flags, opts
|
|
285
|
+
return formatFlagEntriesBlock(opts.theme.sectionTitle("Flags:"), buildFlagEntries(flags, opts), opts.width);
|
|
271
286
|
}
|
|
272
287
|
/**
|
|
273
288
|
* Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
|
package/dist/version.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
//#region src/version.ts
|
|
2
2
|
/** Package version (e.g. `"0.9.1"`). `"dev"` when running unbundled. */
|
|
3
|
-
const DREAMCLI_VERSION = "3.0.0-rc.
|
|
3
|
+
const DREAMCLI_VERSION = "3.0.0-rc.15";
|
|
4
4
|
/** Git short SHA (e.g. `"f9b5f1a"`). `"dev"` when running unbundled. */
|
|
5
|
-
const DREAMCLI_REVISION = "
|
|
5
|
+
const DREAMCLI_REVISION = "403c982";
|
|
6
6
|
//#endregion
|
|
7
7
|
export { DREAMCLI_REVISION, DREAMCLI_VERSION };
|