@eserstack/codebase 0.0.0-bootstrap.0 → 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.
- package/README.md +302 -0
- package/dist/changelog-gen.d.ts +105 -0
- package/dist/changelog-gen.js +498 -0
- package/dist/changelog-text.d.ts +39 -0
- package/dist/changelog-text.js +82 -0
- package/dist/cli-support.d.ts +140 -0
- package/dist/cli-support.js +244 -0
- package/dist/cli-system/app-opts.d.ts +15 -0
- package/dist/cli-system/app-opts.js +13 -0
- package/dist/cli-system/app.d.ts +29 -0
- package/dist/cli-system/app.js +12 -0
- package/dist/cli-system/handlers/completions-setup.d.ts +14 -0
- package/dist/cli-system/handlers/completions-setup.js +139 -0
- package/dist/cli-system/handlers/completions.d.ts +3 -0
- package/dist/cli-system/handlers/completions.js +79 -0
- package/dist/cli-system/handlers/doctor.d.ts +8 -0
- package/dist/cli-system/handlers/doctor.js +146 -0
- package/dist/cli-system/handlers/info.d.ts +3 -0
- package/dist/cli-system/handlers/info.js +69 -0
- package/dist/cli-system/handlers/install.d.ts +8 -0
- package/dist/cli-system/handlers/install.js +137 -0
- package/dist/cli-system/handlers/mod.d.ts +12 -0
- package/dist/cli-system/handlers/mod.js +13 -0
- package/dist/cli-system/handlers/uninstall.d.ts +3 -0
- package/dist/cli-system/handlers/uninstall.js +60 -0
- package/dist/cli-system/handlers/update.d.ts +76 -0
- package/dist/cli-system/handlers/update.js +310 -0
- package/dist/cli-system/handlers/version-check.d.ts +16 -0
- package/dist/cli-system/handlers/version-check.js +176 -0
- package/dist/cli-system/handlers/version.d.ts +3 -0
- package/dist/cli-system/handlers/version.js +45 -0
- package/dist/cli-system/mod.d.ts +19 -0
- package/dist/cli-system/mod.js +52 -0
- package/dist/commitmsg.d.ts +28 -0
- package/dist/commitmsg.js +232 -0
- package/dist/directive-analysis.d.ts +75 -0
- package/dist/directive-analysis.js +223 -0
- package/dist/ffi-client.d.ts +11 -0
- package/dist/ffi-client.js +12 -0
- package/dist/file-tool.d.ts +96 -0
- package/dist/file-tool.js +274 -0
- package/dist/file-tools-shared.d.ts +81 -0
- package/dist/file-tools-shared.js +276 -0
- package/dist/gh-contributors.d.ts +89 -0
- package/dist/gh-contributors.js +205 -0
- package/dist/gh.d.ts +3 -0
- package/dist/gh.js +64 -0
- package/dist/git-listing.d.ts +27 -0
- package/dist/git-listing.js +69 -0
- package/dist/git.d.ts +172 -0
- package/dist/git.js +277 -0
- package/dist/install.d.ts +34 -0
- package/dist/install.js +421 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +14 -0
- package/dist/mod.d.ts +25 -0
- package/dist/mod.js +8 -0
- package/dist/module.d.ts +10 -0
- package/dist/module.js +221 -0
- package/dist/native-functions.d.ts +1088 -0
- package/dist/native-functions.js +2 -0
- package/dist/npm-externals.d.ts +27 -0
- package/dist/npm-externals.js +34 -0
- package/dist/npm-workspace-specifiers.d.ts +6 -0
- package/dist/npm-workspace-specifiers.js +45 -0
- package/dist/package/loader.d.ts +34 -0
- package/dist/package/loader.js +203 -0
- package/dist/package/mod.d.ts +36 -0
- package/dist/package/mod.js +5 -0
- package/dist/package/types.d.ts +142 -0
- package/dist/package/types.js +32 -0
- package/dist/package/workspace.d.ts +33 -0
- package/dist/package/workspace.js +158 -0
- package/dist/package/writer.d.ts +52 -0
- package/dist/package/writer.js +278 -0
- package/dist/package.json +275 -0
- package/dist/release-notes.d.ts +90 -0
- package/dist/release-notes.js +236 -0
- package/dist/release-tag.d.ts +46 -0
- package/dist/release-tag.js +95 -0
- package/dist/release.d.ts +145 -0
- package/dist/release.js +584 -0
- package/dist/source-mask.d.ts +3 -0
- package/dist/source-mask.js +185 -0
- package/dist/validate-bom.d.ts +5 -0
- package/dist/validate-bom.js +43 -0
- package/dist/validate-case-conflict.d.ts +5 -0
- package/dist/validate-case-conflict.js +43 -0
- package/dist/validate-circular-deps.d.ts +11 -0
- package/dist/validate-circular-deps.js +53 -0
- package/dist/validate-code-conventions.d.ts +22 -0
- package/dist/validate-code-conventions.js +166 -0
- package/dist/validate-commit-msg.d.ts +50 -0
- package/dist/validate-commit-msg.js +182 -0
- package/dist/validate-docs.d.ts +20 -0
- package/dist/validate-docs.js +78 -0
- package/dist/validate-eof.d.ts +5 -0
- package/dist/validate-eof.js +61 -0
- package/dist/validate-error-coverage.d.ts +28 -0
- package/dist/validate-error-coverage.js +93 -0
- package/dist/validate-export-names.d.ts +17 -0
- package/dist/validate-export-names.js +56 -0
- package/dist/validate-filenames.d.ts +5 -0
- package/dist/validate-filenames.js +151 -0
- package/dist/validate-json.d.ts +5 -0
- package/dist/validate-json.js +71 -0
- package/dist/validate-large-files.d.ts +5 -0
- package/dist/validate-large-files.js +41 -0
- package/dist/validate-laroux-boundaries.d.ts +19 -0
- package/dist/validate-laroux-boundaries.js +59 -0
- package/dist/validate-licenses.d.ts +5 -0
- package/dist/validate-licenses.js +137 -0
- package/dist/validate-line-endings.d.ts +5 -0
- package/dist/validate-line-endings.js +47 -0
- package/dist/validate-merge-conflict.d.ts +5 -0
- package/dist/validate-merge-conflict.js +46 -0
- package/dist/validate-mod-exports.d.ts +16 -0
- package/dist/validate-mod-exports.js +56 -0
- package/dist/validate-naming-and-todos.d.ts +5 -0
- package/dist/validate-naming-and-todos.js +70 -0
- package/dist/validate-runtime-js-apis.d.ts +5 -0
- package/dist/validate-runtime-js-apis.js +78 -0
- package/dist/validate-secrets.d.ts +5 -0
- package/dist/validate-secrets.js +82 -0
- package/dist/validate-self-imports.d.ts +5 -0
- package/dist/validate-self-imports.js +78 -0
- package/dist/validate-server-loc.d.ts +32 -0
- package/dist/validate-server-loc.js +94 -0
- package/dist/validate-shebangs.d.ts +5 -0
- package/dist/validate-shebangs.js +33 -0
- package/dist/validate-stream.d.ts +25 -0
- package/dist/validate-stream.js +62 -0
- package/dist/validate-submodules.d.ts +5 -0
- package/dist/validate-submodules.js +43 -0
- package/dist/validate-symlinks.d.ts +5 -0
- package/dist/validate-symlinks.js +46 -0
- package/dist/validate-toml.d.ts +5 -0
- package/dist/validate-toml.js +40 -0
- package/dist/validate-trailing-whitespace.d.ts +5 -0
- package/dist/validate-trailing-whitespace.js +49 -0
- package/dist/validate-yaml.d.ts +5 -0
- package/dist/validate-yaml.js +40 -0
- package/dist/validation/config.d.ts +17 -0
- package/dist/validation/config.js +30 -0
- package/dist/validation/mod.d.ts +71 -0
- package/dist/validation/mod.js +479 -0
- package/dist/validation/registry.d.ts +57 -0
- package/dist/validation/registry.js +256 -0
- package/dist/validation/types.d.ts +101 -0
- package/dist/validation/types.js +2 -0
- package/dist/validation/validators/circular-deps.d.ts +7 -0
- package/dist/validation/validators/circular-deps.js +31 -0
- package/dist/validation/validators/docs.d.ts +7 -0
- package/dist/validation/validators/docs.js +38 -0
- package/dist/validation/validators/error-coverage.d.ts +2 -0
- package/dist/validation/validators/error-coverage.js +46 -0
- package/dist/validation/validators/export-names.d.ts +7 -0
- package/dist/validation/validators/export-names.js +31 -0
- package/dist/validation/validators/laroux-boundaries.d.ts +2 -0
- package/dist/validation/validators/laroux-boundaries.js +29 -0
- package/dist/validation/validators/mod-exports.d.ts +7 -0
- package/dist/validation/validators/mod-exports.js +32 -0
- package/dist/validation/validators/mod.d.ts +11 -0
- package/dist/validation/validators/mod.js +12 -0
- package/dist/validation/validators/server-loc.d.ts +2 -0
- package/dist/validation/validators/server-loc.js +48 -0
- package/dist/versions.d.ts +166 -0
- package/dist/versions.js +349 -0
- package/dist/violation-baseline.d.ts +58 -0
- package/dist/violation-baseline.js +144 -0
- package/dist/walk-stream.d.ts +24 -0
- package/dist/walk-stream.js +55 -0
- package/dist/workspace-discovery.d.ts +60 -0
- package/dist/workspace-discovery.js +130 -0
- package/package.json +225 -1
|
@@ -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
|
+
};
|