@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 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.14...HEAD
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()`).
@@ -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
- * Build the flag entries sorted: short-aliased first, then alphabetical.
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 theme - Theme threaded into the per-flag formatters.
105
- * @returns Sorted array of {@link FlagEntry} objects for the flags table.
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, theme) {
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 sorted) {
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.theme), opts.width);
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.14";
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 = "8e2235c";
5
+ const DREAMCLI_REVISION = "403c982";
6
6
  //#endregion
7
7
  export { DREAMCLI_REVISION, DREAMCLI_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "3.0.0-rc.14",
3
+ "version": "3.0.0-rc.15",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",