@eserstack/codebase 0.0.0-stage → 5.0.0

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 (175) hide show
  1. package/README.md +301 -2
  2. package/dist/changelog-gen.d.ts +105 -0
  3. package/dist/changelog-gen.js +498 -0
  4. package/dist/changelog-text.d.ts +39 -0
  5. package/dist/changelog-text.js +82 -0
  6. package/dist/cli-support.d.ts +140 -0
  7. package/dist/cli-support.js +244 -0
  8. package/dist/cli-system/app-opts.d.ts +15 -0
  9. package/dist/cli-system/app-opts.js +13 -0
  10. package/dist/cli-system/app.d.ts +29 -0
  11. package/dist/cli-system/app.js +12 -0
  12. package/dist/cli-system/handlers/completions-setup.d.ts +14 -0
  13. package/dist/cli-system/handlers/completions-setup.js +139 -0
  14. package/dist/cli-system/handlers/completions.d.ts +3 -0
  15. package/dist/cli-system/handlers/completions.js +79 -0
  16. package/dist/cli-system/handlers/doctor.d.ts +8 -0
  17. package/dist/cli-system/handlers/doctor.js +146 -0
  18. package/dist/cli-system/handlers/info.d.ts +3 -0
  19. package/dist/cli-system/handlers/info.js +69 -0
  20. package/dist/cli-system/handlers/install.d.ts +8 -0
  21. package/dist/cli-system/handlers/install.js +137 -0
  22. package/dist/cli-system/handlers/mod.d.ts +12 -0
  23. package/dist/cli-system/handlers/mod.js +13 -0
  24. package/dist/cli-system/handlers/uninstall.d.ts +3 -0
  25. package/dist/cli-system/handlers/uninstall.js +60 -0
  26. package/dist/cli-system/handlers/update.d.ts +76 -0
  27. package/dist/cli-system/handlers/update.js +310 -0
  28. package/dist/cli-system/handlers/version-check.d.ts +16 -0
  29. package/dist/cli-system/handlers/version-check.js +176 -0
  30. package/dist/cli-system/handlers/version.d.ts +3 -0
  31. package/dist/cli-system/handlers/version.js +45 -0
  32. package/dist/cli-system/mod.d.ts +19 -0
  33. package/dist/cli-system/mod.js +52 -0
  34. package/dist/commitmsg.d.ts +28 -0
  35. package/dist/commitmsg.js +232 -0
  36. package/dist/directive-analysis.d.ts +75 -0
  37. package/dist/directive-analysis.js +223 -0
  38. package/dist/ffi-client.d.ts +11 -0
  39. package/dist/ffi-client.js +12 -0
  40. package/dist/file-tool.d.ts +96 -0
  41. package/dist/file-tool.js +274 -0
  42. package/dist/file-tools-shared.d.ts +81 -0
  43. package/dist/file-tools-shared.js +276 -0
  44. package/dist/gh-contributors.d.ts +89 -0
  45. package/dist/gh-contributors.js +205 -0
  46. package/dist/gh.d.ts +3 -0
  47. package/dist/gh.js +64 -0
  48. package/dist/git-listing.d.ts +27 -0
  49. package/dist/git-listing.js +69 -0
  50. package/dist/git.d.ts +172 -0
  51. package/dist/git.js +277 -0
  52. package/dist/install.d.ts +34 -0
  53. package/dist/install.js +421 -0
  54. package/dist/main.d.ts +22 -0
  55. package/dist/main.js +14 -0
  56. package/dist/mod.d.ts +25 -0
  57. package/dist/mod.js +8 -0
  58. package/dist/module.d.ts +10 -0
  59. package/dist/module.js +221 -0
  60. package/dist/native-functions.d.ts +1088 -0
  61. package/dist/native-functions.js +2 -0
  62. package/dist/npm-externals.d.ts +27 -0
  63. package/dist/npm-externals.js +34 -0
  64. package/dist/npm-workspace-specifiers.d.ts +6 -0
  65. package/dist/npm-workspace-specifiers.js +45 -0
  66. package/dist/package/loader.d.ts +34 -0
  67. package/dist/package/loader.js +203 -0
  68. package/dist/package/mod.d.ts +36 -0
  69. package/dist/package/mod.js +5 -0
  70. package/dist/package/types.d.ts +142 -0
  71. package/dist/package/types.js +32 -0
  72. package/dist/package/workspace.d.ts +33 -0
  73. package/dist/package/workspace.js +158 -0
  74. package/dist/package/writer.d.ts +52 -0
  75. package/dist/package/writer.js +278 -0
  76. package/dist/package.json +275 -0
  77. package/dist/release-notes.d.ts +90 -0
  78. package/dist/release-notes.js +236 -0
  79. package/dist/release-tag.d.ts +46 -0
  80. package/dist/release-tag.js +95 -0
  81. package/dist/release.d.ts +145 -0
  82. package/dist/release.js +584 -0
  83. package/dist/source-mask.d.ts +3 -0
  84. package/dist/source-mask.js +185 -0
  85. package/dist/validate-bom.d.ts +5 -0
  86. package/dist/validate-bom.js +43 -0
  87. package/dist/validate-case-conflict.d.ts +5 -0
  88. package/dist/validate-case-conflict.js +43 -0
  89. package/dist/validate-circular-deps.d.ts +11 -0
  90. package/dist/validate-circular-deps.js +53 -0
  91. package/dist/validate-code-conventions.d.ts +22 -0
  92. package/dist/validate-code-conventions.js +166 -0
  93. package/dist/validate-commit-msg.d.ts +50 -0
  94. package/dist/validate-commit-msg.js +182 -0
  95. package/dist/validate-docs.d.ts +20 -0
  96. package/dist/validate-docs.js +78 -0
  97. package/dist/validate-eof.d.ts +5 -0
  98. package/dist/validate-eof.js +61 -0
  99. package/dist/validate-error-coverage.d.ts +28 -0
  100. package/dist/validate-error-coverage.js +93 -0
  101. package/dist/validate-export-names.d.ts +17 -0
  102. package/dist/validate-export-names.js +56 -0
  103. package/dist/validate-filenames.d.ts +5 -0
  104. package/dist/validate-filenames.js +151 -0
  105. package/dist/validate-json.d.ts +5 -0
  106. package/dist/validate-json.js +71 -0
  107. package/dist/validate-large-files.d.ts +5 -0
  108. package/dist/validate-large-files.js +41 -0
  109. package/dist/validate-laroux-boundaries.d.ts +19 -0
  110. package/dist/validate-laroux-boundaries.js +59 -0
  111. package/dist/validate-licenses.d.ts +5 -0
  112. package/dist/validate-licenses.js +137 -0
  113. package/dist/validate-line-endings.d.ts +5 -0
  114. package/dist/validate-line-endings.js +47 -0
  115. package/dist/validate-merge-conflict.d.ts +5 -0
  116. package/dist/validate-merge-conflict.js +46 -0
  117. package/dist/validate-mod-exports.d.ts +16 -0
  118. package/dist/validate-mod-exports.js +56 -0
  119. package/dist/validate-naming-and-todos.d.ts +5 -0
  120. package/dist/validate-naming-and-todos.js +70 -0
  121. package/dist/validate-runtime-js-apis.d.ts +5 -0
  122. package/dist/validate-runtime-js-apis.js +78 -0
  123. package/dist/validate-secrets.d.ts +5 -0
  124. package/dist/validate-secrets.js +82 -0
  125. package/dist/validate-self-imports.d.ts +5 -0
  126. package/dist/validate-self-imports.js +78 -0
  127. package/dist/validate-server-loc.d.ts +32 -0
  128. package/dist/validate-server-loc.js +94 -0
  129. package/dist/validate-shebangs.d.ts +5 -0
  130. package/dist/validate-shebangs.js +33 -0
  131. package/dist/validate-stream.d.ts +25 -0
  132. package/dist/validate-stream.js +62 -0
  133. package/dist/validate-submodules.d.ts +5 -0
  134. package/dist/validate-submodules.js +43 -0
  135. package/dist/validate-symlinks.d.ts +5 -0
  136. package/dist/validate-symlinks.js +46 -0
  137. package/dist/validate-toml.d.ts +5 -0
  138. package/dist/validate-toml.js +40 -0
  139. package/dist/validate-trailing-whitespace.d.ts +5 -0
  140. package/dist/validate-trailing-whitespace.js +49 -0
  141. package/dist/validate-yaml.d.ts +5 -0
  142. package/dist/validate-yaml.js +40 -0
  143. package/dist/validation/config.d.ts +17 -0
  144. package/dist/validation/config.js +30 -0
  145. package/dist/validation/mod.d.ts +71 -0
  146. package/dist/validation/mod.js +479 -0
  147. package/dist/validation/registry.d.ts +57 -0
  148. package/dist/validation/registry.js +256 -0
  149. package/dist/validation/types.d.ts +101 -0
  150. package/dist/validation/types.js +2 -0
  151. package/dist/validation/validators/circular-deps.d.ts +7 -0
  152. package/dist/validation/validators/circular-deps.js +31 -0
  153. package/dist/validation/validators/docs.d.ts +7 -0
  154. package/dist/validation/validators/docs.js +38 -0
  155. package/dist/validation/validators/error-coverage.d.ts +2 -0
  156. package/dist/validation/validators/error-coverage.js +46 -0
  157. package/dist/validation/validators/export-names.d.ts +7 -0
  158. package/dist/validation/validators/export-names.js +31 -0
  159. package/dist/validation/validators/laroux-boundaries.d.ts +2 -0
  160. package/dist/validation/validators/laroux-boundaries.js +29 -0
  161. package/dist/validation/validators/mod-exports.d.ts +7 -0
  162. package/dist/validation/validators/mod-exports.js +32 -0
  163. package/dist/validation/validators/mod.d.ts +11 -0
  164. package/dist/validation/validators/mod.js +12 -0
  165. package/dist/validation/validators/server-loc.d.ts +2 -0
  166. package/dist/validation/validators/server-loc.js +48 -0
  167. package/dist/versions.d.ts +166 -0
  168. package/dist/versions.js +349 -0
  169. package/dist/violation-baseline.d.ts +58 -0
  170. package/dist/violation-baseline.js +144 -0
  171. package/dist/walk-stream.d.ts +24 -0
  172. package/dist/walk-stream.js +55 -0
  173. package/dist/workspace-discovery.d.ts +60 -0
  174. package/dist/workspace-discovery.js +130 -0
  175. package/package.json +222 -3
@@ -0,0 +1,140 @@
1
+ import type { CliEvent } from "@eserstack/functions/triggers";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ import * as shellFlags from "@eserstack/shell/args/flags";
4
+ import * as cliApp from "./cli-system/app.ts";
5
+ import type { TuiContext } from "@eserstack/shell/tui/types";
6
+ import * as streams from "@eserstack/streams";
7
+ /** Return type for {@link createCliContext}. */
8
+ export type CliContext = {
9
+ readonly ctx: TuiContext;
10
+ readonly output: streams.Output;
11
+ };
12
+ /**
13
+ * Creates a `TuiContext` configured for the current environment.
14
+ *
15
+ * Detects whether stdout is a TTY (interactive terminal) or a pipe / CI
16
+ * environment and builds the context accordingly. The `output` field is
17
+ * extracted from the context for backward compatibility with call-sites
18
+ * that only need an `Output`.
19
+ */
20
+ export declare const createCliContext: () => CliContext;
21
+ /**
22
+ * Returns the CLI context shared by every command in this process, creating it
23
+ * on first use.
24
+ *
25
+ * Command modules call this inside their handlers instead of creating a
26
+ * context when they load: the context reads the terminal state, and importing
27
+ * a module must not (design-principles: Module-Level Side Effects).
28
+ */
29
+ export declare const getCliContext: () => CliContext;
30
+ /**
31
+ * Creates a standard Output wired to stdout with ANSI rendering.
32
+ *
33
+ * @deprecated Use {@link getCliContext} or {@link createCliContext}, which
34
+ * return a full `TuiContext`.
35
+ */
36
+ export declare const createCliOutput: () => streams.Output;
37
+ /**
38
+ * Convert a `parseArgs` result from `@eserstack/shell/args/flags` to a
39
+ * `CliEvent`.
40
+ *
41
+ * @param command - Command name
42
+ * @param parsed - Result from `parseArgs()`
43
+ * @returns A CliEvent with args and flags extracted
44
+ */
45
+ export declare const toCliEvent: (command: string, parsed: shellFlags.ParsedArgs) => CliEvent;
46
+ /**
47
+ * Parse CLI arguments into a `CliEvent`. Unknown flags stay in `flags`, as
48
+ * the handlers of the codebase scripts read them by name.
49
+ *
50
+ * @param command - Command name
51
+ * @param cliArgs - The raw arguments; none when undefined
52
+ * @param options - The flags the command knows
53
+ * @returns A CliEvent with args and flags extracted
54
+ */
55
+ export declare const parseCliEvent: (command: string, cliArgs: readonly string[] | undefined, options: Readonly<Record<string, shellFlags.ArgOption>>) => CliEvent;
56
+ /**
57
+ * Standard `import.meta.main` handler for all CLI scripts.
58
+ *
59
+ * Matches on the `CliResult`, printing any error message and setting
60
+ * the process exit code on failure.
61
+ *
62
+ * @param result - The CliResult from a trigger invocation
63
+ * @param out - Output instance for printing errors
64
+ */
65
+ export declare const runCliMain: (result: shellArgs.CliResult<void>, out?: streams.Output) => void;
66
+ /**
67
+ * Terminal `import.meta.main` handler for CLI entry points that may load the
68
+ * native `@eserstack/ajan` FFI library (the `eser` dispatcher, `codebase`,
69
+ * `validation`).
70
+ *
71
+ * Resolves the exit code from `result`, prints any error, drains buffered CLI
72
+ * output (see {@link liveOutputs}) and sets the exit code; the process then
73
+ * exits on its own. It used to exit the process itself, because the Go
74
+ * library could crash Deno on teardown and lose the exit code. Under Node it
75
+ * does not (TASK-175, measurement (c); ajan's teardown.ffi.test.ts), and
76
+ * cli-support-exit.ffi.test.ts checks the code survives a natural exit after
77
+ * a prompt and the bridge's workers.
78
+ *
79
+ * @param result - The CliResult from the command dispatch
80
+ */
81
+ export declare const exitCli: (result: shellArgs.CliResult<void>) => Promise<void>;
82
+ /**
83
+ * Attaches the `system` tree and its root aliases to a binary's root command.
84
+ *
85
+ * # Why a layer, and why it attaches to the ROOT
86
+ *
87
+ * Every shipped binary needs the same operational commands: `system install`,
88
+ * `uninstall`, `update`, `doctor`, `completions`, `version`, `info` — plus the
89
+ * short forms people actually type, `eser update` and `noskills doctor`.
90
+ *
91
+ * But `eser noskills version` must NOT exist. A submodule is not a program;
92
+ * giving it a version implies it has one of its own, and repeating the whole
93
+ * system tree under every namespace would bury each one's real commands.
94
+ *
95
+ * Attaching to the root Command rather than to the Module is what draws that
96
+ * line, and it draws it for free. The Module objects are SHARED — `eser` mounts
97
+ * the very same object the standalone `noskills` binary re-roots — so a layer
98
+ * living on the module would necessarily appear in both, with no way to have
99
+ * one without the other.
100
+ *
101
+ * The tree itself is built once in @eserstack/codebase/cli-system and
102
+ * parameterised by a `CliApp`, so `noskills system install` installs
103
+ * noskills and says so. One implementation, three bindings — not three copies.
104
+ */
105
+ export declare const attachStandardCommands: (command: shellArgs.Command, app?: Partial<cliApp.CliApp>) => shellArgs.Command;
106
+ /**
107
+ * Builds the entry point for a standalone binary carved out of the `eser` CLI.
108
+ *
109
+ * # The rule this enforces
110
+ *
111
+ * Some submodules are worth shipping on their own: someone who only wants the
112
+ * spec workflow should be able to `brew install noskills` and type
113
+ * `noskills next`, without discovering it lives inside a larger CLI. Someone
114
+ * already using the stack types `eser noskills next`. Both are reasonable, so
115
+ * both are shipped.
116
+ *
117
+ * What must not follow is two implementations. There used to be a 1,563-line Go
118
+ * CLI at cmd/noskills covering a subset of the same commands — a fork of the
119
+ * behaviour, free to drift, and it had. A standalone binary built this way
120
+ * mounts the SAME module object the `eser` CLI mounts, just at the root of its
121
+ * own tree, so `noskills next` and `eser noskills next` are one code path.
122
+ * There is nothing to keep in sync because nothing is duplicated.
123
+ *
124
+ * The only difference between the two entry points is where the module sits and
125
+ * what the binary is called.
126
+ */
127
+ export declare const runStandaloneModule: (module: {
128
+ toCommand: (name: string, version: string) => shellArgs.Command;
129
+ }, name: string, version: string) => Promise<void>;
130
+ /**
131
+ * Render why a spawned command failed, so the error an operator sees is
132
+ * actionable.
133
+ *
134
+ * Commands run with piped stdio, so the tool's own diagnostic ("non-fast-forward",
135
+ * "HTTP 403", "release not found") lives only on `CommandError.stderr` and is
136
+ * otherwise never printed. "Command failed with exit code 1: gh" on its own
137
+ * sends the operator to rerun the same command and watch it fail the same
138
+ * silent way — which is exactly how the v4.5.0 release-notes step died in CI.
139
+ */
140
+ export declare const commandFailureDetail: (err: unknown) => string;
@@ -0,0 +1,244 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Shared CLI support utilities for codebase scripts.
4
+ *
5
+ * Provides helpers for converting parsed CLI arguments to `CliEvent`
6
+ * and for running CLI triggers with standard exit code handling.
7
+ *
8
+ * @module
9
+ */
10
+ import * as results from "@eserstack/primitives/results";
11
+ import * as shellFlags from "@eserstack/shell/args/flags";
12
+ import * as shellExec from "@eserstack/shell/exec";
13
+ import * as cliApp from "./cli-system/app.js";
14
+ // The specific module, not the @eserstack/shell/tui barrel.
15
+ //
16
+ // Only createTuiContext and the TuiContext type are used here, but importing
17
+ // the barrel pulled all 26 of its exports -- every prompt widget, the spinner,
18
+ // the signal handling -- onto the startup path of every command that touches
19
+ // cli-support, which is all of them.
20
+ import * as types from "@eserstack/shell/tui/types";
21
+ import * as streams from "@eserstack/streams";
22
+ import * as span from "@eserstack/streams/span";
23
+ import { runtime } from "@eserstack/standards/cross-runtime";
24
+ // Every Output created through the helpers below is registered here so
25
+ // {@link exitCli} can drain it before the command's exit code is set. The
26
+ // streams Output is sync-write / async-flush.
27
+ const liveOutputs = new Set();
28
+ const flushLiveOutputs = async () => {
29
+ await Promise.all([...liveOutputs].map((out) => out.flush().catch(() => { })));
30
+ };
31
+ /**
32
+ * Creates a `TuiContext` configured for the current environment.
33
+ *
34
+ * Detects whether stdout is a TTY (interactive terminal) or a pipe / CI
35
+ * environment and builds the context accordingly. The `output` field is
36
+ * extracted from the context for backward compatibility with call-sites
37
+ * that only need an `Output`.
38
+ */
39
+ export const createCliContext = () => {
40
+ const isInteractive = runtime.process.isTerminal("stdout");
41
+ const interaction = isInteractive
42
+ ? "interactive"
43
+ : "non-interactive";
44
+ const ctx = types.createTuiContext({ interaction });
45
+ liveOutputs.add(ctx.output);
46
+ return { ctx, output: ctx.output };
47
+ };
48
+ // The cache behind getCliContext. It stays null until a command first needs
49
+ // the context.
50
+ let sharedCliContext = null;
51
+ /**
52
+ * Returns the CLI context shared by every command in this process, creating it
53
+ * on first use.
54
+ *
55
+ * Command modules call this inside their handlers instead of creating a
56
+ * context when they load: the context reads the terminal state, and importing
57
+ * a module must not (design-principles: Module-Level Side Effects).
58
+ */
59
+ export const getCliContext = () => {
60
+ if (sharedCliContext === null) {
61
+ sharedCliContext = createCliContext();
62
+ }
63
+ return sharedCliContext;
64
+ };
65
+ /**
66
+ * Creates a standard Output wired to stdout with ANSI rendering.
67
+ *
68
+ * @deprecated Use {@link getCliContext} or {@link createCliContext}, which
69
+ * return a full `TuiContext`.
70
+ */
71
+ export const createCliOutput = () => {
72
+ const out = streams.output({
73
+ renderer: streams.renderers.ansi(),
74
+ sink: streams.sinks.stdout(),
75
+ });
76
+ liveOutputs.add(out);
77
+ return out;
78
+ };
79
+ /**
80
+ * Convert a `parseArgs` result from `@eserstack/shell/args/flags` to a
81
+ * `CliEvent`.
82
+ *
83
+ * @param command - Command name
84
+ * @param parsed - Result from `parseArgs()`
85
+ * @returns A CliEvent with args and flags extracted
86
+ */
87
+ export const toCliEvent = (command, parsed) => ({
88
+ command,
89
+ args: parsed.positionals,
90
+ flags: { ...parsed.values },
91
+ });
92
+ /**
93
+ * Parse CLI arguments into a `CliEvent`. Unknown flags stay in `flags`, as
94
+ * the handlers of the codebase scripts read them by name.
95
+ *
96
+ * @param command - Command name
97
+ * @param cliArgs - The raw arguments; none when undefined
98
+ * @param options - The flags the command knows
99
+ * @returns A CliEvent with args and flags extracted
100
+ */
101
+ export const parseCliEvent = (command, cliArgs, options) => toCliEvent(command, shellFlags.parseArgs(cliArgs ?? [], { options }));
102
+ /**
103
+ * Standard `import.meta.main` handler for all CLI scripts.
104
+ *
105
+ * Matches on the `CliResult`, printing any error message and setting
106
+ * the process exit code on failure.
107
+ *
108
+ * @param result - The CliResult from a trigger invocation
109
+ * @param out - Output instance for printing errors
110
+ */
111
+ export const runCliMain = (result, out) => {
112
+ results.match(result, {
113
+ ok: () => { },
114
+ fail: (error) => {
115
+ if (error.message !== undefined) {
116
+ if (out !== undefined) {
117
+ out.writeln(span.red(error.message));
118
+ }
119
+ else {
120
+ const errorOutput = streams.output({
121
+ renderer: streams.renderers.plain(),
122
+ sink: streams.sinks.stderr(),
123
+ });
124
+ liveOutputs.add(errorOutput);
125
+ errorOutput.writeln(error.message);
126
+ }
127
+ }
128
+ runtime.process.setExitCode(error.exitCode);
129
+ },
130
+ });
131
+ };
132
+ /**
133
+ * Terminal `import.meta.main` handler for CLI entry points that may load the
134
+ * native `@eserstack/ajan` FFI library (the `eser` dispatcher, `codebase`,
135
+ * `validation`).
136
+ *
137
+ * Resolves the exit code from `result`, prints any error, drains buffered CLI
138
+ * output (see {@link liveOutputs}) and sets the exit code; the process then
139
+ * exits on its own. It used to exit the process itself, because the Go
140
+ * library could crash Deno on teardown and lose the exit code. Under Node it
141
+ * does not (TASK-175, measurement (c); ajan's teardown.ffi.test.ts), and
142
+ * cli-support-exit.ffi.test.ts checks the code survives a natural exit after
143
+ * a prompt and the bridge's workers.
144
+ *
145
+ * @param result - The CliResult from the command dispatch
146
+ */
147
+ export const exitCli = async (result) => {
148
+ const exitCode = results.match(result, {
149
+ ok: () => 0,
150
+ fail: (error) => {
151
+ if (error.message !== undefined) {
152
+ // oxlint-disable-next-line no-console
153
+ console.error(error.message);
154
+ }
155
+ return error.exitCode;
156
+ },
157
+ });
158
+ await flushLiveOutputs();
159
+ runtime.process.setExitCode(exitCode);
160
+ };
161
+ /**
162
+ * Attaches the `system` tree and its root aliases to a binary's root command.
163
+ *
164
+ * # Why a layer, and why it attaches to the ROOT
165
+ *
166
+ * Every shipped binary needs the same operational commands: `system install`,
167
+ * `uninstall`, `update`, `doctor`, `completions`, `version`, `info` — plus the
168
+ * short forms people actually type, `eser update` and `noskills doctor`.
169
+ *
170
+ * But `eser noskills version` must NOT exist. A submodule is not a program;
171
+ * giving it a version implies it has one of its own, and repeating the whole
172
+ * system tree under every namespace would bury each one's real commands.
173
+ *
174
+ * Attaching to the root Command rather than to the Module is what draws that
175
+ * line, and it draws it for free. The Module objects are SHARED — `eser` mounts
176
+ * the very same object the standalone `noskills` binary re-roots — so a layer
177
+ * living on the module would necessarily appear in both, with no way to have
178
+ * one without the other.
179
+ *
180
+ * The tree itself is built once in @eserstack/codebase/cli-system and
181
+ * parameterised by a `CliApp`, so `noskills system install` installs
182
+ * noskills and says so. One implementation, three bindings — not three copies.
183
+ */
184
+ export const attachStandardCommands = (command, app) => {
185
+ const resolved = {
186
+ ...cliApp.appFromName(command.name),
187
+ ...app,
188
+ };
189
+ return (command
190
+ .lazyCommand("system", {
191
+ description: "Commands related with this CLI",
192
+ load: async () => {
193
+ const cliSystem = await import("./cli-system/mod.js");
194
+ return cliSystem.createSystemCommand(resolved);
195
+ },
196
+ })
197
+ // The short forms. `system` holds the canonical definitions; these are the
198
+ // names people type.
199
+ .shortcut("install", "system install", `Install ${resolved.command} globally`)
200
+ .shortcut("update", "system update", `Update ${resolved.command}`)
201
+ .shortcut("version", "system version", "Show version number")
202
+ .shortcut("doctor", "system doctor", "Run diagnostic checks"));
203
+ };
204
+ /**
205
+ * Builds the entry point for a standalone binary carved out of the `eser` CLI.
206
+ *
207
+ * # The rule this enforces
208
+ *
209
+ * Some submodules are worth shipping on their own: someone who only wants the
210
+ * spec workflow should be able to `brew install noskills` and type
211
+ * `noskills next`, without discovering it lives inside a larger CLI. Someone
212
+ * already using the stack types `eser noskills next`. Both are reasonable, so
213
+ * both are shipped.
214
+ *
215
+ * What must not follow is two implementations. There used to be a 1,563-line Go
216
+ * CLI at cmd/noskills covering a subset of the same commands — a fork of the
217
+ * behaviour, free to drift, and it had. A standalone binary built this way
218
+ * mounts the SAME module object the `eser` CLI mounts, just at the root of its
219
+ * own tree, so `noskills next` and `eser noskills next` are one code path.
220
+ * There is nothing to keep in sync because nothing is duplicated.
221
+ *
222
+ * The only difference between the two entry points is where the module sits and
223
+ * what the binary is called.
224
+ */
225
+ export const runStandaloneModule = async (module, name, version) => {
226
+ const app = attachStandardCommands(module.toCommand(name, version));
227
+ await exitCli(await app.parse());
228
+ };
229
+ /**
230
+ * Render why a spawned command failed, so the error an operator sees is
231
+ * actionable.
232
+ *
233
+ * Commands run with piped stdio, so the tool's own diagnostic ("non-fast-forward",
234
+ * "HTTP 403", "release not found") lives only on `CommandError.stderr` and is
235
+ * otherwise never printed. "Command failed with exit code 1: gh" on its own
236
+ * sends the operator to rerun the same command and watch it fail the same
237
+ * silent way — which is exactly how the v4.5.0 release-notes step died in CI.
238
+ */
239
+ export const commandFailureDetail = (err) => {
240
+ if (err instanceof shellExec.CommandError && err.stderr.trim().length > 0) {
241
+ return `\n\n${err.stderr.trim()}`;
242
+ }
243
+ return err instanceof Error ? `\n\n${err.message}` : "";
244
+ };
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Bridge between {@link CliApp} and the cross-runtime execution detector.
3
+ *
4
+ * @module
5
+ */
6
+ import type * as standardsCrossRuntime from "@eserstack/standards/cross-runtime";
7
+ import type { CliApp } from "./app.ts";
8
+ /**
9
+ * Adapts the app descriptor to the cross-runtime detector's shape.
10
+ *
11
+ * One conversion, used by every handler that needs it — the alternative was a
12
+ * hardcoded ESER_OPTS constant per file, which is exactly what made this tree
13
+ * un-shareable.
14
+ */
15
+ export declare const appOpts: (app: CliApp) => standardsCrossRuntime.CliCommandOptions;
@@ -0,0 +1,13 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Adapts the app descriptor to the cross-runtime detector's shape.
4
+ *
5
+ * One conversion, used by every handler that needs it — the alternative was a
6
+ * hardcoded ESER_OPTS constant per file, which is exactly what made this tree
7
+ * un-shareable.
8
+ */
9
+ export const appOpts = (app) => ({
10
+ command: app.command,
11
+ devCommand: app.devCommand,
12
+ npmPackage: app.npmPackage ?? app.command,
13
+ });
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Identity of the binary the `system` commands are acting on.
3
+ *
4
+ * The system tree used to live in @eserstack/cli with "eser" written into it in
5
+ * a dozen places. It is shared now — `eser`, `noskills` and `laroux` are all
6
+ * shipped binaries built from this workspace, released at the same version by
7
+ * the same pipeline — so the parts that differ between them are gathered here
8
+ * and passed in, rather than each binary getting its own fork of install,
9
+ * update, doctor and completions.
10
+ *
11
+ * @module
12
+ */
13
+ /** What `system install` / `update` / `doctor` need to know about a binary. */
14
+ export type CliApp = {
15
+ /** The command name, e.g. "noskills". Also the installed file name. */
16
+ readonly command: string;
17
+ /** How to run it from a source checkout, for doctor's guidance. */
18
+ readonly devCommand: string;
19
+ /** npm package that provides it, when one does. */
20
+ readonly npmPackage?: string;
21
+ };
22
+ /**
23
+ * Falls back to the root command's own name.
24
+ *
25
+ * A binary that never declares an app descriptor still gets a working
26
+ * `system completions` and `system version`, because both are answerable from
27
+ * the command tree alone.
28
+ */
29
+ export declare const appFromName: (command: string) => CliApp;
@@ -0,0 +1,12 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Falls back to the root command's own name.
4
+ *
5
+ * A binary that never declares an app descriptor still gets a working
6
+ * `system completions` and `system version`, because both are answerable from
7
+ * the command tree alone.
8
+ */
9
+ export const appFromName = (command) => ({
10
+ command,
11
+ devCommand: `pnpm cli ${command}`,
12
+ });
@@ -0,0 +1,14 @@
1
+ import * as shellEnv from "@eserstack/shell/env";
2
+ export { detectShell, type Shell } from "@eserstack/shell/env";
3
+ /**
4
+ * Check if completions are already configured for the shell
5
+ */
6
+ export declare const hasCompletions: (shell: shellEnv.Shell, appName: string) => Promise<boolean>;
7
+ /**
8
+ * Add completions to shell configuration
9
+ */
10
+ export declare const addCompletions: (shell: shellEnv.Shell, appName: string) => Promise<void>;
11
+ /**
12
+ * Remove completions from shell configuration
13
+ */
14
+ export declare const removeCompletions: (shell: shellEnv.Shell, appName: string) => Promise<void>;
@@ -0,0 +1,139 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Shell completions setup utilities - manages shell completion configuration
4
+ *
5
+ * @module
6
+ */
7
+ import * as span from "@eserstack/streams/span";
8
+ import * as streams from "@eserstack/streams";
9
+ import { runtime } from "@eserstack/standards/cross-runtime";
10
+ import * as shellEnv from "@eserstack/shell/env";
11
+ export { detectShell } from "@eserstack/shell/env";
12
+ const COMPLETION_MARKER = "# eser CLI completions";
13
+ /**
14
+ * Read file contents, returns empty string if file doesn't exist
15
+ */
16
+ const readFileOrEmpty = async (path) => {
17
+ try {
18
+ return await runtime.fs.readTextFile(path);
19
+ }
20
+ catch {
21
+ return "";
22
+ }
23
+ };
24
+ /**
25
+ * Check if a file exists
26
+ */
27
+ const fileExists = async (path) => {
28
+ try {
29
+ await runtime.fs.stat(path);
30
+ return true;
31
+ }
32
+ catch {
33
+ return false;
34
+ }
35
+ };
36
+ /**
37
+ * Check if completions are already configured for the shell
38
+ */
39
+ export const hasCompletions = async (shell, appName) => {
40
+ const config = shellEnv.getShellConfig(shell, appName);
41
+ if (config.completionType === "file") {
42
+ return await fileExists(config.completionsFile);
43
+ }
44
+ const content = await readFileOrEmpty(config.rcFile);
45
+ const line = shellEnv.getCompletionSourceLine(shell, appName);
46
+ return content.includes(line);
47
+ };
48
+ /**
49
+ * Add completions to shell configuration
50
+ */
51
+ export const addCompletions = async (shell, appName) => {
52
+ const config = shellEnv.getShellConfig(shell, appName);
53
+ const out = streams.output({
54
+ renderer: streams.renderers.ansi(),
55
+ sink: streams.sinks.stdout(),
56
+ });
57
+ try {
58
+ if (config.completionType === "file") {
59
+ const fishPath = config.completionsFile;
60
+ const dir = runtime.path.dirname(fishPath);
61
+ try {
62
+ await runtime.fs.mkdir(dir, { recursive: true });
63
+ }
64
+ catch {
65
+ // Directory might already exist
66
+ }
67
+ const fishScript = `# eser CLI completions
68
+ # This file is auto-generated. Run 'eser system completions --shell fish' to regenerate.
69
+ complete -c eser -f
70
+ complete -c eser -n "__fish_use_subcommand" -a "codebase" -d "Codebase management tools"
71
+ complete -c eser -n "__fish_use_subcommand" -a "system" -d "Commands related with this CLI"
72
+ complete -c eser -n "__fish_use_subcommand" -a "install" -d "Install eser CLI globally"
73
+ complete -c eser -n "__fish_use_subcommand" -a "update" -d "Update eser CLI to latest version"
74
+ complete -c eser -n "__fish_seen_subcommand_from system" -a "install" -d "Install eser CLI globally"
75
+ complete -c eser -n "__fish_seen_subcommand_from system" -a "uninstall" -d "Uninstall eser CLI globally"
76
+ complete -c eser -n "__fish_seen_subcommand_from system" -a "update" -d "Update eser CLI to latest version"
77
+ complete -c eser -n "__fish_seen_subcommand_from system" -a "completions" -d "Generate shell completion scripts"
78
+ `;
79
+ await runtime.fs.writeTextFile(fishPath, fishScript);
80
+ out.writeln(span.text(" "), span.dim("Created"), span.text(" "), span.cyan(fishPath));
81
+ }
82
+ else {
83
+ const content = await readFileOrEmpty(config.rcFile);
84
+ const line = shellEnv.getCompletionSourceLine(shell, appName);
85
+ if (!content.includes(line)) {
86
+ const addition = `\n${COMPLETION_MARKER}\n${line}\n`;
87
+ await runtime.fs.writeTextFile(config.rcFile, content + addition);
88
+ out.writeln(span.text(" "), span.dim("Added completions to"), span.text(" "), span.cyan(config.rcFile));
89
+ }
90
+ }
91
+ }
92
+ catch (error) {
93
+ out.writeln(span.yellow(` Warning: Could not add shell completions: ${error instanceof Error ? error.message : String(error)}`));
94
+ }
95
+ await out.close();
96
+ };
97
+ /**
98
+ * Remove completions from shell configuration
99
+ */
100
+ export const removeCompletions = async (shell, appName) => {
101
+ const config = shellEnv.getShellConfig(shell, appName);
102
+ const out = streams.output({
103
+ renderer: streams.renderers.ansi(),
104
+ sink: streams.sinks.stdout(),
105
+ });
106
+ try {
107
+ if (config.completionType === "file") {
108
+ const fishPath = config.completionsFile;
109
+ if (await fileExists(fishPath)) {
110
+ await runtime.fs.remove(fishPath);
111
+ out.writeln(span.text(" "), span.dim("Removed"), span.text(" "), span.cyan(fishPath));
112
+ }
113
+ }
114
+ else {
115
+ const content = await readFileOrEmpty(config.rcFile);
116
+ if (content === "") {
117
+ await out.close();
118
+ return;
119
+ }
120
+ const line = shellEnv.getCompletionSourceLine(shell, appName);
121
+ if (!content.includes(line)) {
122
+ await out.close();
123
+ return;
124
+ }
125
+ const filtered = content
126
+ .split("\n")
127
+ .filter((l) => !l.includes("eser system completions"))
128
+ .filter((l) => l !== COMPLETION_MARKER)
129
+ .join("\n")
130
+ .replace(/\n{3,}/g, "\n\n");
131
+ await runtime.fs.writeTextFile(config.rcFile, filtered);
132
+ out.writeln(span.text(" "), span.dim("Removed completions from"), span.text(" "), span.cyan(config.rcFile));
133
+ }
134
+ }
135
+ catch (error) {
136
+ out.writeln(span.yellow(` Warning: Could not remove shell completions: ${error instanceof Error ? error.message : String(error)}`));
137
+ }
138
+ await out.close();
139
+ };
@@ -0,0 +1,3 @@
1
+ import type { CliApp } from "../app.ts";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ export declare const completionsHandler: (ctx: shellArgs.CommandContext, app: CliApp) => shellArgs.CliResult<void>;