@intellectual-frontiers/ergonex 0.2.6 → 0.3.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 +2 -0
- package/dist/desired.d.ts +27 -0
- package/dist/diff.d.ts +12 -0
- package/dist/doctor.d.ts +79 -0
- package/dist/findings.d.ts +85 -0
- package/dist/layout.d.ts +83 -0
- package/dist/manifest.d.ts +84 -0
- package/dist/mod.d.ts +29 -0
- package/dist/mod.js +4219 -0
- package/dist/modules/external.d.ts +31 -0
- package/dist/modules/mod.d.ts +10 -0
- package/dist/modules/name.d.ts +32 -0
- package/dist/modules/registry.d.ts +51 -0
- package/dist/modules/types.d.ts +178 -0
- package/dist/places.d.ts +35 -0
- package/dist/plan.d.ts +176 -0
- package/dist/platform/k-args.d.ts +28 -0
- package/dist/policy.d.ts +39 -0
- package/dist/portable.d.ts +111 -0
- package/dist/render.d.ts +95 -0
- package/dist/setup/evidence.d.ts +58 -0
- package/dist/shell/block.d.ts +45 -0
- package/dist/shell/mod.d.ts +8 -0
- package/dist/shell/snippet.d.ts +43 -0
- package/dist/state-record.d.ts +59 -0
- package/dist/state.d.ts +64 -0
- package/dist/templates/data.d.ts +25 -0
- package/dist/templates/hooks.d.ts +13 -0
- package/dist/templates/mod.d.ts +16 -0
- package/dist/tools/catalog.d.ts +70 -0
- package/dist/types.d.ts +51 -0
- package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
- package/dist/vendor/ts/githost/git.d.ts +16 -0
- package/dist/vendor/ts/githost/github.d.ts +15 -0
- package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
- package/dist/vendor/ts/githost/mod.d.ts +29 -0
- package/dist/vendor/ts/githost/remote.d.ts +59 -0
- package/dist/vendor/ts/githost/types.d.ts +101 -0
- package/dist/vendor/ts/kernel/archive.d.ts +147 -0
- package/dist/vendor/ts/kernel/args.d.ts +240 -0
- package/dist/vendor/ts/kernel/assess.d.ts +247 -0
- package/dist/vendor/ts/kernel/attest.d.ts +164 -0
- package/dist/vendor/ts/kernel/base64.d.ts +24 -0
- package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
- package/dist/vendor/ts/kernel/cms.d.ts +106 -0
- package/dist/vendor/ts/kernel/commands.d.ts +103 -0
- package/dist/vendor/ts/kernel/cose.d.ts +34 -0
- package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
- package/dist/vendor/ts/kernel/csv.d.ts +38 -0
- package/dist/vendor/ts/kernel/der.d.ts +67 -0
- package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
- package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
- package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
- package/dist/vendor/ts/kernel/glob.d.ts +64 -0
- package/dist/vendor/ts/kernel/grc.d.ts +356 -0
- package/dist/vendor/ts/kernel/http.d.ts +46 -0
- package/dist/vendor/ts/kernel/json5.d.ts +46 -0
- package/dist/vendor/ts/kernel/layers.d.ts +35 -0
- package/dist/vendor/ts/kernel/md5.d.ts +19 -0
- package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
- package/dist/vendor/ts/kernel/mod.d.ts +95 -0
- package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
- package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
- package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
- package/dist/vendor/ts/kernel/otel.d.ts +365 -0
- package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
- package/dist/vendor/ts/kernel/palette.d.ts +44 -0
- package/dist/vendor/ts/kernel/png.d.ts +124 -0
- package/dist/vendor/ts/kernel/rdf-schema.d.ts +190 -0
- package/dist/vendor/ts/kernel/rdf-term.d.ts +162 -0
- package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +148 -0
- package/dist/vendor/ts/kernel/rdf-write.d.ts +25 -0
- package/dist/vendor/ts/kernel/rdf.d.ts +35 -0
- package/dist/vendor/ts/kernel/render.d.ts +111 -0
- package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
- package/dist/vendor/ts/kernel/semver.d.ts +94 -0
- package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
- package/dist/vendor/ts/kernel/signals.d.ts +371 -0
- package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
- package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
- package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
- package/dist/vendor/ts/kernel/toml.d.ts +51 -0
- package/dist/vendor/ts/kernel/trace.d.ts +169 -0
- package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
- package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
- package/dist/vendor/ts/kernel/vt.d.ts +78 -0
- package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
- package/dist/vendor/ts/kernel/width.d.ts +63 -0
- package/dist/vendor/ts/kernel/xml.d.ts +73 -0
- package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
- package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
- package/ergonex.mjs +137 -138
- package/package.json +17 -5
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Paths that are valid on Linux, macOS and Windows alike (commons 0002-workspace-model FR-009 to FR-012): `segment` refuses what one of them would not take, `repoPath` joins segments, a pair
|
|
3
|
+
* of paths that are one after Unicode normalization and case folding are told apart from the ones that are not, and a path longer than Windows' limit is told as it is.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* A segment is refused for: nothing in it, `.` and `..`; `<`, `>`, `:`, `"`, `/`, `\`, `|`, `?`, `*` and the control characters; a trailing dot or space; a Windows device name (`CON`, `PRN`, `AUX`,
|
|
7
|
+
* `NUL`, `COM0` to `COM9`, `LPT0` to `LPT9`, with the superscript digits `¹ ² ³` in their place, and `CONIN$` and `CONOUT$`) in any case and with any extension (`aux.git` is `AUX`); more than 255 bytes in
|
|
8
|
+
* UTF-8; and a name that is not in Unicode normalization form NFC (a name typed on macOS in NFD would be another name there). Case folding is the upper case then the lower case of the
|
|
9
|
+
* NFC form, which makes `Straße` and `STRASSE` one name, as a case-insensitive file system does.
|
|
10
|
+
*
|
|
11
|
+
* @limits It reads no file system: whether a file system is case-insensitive is not asked, because the workspace refuses a collision on every one (0002-workspace-model FR-011). Windows' own
|
|
12
|
+
* rule of 260 counts the terminating character, so a path of 260 characters is the first too long (FR-012); the path of a file inside a repository is not known when its path is chosen (OQ-1).
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
17
|
+
import type { PortableSegment, RepoPath } from "./types.js";
|
|
18
|
+
/** Why a text is not a portable path segment. */
|
|
19
|
+
export type PortableError = {
|
|
20
|
+
readonly kind: "empty";
|
|
21
|
+
} | {
|
|
22
|
+
readonly kind: "dot";
|
|
23
|
+
readonly segment: string;
|
|
24
|
+
} | {
|
|
25
|
+
readonly kind: "forbidden-character";
|
|
26
|
+
readonly segment: string;
|
|
27
|
+
readonly character: string;
|
|
28
|
+
} | {
|
|
29
|
+
readonly kind: "control-character";
|
|
30
|
+
readonly segment: string;
|
|
31
|
+
} | {
|
|
32
|
+
readonly kind: "trailing-dot-or-space";
|
|
33
|
+
readonly segment: string;
|
|
34
|
+
} | {
|
|
35
|
+
readonly kind: "device-name";
|
|
36
|
+
readonly segment: string;
|
|
37
|
+
readonly device: string;
|
|
38
|
+
} | {
|
|
39
|
+
readonly kind: "too-long";
|
|
40
|
+
readonly segment: string;
|
|
41
|
+
readonly bytes: number;
|
|
42
|
+
} | {
|
|
43
|
+
readonly kind: "not-nfc";
|
|
44
|
+
readonly segment: string;
|
|
45
|
+
};
|
|
46
|
+
/** A refusal as one sentence that names the text and what to do. */
|
|
47
|
+
export declare function describePortableError(e: PortableError): string;
|
|
48
|
+
/** Whether a name, on the part before its first dot and without trailing spaces, is a reserved Windows device name in any case. */
|
|
49
|
+
export declare function isDeviceName(name: string): boolean;
|
|
50
|
+
/** The longest name, in bytes of UTF-8. */
|
|
51
|
+
export declare const MAX_SEGMENT_BYTES = 255;
|
|
52
|
+
/** A text as a path segment valid on every operating system, or why not. */
|
|
53
|
+
export declare function segment(text: string): Result<PortableSegment, PortableError>;
|
|
54
|
+
/** Segments as a path of the workspace, each made by `segment`, with `/` between them; the first refusal otherwise. At least one segment. */
|
|
55
|
+
export declare function repoPath(segments: readonly string[]): Result<RepoPath, PortableError>;
|
|
56
|
+
/** The segments of a path of the workspace. */
|
|
57
|
+
export declare function segmentsOf(path: RepoPath): readonly PortableSegment[];
|
|
58
|
+
/** A path with one more segment below it. */
|
|
59
|
+
export declare function child(path: RepoPath, name: PortableSegment): RepoPath;
|
|
60
|
+
/** A path as the operating system writes it below a root: the root, then the segments with the platform's separator. */
|
|
61
|
+
export declare function nativePath(root: string, path: RepoPath, separator: "/" | "\\"): string;
|
|
62
|
+
/** The key under which two names are one on a file system that folds case and normalizes Unicode: NFC, upper case, lower case, NFC. */
|
|
63
|
+
export declare function foldKey(path: string): string;
|
|
64
|
+
/** Two or more paths that are one after folding, with the name each was given. */
|
|
65
|
+
export type Collision = {
|
|
66
|
+
readonly key: string;
|
|
67
|
+
readonly members: readonly {
|
|
68
|
+
readonly id: string;
|
|
69
|
+
readonly path: string;
|
|
70
|
+
}[];
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* The paths that collide: every group of two or more items whose paths are equal after NFC and case folding (an item listed twice collides with itself), each member named, in the order
|
|
74
|
+
* of the first. `id` says what the path is for (a repository's remote, a worktree, a generated file).
|
|
75
|
+
*/
|
|
76
|
+
export declare function collisions(items: readonly {
|
|
77
|
+
readonly id: string;
|
|
78
|
+
readonly path: string;
|
|
79
|
+
}[]): readonly Collision[];
|
|
80
|
+
/** The most characters a path may have on Windows while long paths are off: 259, as the limit of 260 counts the terminating character. */
|
|
81
|
+
export declare const WINDOWS_PATH_LIMIT = 259;
|
|
82
|
+
/** A path that is too long for Windows, as `ergonex:Error` says it. */
|
|
83
|
+
export type PathTooLong = {
|
|
84
|
+
readonly kind: "path-too-long";
|
|
85
|
+
readonly path: string;
|
|
86
|
+
readonly length: number;
|
|
87
|
+
readonly limit: number;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* Whether a path, written as Windows writes it (`C:\Users\a\workspaces\github.com\o\r`), may be used: where long paths are not enabled, more than 259 characters are refused with the path named;
|
|
91
|
+
* where they are, no length is refused.
|
|
92
|
+
*/
|
|
93
|
+
export declare function checkPathLength(windowsPath: string, longPathsEnabled: boolean): Result<string, PathTooLong>;
|
|
94
|
+
/** The most characters of a repository's own path (the root and the repository's path under it) that leaves room for the files inside it (0002-workspace-model FR-048). */
|
|
95
|
+
export declare const REPO_PATH_ROOM = 150;
|
|
96
|
+
/** How a repository's own path stands against the two limits of FR-048. */
|
|
97
|
+
export type RepoPathLength = {
|
|
98
|
+
readonly kind: "fits";
|
|
99
|
+
readonly length: number;
|
|
100
|
+
} | {
|
|
101
|
+
readonly kind: "no-room";
|
|
102
|
+
readonly length: number;
|
|
103
|
+
} | {
|
|
104
|
+
readonly kind: "too-long";
|
|
105
|
+
readonly length: number;
|
|
106
|
+
};
|
|
107
|
+
/**
|
|
108
|
+
* A repository's own path, as the system writes it below the root (`separator` is `\\` on Windows and `/` elsewhere), against the limits of FR-048: up to 150 characters it fits; over 150 it leaves
|
|
109
|
+
* no room for the files inside it; over 259 it is too long, whether or not long paths are enabled, because tools that work with a path do not all take a long one.
|
|
110
|
+
*/
|
|
111
|
+
export declare function repoPathLength(root: string, path: RepoPath, separator: "/" | "\\"): RepoPathLength;
|
package/dist/render.d.ts
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generated files (commons 0003-host FR-003, FR-004, FR-007, FR-008): a template is a TypeScript function from data to a list of `GeneratedFile`s, and a generated file is made only
|
|
3
|
+
* here, so that its path is a `RepoPath` inside the root, its name carries `.auto.` (a Git hook, whose name Git fixes and which lives in `.ergonex/hooks/`, is the one exception), its header names
|
|
4
|
+
* its generator and says it is not to be edited, and its bytes are the same for the same data on every operating system: UTF-8 with no byte-order mark, LF line endings and one final newline.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* There is no template language here: no parser, no `eval`, no `new Function` and no interpolation of data into code; a file's body is text a template built, or JSON a template built as a value, which
|
|
8
|
+
* `generated` writes with the header as its first member (`_generated`). A path that holds `..`, is absolute or names a drive is refused by `repoPath` before any file exists. Two files whose
|
|
9
|
+
* paths are one after Unicode normalization and case folding are both refused and named (0002-workspace-model FR-011), and a file inside a repository's working tree is refused (FR-008).
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
14
|
+
import type { JsonObject } from "./vendor/ts/kernel/mod.js";
|
|
15
|
+
import { type Sha256 } from "./vendor/ts/kernel/mod.js";
|
|
16
|
+
import type { RepoPath } from "./types.js";
|
|
17
|
+
/** The mode of a generated file: `0644`, or `0755` for a script. */
|
|
18
|
+
export type FileMode = "0644" | "0755";
|
|
19
|
+
/** What a template gives of a file's body, by its format; the header is added by `generated`. */
|
|
20
|
+
export type FileBody = {
|
|
21
|
+
readonly format: "json";
|
|
22
|
+
readonly value: JsonObject;
|
|
23
|
+
} | {
|
|
24
|
+
readonly format: "markdown";
|
|
25
|
+
readonly text: string;
|
|
26
|
+
} | {
|
|
27
|
+
readonly format: "yaml";
|
|
28
|
+
readonly text: string;
|
|
29
|
+
} | {
|
|
30
|
+
readonly format: "gitconfig";
|
|
31
|
+
readonly text: string;
|
|
32
|
+
} | {
|
|
33
|
+
readonly format: "envrc";
|
|
34
|
+
readonly text: string;
|
|
35
|
+
} | {
|
|
36
|
+
readonly format: "sh";
|
|
37
|
+
readonly text: string;
|
|
38
|
+
};
|
|
39
|
+
/** A file a template makes (`ergonex:GeneratedFile`). */
|
|
40
|
+
export type GeneratedFile = {
|
|
41
|
+
/** Its path below the root, with `/` between segments. */
|
|
42
|
+
readonly path: RepoPath;
|
|
43
|
+
/** Its bytes as text: header included, LF only, one final newline. */
|
|
44
|
+
readonly content: string;
|
|
45
|
+
readonly mode: FileMode;
|
|
46
|
+
/** The generator the header names, such as `ergonex templates/agents`. */
|
|
47
|
+
readonly generator: string;
|
|
48
|
+
};
|
|
49
|
+
/** Why a file was refused. */
|
|
50
|
+
export type GenerateError = {
|
|
51
|
+
readonly kind: "bad-path";
|
|
52
|
+
readonly path: string;
|
|
53
|
+
readonly reason: string;
|
|
54
|
+
} | {
|
|
55
|
+
readonly kind: "not-auto";
|
|
56
|
+
readonly path: string;
|
|
57
|
+
} | {
|
|
58
|
+
readonly kind: "collision";
|
|
59
|
+
readonly path: string;
|
|
60
|
+
readonly other: string;
|
|
61
|
+
} | {
|
|
62
|
+
readonly kind: "inside-repository";
|
|
63
|
+
readonly path: string;
|
|
64
|
+
readonly repository: string;
|
|
65
|
+
} | {
|
|
66
|
+
readonly kind: "bad-data";
|
|
67
|
+
readonly what: string;
|
|
68
|
+
readonly reason: string;
|
|
69
|
+
};
|
|
70
|
+
/** A refusal as one sentence. */
|
|
71
|
+
export declare function describeGenerateError(e: GenerateError): string;
|
|
72
|
+
/** The folder of the hooks, below the root. */
|
|
73
|
+
export declare const HOOKS_FOLDER = ".ergonex/hooks";
|
|
74
|
+
/** The text of the header of a generated file: what made it, and that it is not to be edited. */
|
|
75
|
+
export declare function headerText(generator: string): string;
|
|
76
|
+
/** Text as a generated file keeps it: LF line endings, no byte-order mark, exactly one final newline. */
|
|
77
|
+
export declare function normalizeText(text: string): string;
|
|
78
|
+
/** Whether a file name carries `.auto.` (`AGENTS.auto.md`) or ends in `.auto` (`.envrc.auto`). */
|
|
79
|
+
export declare function isAutoName(name: string): boolean;
|
|
80
|
+
/** A path as a generated file's: portable segments, never absolute, never `..`, never a drive. */
|
|
81
|
+
export declare function generatedPath(path: string): Result<RepoPath, GenerateError>;
|
|
82
|
+
/**
|
|
83
|
+
* A generated file: its path checked, its name checked to carry `.auto.` (a hook in `.ergonex/hooks/` excepted), its header added, its bytes normalized. The same arguments give the same bytes.
|
|
84
|
+
*/
|
|
85
|
+
export declare function generated(path: string, body: FileBody, options: {
|
|
86
|
+
readonly generator: string;
|
|
87
|
+
readonly mode?: FileMode;
|
|
88
|
+
}): Result<GeneratedFile, GenerateError>;
|
|
89
|
+
/** The SHA-256 of a generated file's bytes. */
|
|
90
|
+
export declare function fileDigest(file: GeneratedFile): Promise<Sha256>;
|
|
91
|
+
/**
|
|
92
|
+
* A set of files checked together: two whose paths are one after folding are refused (each naming the other), and so is one inside the working tree of a repository of the workspace
|
|
93
|
+
* (`repositories` are their paths below the root). The files are returned in the order of their paths, folded, so that the same data gives the same order.
|
|
94
|
+
*/
|
|
95
|
+
export declare function checkFiles(files: readonly GeneratedFile[], repositories: readonly string[]): Result<readonly GeneratedFile[], readonly GenerateError[]>;
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The content of a run's evidence record (commons 0002-workspace-model FR-041 to FR-043): every run of a command of `ergonex` is one record in the IFQS test-record shape (0021-ifqs), named by the
|
|
3
|
+
* run's UTC time and identifier and never overwritten, naming the command and its options, the hash of the plan, the version of each tool probed or installed, the hash of the state record, the
|
|
4
|
+
* findings and the exit status, and holding no credential and no file content; where a check did not run it is `not_run` with its reason, and where a regulated domain is named every tool used
|
|
5
|
+
* is named with its version.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* A record of the quality system is a set of cases (`checkRun`): each fact of the run is a case whose name states it (`ergonex/run: ergonex setup --apply`, `ergonex/plan: sha256 ...`, `ergonex/tool: git 2.43.0`,
|
|
9
|
+
* `ergonex/exit: Findings`), each finding is a failed case with its rule, file and message, and a check that did not run is `not_run`. `runRules` makes the cases and `checkRun` (the quality
|
|
10
|
+
* module) makes the record; the host layer (`host/evidence.ts`) writes it once. The options are only the NAMES of the flags: a value that follows a flag is never kept.
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { type Finding } from "../findings.js";
|
|
15
|
+
import { type Policy } from "../policy.js";
|
|
16
|
+
/** The facts of a run that its evidence names. */
|
|
17
|
+
export type RunFacts = {
|
|
18
|
+
/** The command, such as `setup`, `tools`, `doctor`. */
|
|
19
|
+
readonly command: string;
|
|
20
|
+
/** The arguments as given; only the names of flags are kept in the evidence, never a value. */
|
|
21
|
+
readonly argv: readonly string[];
|
|
22
|
+
/** The SHA-256 of the plan, where the run made one. */
|
|
23
|
+
readonly planSha256?: string;
|
|
24
|
+
/** The SHA-256 of the state record after the run, where there is one. */
|
|
25
|
+
readonly stateSha256?: string;
|
|
26
|
+
/** The version of each tool probed or installed, by name. */
|
|
27
|
+
readonly tools: Readonly<Record<string, string>>;
|
|
28
|
+
readonly findings: readonly Finding[];
|
|
29
|
+
/** The exit status, by name (`Ok`, `Findings`, `Usage`, `Environment`). */
|
|
30
|
+
readonly exit: string;
|
|
31
|
+
/** Checks that did not run, each with its name and why. */
|
|
32
|
+
readonly notRun: readonly {
|
|
33
|
+
readonly name: string;
|
|
34
|
+
readonly reason: string;
|
|
35
|
+
}[];
|
|
36
|
+
readonly policy: Policy;
|
|
37
|
+
};
|
|
38
|
+
/** The options of an argument vector as the evidence keeps them: the names of the flags (`--apply`), never a value (`--home=/x` is `--home`; a word that is not a flag is dropped). */
|
|
39
|
+
export declare function optionNames(argv: readonly string[]): readonly string[];
|
|
40
|
+
/** One rule of a run's record, in the shape the quality module's `checkRun` takes: the rule, what it found (a file and a message each) and, where it did not run, why. */
|
|
41
|
+
export type EvidenceRule = {
|
|
42
|
+
readonly id: string;
|
|
43
|
+
readonly findings: readonly {
|
|
44
|
+
readonly file: string;
|
|
45
|
+
readonly message: string;
|
|
46
|
+
}[];
|
|
47
|
+
readonly notRun?: string;
|
|
48
|
+
};
|
|
49
|
+
/** The cases of a run's record: the facts as passing cases, each failing rule's findings as failing cases, and the checks that did not run. */
|
|
50
|
+
export declare function runRules(facts: RunFacts): readonly EvidenceRule[];
|
|
51
|
+
/** How many cases (and so span ids) the rules make: one for each rule that ran clean or did not run, one for each finding of the others. */
|
|
52
|
+
export declare function caseCount(rules: readonly EvidenceRule[]): number;
|
|
53
|
+
/** The tools whose version a regulated run must name (0002-workspace-model FR-043) that the facts do not: none where no domain is regulated, else `git`, `bun` and `node` and every tool installed. */
|
|
54
|
+
export declare function missingToolVersions(facts: Pick<RunFacts, "tools" | "policy">, used: readonly string[]): readonly string[];
|
|
55
|
+
/** Whether a record's text holds a secret of the shapes the secrets scan knows: the evidence must hold none (0002-workspace-model FR-042). */
|
|
56
|
+
export declare function holdsCredential(recordText: string): boolean;
|
|
57
|
+
/** The name of a run's evidence file below `<home>/.ergonex/evidence/`: the UTC time and the run's identifier (the trace id), so it sorts by time and is never reused. */
|
|
58
|
+
export declare function evidenceFileName(endIso: string, traceId: string): string;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one marked block of a start-up file (commons 0003-host FR-019): `ergonex shell --install` writes a block between the lines `# >>> ergonex >>>` and `# <<< ergonex <<<`, leaves one block where it is
|
|
3
|
+
* run twice, and `--uninstall` removes exactly that block and nothing else, so that a file that had other text is, after both, as it was.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Pure: these are functions from the file's text to its new text; the host layer reads the file, shows the diff, asks and writes. The block is appended at the end of the file with no blank line of
|
|
7
|
+
* its own, so that removing it removes nothing the person wrote; where the file did not end in a newline, one is added before the block and stays after it is removed. A file that uses CRLF gets
|
|
8
|
+
* a block that uses CRLF. A block with a begin and no end is refused rather than guessed at. A file that does not exist is not made (0003-host FR-026): `installBlock` refuses it as `absent`,
|
|
9
|
+
* and the command says how the person creates it.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
14
|
+
/** The line that begins the block. */
|
|
15
|
+
export declare const BEGIN = "# >>> ergonex >>>";
|
|
16
|
+
/** The line that ends the block. */
|
|
17
|
+
export declare const END = "# <<< ergonex <<<";
|
|
18
|
+
/** What is wrong with a file's blocks. */
|
|
19
|
+
export type BlockError = {
|
|
20
|
+
readonly kind: "unterminated";
|
|
21
|
+
readonly line: number;
|
|
22
|
+
} | {
|
|
23
|
+
readonly kind: "unopened";
|
|
24
|
+
readonly line: number;
|
|
25
|
+
}
|
|
26
|
+
/** The start-up file does not exist: ergonex never creates one (0003-host FR-026). */
|
|
27
|
+
| {
|
|
28
|
+
readonly kind: "absent";
|
|
29
|
+
};
|
|
30
|
+
/** A refusal as one sentence. */
|
|
31
|
+
export declare function describeBlockError(e: BlockError): string;
|
|
32
|
+
/** The text of a block: the begin line, the snippet and the end line, each ending in `eol`. */
|
|
33
|
+
export declare function blockText(snippet: string, eol?: "\n" | "\r\n"): string;
|
|
34
|
+
/** What a change to a file comes to. */
|
|
35
|
+
export type Edit = {
|
|
36
|
+
readonly text: string;
|
|
37
|
+
readonly changed: boolean;
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* The file after the block is installed: appended where there is none, replaced where one is there (so that the snippet is the current one), and one only where several are. `existing` is the file's
|
|
41
|
+
* text, or undefined where there is no file, which is refused as `absent`: a start-up file is never created (0003-host FR-026).
|
|
42
|
+
*/
|
|
43
|
+
export declare function installBlock(existing: string | undefined, snippet: string): Result<Edit, BlockError>;
|
|
44
|
+
/** The file after every block is removed, with exactly the lines of the blocks and nothing else; unchanged where there is none. */
|
|
45
|
+
export declare function removeBlock(existing: string): Result<Edit, BlockError>;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shell snippet of `ergonex` and the one marked block of a start-up file (commons 0003-host FR-017 to FR-019): the snippet for each of five shells, the start-up file each reads, and the functions that
|
|
3
|
+
* install the block and remove exactly it. All pure: the files are read and written by `commands/shell.ts`.
|
|
4
|
+
*
|
|
5
|
+
* @module
|
|
6
|
+
*/
|
|
7
|
+
export { BEGIN, type BlockError, blockText, describeBlockError, type Edit, END, installBlock, removeBlock } from "./block.js";
|
|
8
|
+
export { type Completions, createCommand, type HomeSpec, isShell, type RcFacts, rcFileFor, type Shell, SHELLS, snippetFor, type SnippetFacts, } from "./snippet.js";
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/** The shells `ergonex shell` knows. */
|
|
2
|
+
export type Shell = "bash" | "zsh" | "fish" | "pwsh" | "nu";
|
|
3
|
+
/** All the shells, in the order `ergonex shell` names them. */
|
|
4
|
+
export declare const SHELLS: readonly Shell[];
|
|
5
|
+
/** Whether a word names a shell. */
|
|
6
|
+
export declare function isShell(word: string): word is Shell;
|
|
7
|
+
/** Where the root is, for a snippet: the default of the system, or a path a run named. */
|
|
8
|
+
export type HomeSpec = {
|
|
9
|
+
readonly kind: "default";
|
|
10
|
+
} | {
|
|
11
|
+
readonly kind: "path";
|
|
12
|
+
readonly path: string;
|
|
13
|
+
};
|
|
14
|
+
/** What a snippet completes: the modules, and for each the commands it takes after its name. */
|
|
15
|
+
export type Completions = readonly {
|
|
16
|
+
readonly module: string;
|
|
17
|
+
readonly commands: readonly string[];
|
|
18
|
+
}[];
|
|
19
|
+
/** What the snippet is made from. */
|
|
20
|
+
export type SnippetFacts = {
|
|
21
|
+
readonly home: HomeSpec;
|
|
22
|
+
readonly completions: Completions;
|
|
23
|
+
};
|
|
24
|
+
/** The snippet for a shell, ending in one newline. */
|
|
25
|
+
export declare function snippetFor(shell: Shell, facts: SnippetFacts): string;
|
|
26
|
+
/** What the system gives of where a shell's start-up file is. */
|
|
27
|
+
export type RcFacts = {
|
|
28
|
+
readonly home: string;
|
|
29
|
+
readonly xdgConfigHome?: string | undefined;
|
|
30
|
+
readonly zdotdir?: string | undefined;
|
|
31
|
+
readonly windows: boolean;
|
|
32
|
+
readonly darwin: boolean;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* The start-up file a shell reads, which `ergonex shell --install` writes one block into: `~/.bashrc`, `~/.zshrc` (under `$ZDOTDIR` where it is set), `~/.config/fish/conf.d/ergonex.fish`, PowerShell's
|
|
36
|
+
* profile and Nushell's `config.nu`. A run that names `--rc` uses that file instead; this is the default, as a path with `/` between parts (the host gives it its native separators).
|
|
37
|
+
*/
|
|
38
|
+
export declare function rcFileFor(shell: Shell, f: RcFacts): string;
|
|
39
|
+
/**
|
|
40
|
+
* What a person runs to create a start-up file that does not exist (0003-host FR-026): `ergonex shell --install` never creates one, so it says the command and the path. A path with a quote in it is quoted
|
|
41
|
+
* for the shell it names.
|
|
42
|
+
*/
|
|
43
|
+
export declare function createCommand(shell: Shell, rc: string): string;
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The state record (commons 0003-host FR-009 to FR-011): `<home>/.ergonex/state.auto.json`, which holds the path, the SHA-256 and the generator of each generated file as it was written,
|
|
3
|
+
* the hash of the last plan, the version of Ergonex and the day each tool or module outside the catalog was first seen. `ergonex verify` compares the disk with it and it with what the templates give now;
|
|
4
|
+
* `render` and `apply` never overwrite a file whose bytes differ from it.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Pure: it decodes and encodes text and judges what `verify` compares; reading and writing the file is the host layer's. The text is deterministic (keys in order, two spaces, LF, one final
|
|
8
|
+
* newline), so that the record's own hash, which the evidence of a run names, is the same for the same record. The record is data, never trusted: a hash that is not 64 hexadecimal digits is refused.
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
13
|
+
import { type Sha256 } from "./vendor/ts/kernel/mod.js";
|
|
14
|
+
import { type Finding } from "./findings.js";
|
|
15
|
+
import { type GeneratedFile } from "./render.js";
|
|
16
|
+
/** The version of Ergonex the record names. */
|
|
17
|
+
export declare const ERGONEX_VERSION = "0.3.0";
|
|
18
|
+
/** Where the state record is, below the root. */
|
|
19
|
+
export declare const STATE_RECORD_PATH = ".ergonex/state.auto.json";
|
|
20
|
+
/** One generated file as it was written. */
|
|
21
|
+
export type RecordedFile = {
|
|
22
|
+
readonly sha256: Sha256;
|
|
23
|
+
readonly generator: string;
|
|
24
|
+
};
|
|
25
|
+
/** The state record (`ergonex:StateRecord`). */
|
|
26
|
+
export type StateRecord = {
|
|
27
|
+
readonly ergonex: string;
|
|
28
|
+
/** The SHA-256 of the last plan, as `planDigest` gives it; absent before the first apply. */
|
|
29
|
+
readonly plan?: Sha256;
|
|
30
|
+
/** The generated files as written, by path. */
|
|
31
|
+
readonly files: Readonly<Record<string, RecordedFile>>;
|
|
32
|
+
/** The day each tool or module outside the catalog was first seen, by name (never restarted by a later run). */
|
|
33
|
+
readonly firstSeen: Readonly<Record<string, string>>;
|
|
34
|
+
};
|
|
35
|
+
/** A record with nothing in it, as before the first apply. */
|
|
36
|
+
export declare const EMPTY_RECORD: StateRecord;
|
|
37
|
+
/** The record from its text, or why it cannot be read: a hand-edited or damaged record is told, never guessed. */
|
|
38
|
+
export declare function decodeStateRecord(text: string): Result<StateRecord, string>;
|
|
39
|
+
/** The record as text: deterministic, with the header of a generated file as `_generated`. */
|
|
40
|
+
export declare function encodeStateRecord(r: StateRecord): string;
|
|
41
|
+
/** The record after a file was written: its path, hash and generator. */
|
|
42
|
+
export declare function withFile(r: StateRecord, file: GeneratedFile, digest: Sha256): StateRecord;
|
|
43
|
+
/** The record after a generated file was removed. */
|
|
44
|
+
export declare function withoutFile(r: StateRecord, path: string): StateRecord;
|
|
45
|
+
/** What `verify` found of one path. */
|
|
46
|
+
export type FileFacts = {
|
|
47
|
+
readonly path: string;
|
|
48
|
+
/** The SHA-256 of the bytes on disk; absent where there is no file. */
|
|
49
|
+
readonly onDisk?: Sha256 | undefined;
|
|
50
|
+
/** The SHA-256 the record holds; absent where it holds none. */
|
|
51
|
+
readonly recorded?: Sha256 | undefined;
|
|
52
|
+
/** The SHA-256 of what the templates give now; absent where they give no such file. */
|
|
53
|
+
readonly wanted?: Sha256 | undefined;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* What `ergonex verify` reports (0003-host FR-010): a generated file whose bytes differ from the record is an error (a hand edit); a recorded file that is missing, an `.auto.` file the record does
|
|
57
|
+
* not hold and a file the templates would now write differently (a drift) are each a warning. Nothing is changed. `today` is the day the findings are first seen.
|
|
58
|
+
*/
|
|
59
|
+
export declare function verifyFindings(facts: readonly FileFacts[], today: string): readonly Finding[];
|
package/dist/state.d.ts
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import type { RepoRef } from "./vendor/ts/githost/mod.js";
|
|
2
|
+
/** What a host layer read of a path. */
|
|
3
|
+
export type RepoFacts = {
|
|
4
|
+
readonly kind: "absent";
|
|
5
|
+
} | {
|
|
6
|
+
readonly kind: "not-a-repository";
|
|
7
|
+
} | {
|
|
8
|
+
readonly kind: "repository";
|
|
9
|
+
/** The URL of the remote `origin`, as Git holds it (it may hold a credential, which is never kept); undefined where there is none. */
|
|
10
|
+
readonly remote: string | undefined;
|
|
11
|
+
/** A Git lock file (`index.lock`, `HEAD.lock`, `shallow.lock`, `config.lock`, a ref's `.lock`) is present. */
|
|
12
|
+
readonly lockFile: boolean;
|
|
13
|
+
/** HEAD is on no branch. */
|
|
14
|
+
readonly detached: boolean;
|
|
15
|
+
/** The working tree has uncommitted or untracked changes. */
|
|
16
|
+
readonly dirty: boolean;
|
|
17
|
+
/** Commits the branch has that its upstream does not (those on no remote, where it has no upstream). */
|
|
18
|
+
readonly ahead: number;
|
|
19
|
+
/** Commits the upstream has that the branch does not. */
|
|
20
|
+
readonly behind: number;
|
|
21
|
+
};
|
|
22
|
+
/** The observed state of one repository: exactly one of the ten of `ergonex:RepoState`. */
|
|
23
|
+
export type RepoState = {
|
|
24
|
+
readonly kind: "Missing";
|
|
25
|
+
} | {
|
|
26
|
+
readonly kind: "Clean";
|
|
27
|
+
} | {
|
|
28
|
+
readonly kind: "Dirty";
|
|
29
|
+
} | {
|
|
30
|
+
readonly kind: "Ahead";
|
|
31
|
+
readonly commits: number;
|
|
32
|
+
} | {
|
|
33
|
+
readonly kind: "Behind";
|
|
34
|
+
readonly commits: number;
|
|
35
|
+
} | {
|
|
36
|
+
readonly kind: "Diverged";
|
|
37
|
+
readonly ahead: number;
|
|
38
|
+
readonly behind: number;
|
|
39
|
+
} | {
|
|
40
|
+
readonly kind: "Locked";
|
|
41
|
+
} | {
|
|
42
|
+
readonly kind: "Detached";
|
|
43
|
+
} | {
|
|
44
|
+
readonly kind: "WrongRemote";
|
|
45
|
+
readonly found: string;
|
|
46
|
+
} | {
|
|
47
|
+
readonly kind: "NotARepo";
|
|
48
|
+
};
|
|
49
|
+
/** The key of a state: the local name of an `ergonex:RepoState`. */
|
|
50
|
+
export type RepoStateKind = RepoState["kind"];
|
|
51
|
+
/** All the keys, in the order of the code list. */
|
|
52
|
+
export declare const REPO_STATE_KINDS: readonly RepoStateKind[];
|
|
53
|
+
/** The kind of action that is a state's default (`ergonex:defaultAction`): clone where it is missing, fast-forward where it is behind, refuse where it is on the wrong remote or not a repository, skip otherwise. */
|
|
54
|
+
export declare function defaultActionOf(kind: RepoStateKind): "Clone" | "FastForward" | "Skip" | "Refuse";
|
|
55
|
+
/** Whether a state may be fast-forwarded (`ergonex:fastForwardable`): `Behind` alone (0002-workspace-model FR-026). */
|
|
56
|
+
export declare function fastForwardable(kind: RepoStateKind): boolean;
|
|
57
|
+
/** Whether a folder in a state holds work that exists nowhere else (`ergonex:holdsLocalWork`): every state but `Missing`, `Clean` and `Behind` (FR-027). Such a folder is never deleted. */
|
|
58
|
+
export declare function holdsLocalWork(kind: RepoStateKind): boolean;
|
|
59
|
+
/** A remote as it may be said in a finding or a plan: the host and the path, never a credential, `(none)` where there is no remote and `(not a remote of a host)` where it is a path or unreadable. */
|
|
60
|
+
export declare function describeRemote(remote: string | undefined): string;
|
|
61
|
+
/** Whether an observed remote is the repository the manifest names (the same host and path, whatever the scheme). */
|
|
62
|
+
export declare function isExpectedRemote(remote: string | undefined, expected: RepoRef): boolean;
|
|
63
|
+
/** The one state a repository is in, from what was read of it and the repository the manifest names at its path. */
|
|
64
|
+
export declare function classify(facts: RepoFacts, expected: RepoRef): RepoState;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a template is given and what it is (commons 0003-host FR-003): a template is a TypeScript function from the decoded data to a list of generated files, and not text in a template language,
|
|
3
|
+
* so that the compiler checks it and no value of the data can become code. `TemplateData` is the manifest and the two facts a probe gave; `Template` names its generator, which the header of each
|
|
4
|
+
* of its files says.
|
|
5
|
+
*
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import type { Result } from "@intellectual-frontiers/core";
|
|
9
|
+
import type { Manifest } from "../manifest.js";
|
|
10
|
+
import type { GeneratedFile, GenerateError } from "../render.js";
|
|
11
|
+
import type { Tool } from "../tools/catalog.js";
|
|
12
|
+
/** A tool as the resolved catalog lists it: the catalog's own `Tool`. */
|
|
13
|
+
export type ToolEntry = Tool;
|
|
14
|
+
/** What the templates read: the decoded manifest, whether `direnv` is wanted and found (0003-host FR-023), and the resolved tool catalog (the manifest's, empty where it names none). */
|
|
15
|
+
export type TemplateData = {
|
|
16
|
+
readonly manifest: Manifest;
|
|
17
|
+
/** The manifest says `direnv` is wanted and a probe found it. */
|
|
18
|
+
readonly direnv: boolean;
|
|
19
|
+
readonly tools: readonly ToolEntry[];
|
|
20
|
+
};
|
|
21
|
+
/** A template: its generator's name and what it makes. */
|
|
22
|
+
export type Template = {
|
|
23
|
+
readonly name: string;
|
|
24
|
+
readonly render: (data: TemplateData) => Result<readonly GeneratedFile[], readonly GenerateError[]>;
|
|
25
|
+
};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { Template } from "./data.js";
|
|
2
|
+
/** The hooks Ergonex generates, in the order Git runs them. */
|
|
3
|
+
export declare const HOOK_NAMES: readonly ["pre-commit", "commit-msg", "pre-push"];
|
|
4
|
+
/** The name of a hook. */
|
|
5
|
+
export type HookName = (typeof HOOK_NAMES)[number];
|
|
6
|
+
/** Whether a word names a hook. */
|
|
7
|
+
export declare function isHookName(word: string): word is HookName;
|
|
8
|
+
/** What each hook checks, in a sentence. */
|
|
9
|
+
export declare const HOOK_PURPOSE: Readonly<Record<HookName, string>>;
|
|
10
|
+
/** The text of one hook script. `strict` is whether a hook that cannot run its checker fails (it does where a regulated domain is named). */
|
|
11
|
+
export declare function hookScript(name: HookName, strict: boolean): string;
|
|
12
|
+
/** The template: the three scripts, of mode 0755, in `.ergonex/hooks/`. */
|
|
13
|
+
export declare const hooksTemplate: Template;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The templates of IF Workspaces (commons 0003-host FR-003 to FR-007, FR-014, FR-022, FR-023): typed functions from the manifest's data to generated files. `TEMPLATES` is the list, a value the
|
|
3
|
+
* compiler checks; `renderAll` runs them all, checks the files together (no two paths that are one after case folding, none inside a repository's working tree) and gives them in the order of their
|
|
4
|
+
* paths, so that the same data gives the same files on every operating system.
|
|
5
|
+
*
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
9
|
+
import { type GeneratedFile, type GenerateError } from "../render.js";
|
|
10
|
+
import type { Template, TemplateData } from "./data.js";
|
|
11
|
+
export type { Template, TemplateData, ToolEntry } from "./data.js";
|
|
12
|
+
export { HOOK_NAMES, type HookName, hookScript, isHookName } from "./hooks.js";
|
|
13
|
+
/** Every template, in the order of their generators. */
|
|
14
|
+
export declare const TEMPLATES: readonly Template[];
|
|
15
|
+
/** Every generated file the data gives, or every reason one was refused. */
|
|
16
|
+
export declare function renderAll(data: TemplateData): Result<readonly GeneratedFile[], readonly GenerateError[]>;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The tool catalog (commons 0002-workspace-model FR-037, FR-038): the tools a workspace approves, each with one pinned version, what it provides and, for each operating system and
|
|
3
|
+
* architecture, an `https` URL and a SHA-256, decoded once at the boundary and then checked as a whole, so that a pin that is `latest`, a range, an `http` URL, a URL that holds a
|
|
4
|
+
* credential, a hash that is not a SHA-256 or a tool that is only probed (`git`, `bun`, `node`) is refused with its place and none is guessed.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* The catalog is a field of the manifest (`tools`); `manifest.ts` decodes the rest of the manifest, and `decodeCatalog` decodes this field, so that the catalog can be read alone. Pure: nothing
|
|
8
|
+
* is read or fetched here. The operating systems and architectures are the keys of `ergonex:Tool` in the ontology (`linux`, `macos`, `windows`; `x64`, `arm64`).
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
13
|
+
import { type Sha256 } from "../vendor/ts/kernel/mod.js";
|
|
14
|
+
import { type Version } from "../types.js";
|
|
15
|
+
/** The operating systems of a pinned artifact (`ergonex:toolOs`). */
|
|
16
|
+
export type ToolOs = "linux" | "macos" | "windows";
|
|
17
|
+
/** The architectures of a pinned artifact (`ergonex:toolArch`). */
|
|
18
|
+
export type ToolArch = "x64" | "arm64";
|
|
19
|
+
/** All the operating systems. */
|
|
20
|
+
export declare const TOOL_OSES: readonly ToolOs[];
|
|
21
|
+
/** All the architectures. */
|
|
22
|
+
export declare const TOOL_ARCHES: readonly ToolArch[];
|
|
23
|
+
/** How a downloaded artifact is laid out: one executable file, a gzipped tar or a zip. */
|
|
24
|
+
export type ArtifactKind = "file" | "tar.gz" | "zip";
|
|
25
|
+
/** The tools Ergonex only probes and never installs (0002-workspace-model FR-038). */
|
|
26
|
+
export declare const PROBED_TOOLS: readonly string[];
|
|
27
|
+
/** One pinned artifact of a tool, for one operating system and architecture. */
|
|
28
|
+
export type ToolArtifact = {
|
|
29
|
+
readonly os: ToolOs;
|
|
30
|
+
readonly arch: ToolArch;
|
|
31
|
+
/** An `https` URL of the pinned version, holding no credential and never a `latest`. */
|
|
32
|
+
readonly url: string;
|
|
33
|
+
/** The SHA-256 of the bytes at the URL. */
|
|
34
|
+
readonly sha256: Sha256;
|
|
35
|
+
readonly kind: ArtifactKind;
|
|
36
|
+
/** The executable, as a path inside the archive (or the file's own name for kind `file`), with `/` between parts. */
|
|
37
|
+
readonly bin: string;
|
|
38
|
+
};
|
|
39
|
+
/** A tool of the catalog (`ergonex:Tool`): a name, one pinned version, what it provides and its artifacts. */
|
|
40
|
+
export type Tool = {
|
|
41
|
+
readonly name: string;
|
|
42
|
+
readonly version: Version;
|
|
43
|
+
/** The commands it provides on the path of the shims; the tool's own name where the manifest names none. */
|
|
44
|
+
readonly provides: readonly string[];
|
|
45
|
+
readonly artifacts: readonly ToolArtifact[];
|
|
46
|
+
};
|
|
47
|
+
/** The tool catalog (`ergonex:ToolCatalog`). */
|
|
48
|
+
export type ToolCatalog = {
|
|
49
|
+
readonly tools: readonly Tool[];
|
|
50
|
+
};
|
|
51
|
+
/** One thing wrong in the catalog, with where (as `$.tools[1].artifacts[0].url`). */
|
|
52
|
+
export type CatalogIssue = {
|
|
53
|
+
readonly rule: "ergonex/catalog-shape" | "ergonex/catalog-tool";
|
|
54
|
+
readonly path: string;
|
|
55
|
+
readonly message: string;
|
|
56
|
+
};
|
|
57
|
+
/** Whether a relative path inside an archive is safe: no `..`, no absolute path, no drive letter, no backslash, no empty part. */
|
|
58
|
+
export declare function safeInnerPath(path: string): boolean;
|
|
59
|
+
/** Why a URL may not be a pin, or undefined where it may: `https` only (`loopbackHttp` also allows `http` to the loopback interface, for a test's own server; the catalog's decoder does so only where it is told to, by `ergonex` for a person's own local mirror), no credential, no query that carries one, and no `latest` in its path. */
|
|
60
|
+
export declare function urlProblem(text: string, loopbackHttp?: boolean): string | undefined;
|
|
61
|
+
/** The catalog from the manifest's `tools` value, or every issue found: the shape first (the first field that is wrong, by its path), then the meaning, all of it. */
|
|
62
|
+
export declare function decodeCatalog(input: unknown, loopbackHttp?: boolean): Result<ToolCatalog, readonly CatalogIssue[]>;
|
|
63
|
+
/** A tool of the catalog by name. */
|
|
64
|
+
export declare function toolNamed(catalog: ToolCatalog, name: string): Tool | undefined;
|
|
65
|
+
/** The pinned artifact of a tool for an operating system and architecture, or undefined where the catalog pins none for it. */
|
|
66
|
+
export declare function artifactFor(tool: Tool, os: ToolOs, arch: ToolArch): ToolArtifact | undefined;
|
|
67
|
+
/** The folder of an installed tool below the tools folder (`<data>/tools`, 0002-workspace-model FR-039 and 0031-install-locations), `<name>/<version>`, with `/` between parts. */
|
|
68
|
+
export declare function installDirOf(tool: Pick<Tool, "name" | "version">): string;
|
|
69
|
+
/** Whether a name is a command that a tool of the catalog provides (the catalog's `provides`, with each tool's own name). */
|
|
70
|
+
export declare function providedBy(catalog: ToolCatalog, command: string): Tool | undefined;
|