@intellectual-frontiers/ergonex 0.2.6 → 0.3.1

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 (83) hide show
  1. package/README.md +2 -0
  2. package/dist/desired.d.ts +27 -0
  3. package/dist/diff.d.ts +12 -0
  4. package/dist/doctor.d.ts +79 -0
  5. package/dist/findings.d.ts +85 -0
  6. package/dist/layout.d.ts +83 -0
  7. package/dist/manifest.d.ts +84 -0
  8. package/dist/mod.d.ts +29 -0
  9. package/dist/mod.js +3927 -0
  10. package/dist/modules/external.d.ts +31 -0
  11. package/dist/modules/mod.d.ts +10 -0
  12. package/dist/modules/name.d.ts +32 -0
  13. package/dist/modules/registry.d.ts +51 -0
  14. package/dist/modules/types.d.ts +178 -0
  15. package/dist/places.d.ts +35 -0
  16. package/dist/plan.d.ts +176 -0
  17. package/dist/platform/k-args.d.ts +7 -0
  18. package/dist/policy.d.ts +39 -0
  19. package/dist/portable.d.ts +111 -0
  20. package/dist/render.d.ts +95 -0
  21. package/dist/setup/evidence.d.ts +58 -0
  22. package/dist/shell/block.d.ts +45 -0
  23. package/dist/shell/mod.d.ts +8 -0
  24. package/dist/shell/snippet.d.ts +43 -0
  25. package/dist/state-record.d.ts +59 -0
  26. package/dist/state.d.ts +64 -0
  27. package/dist/templates/data.d.ts +25 -0
  28. package/dist/templates/hooks.d.ts +13 -0
  29. package/dist/templates/mod.d.ts +16 -0
  30. package/dist/tools/catalog.d.ts +70 -0
  31. package/dist/types.d.ts +51 -0
  32. package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
  33. package/dist/vendor/ts/githost/git.d.ts +16 -0
  34. package/dist/vendor/ts/githost/github.d.ts +15 -0
  35. package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
  36. package/dist/vendor/ts/githost/mod.d.ts +29 -0
  37. package/dist/vendor/ts/githost/remote.d.ts +59 -0
  38. package/dist/vendor/ts/githost/types.d.ts +101 -0
  39. package/dist/vendor/ts/kernel/archive.d.ts +147 -0
  40. package/dist/vendor/ts/kernel/assess.d.ts +247 -0
  41. package/dist/vendor/ts/kernel/attest.d.ts +164 -0
  42. package/dist/vendor/ts/kernel/base64.d.ts +24 -0
  43. package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
  44. package/dist/vendor/ts/kernel/cms.d.ts +106 -0
  45. package/dist/vendor/ts/kernel/cose.d.ts +34 -0
  46. package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
  47. package/dist/vendor/ts/kernel/csv.d.ts +38 -0
  48. package/dist/vendor/ts/kernel/der.d.ts +67 -0
  49. package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
  50. package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
  51. package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
  52. package/dist/vendor/ts/kernel/glob.d.ts +64 -0
  53. package/dist/vendor/ts/kernel/grc.d.ts +356 -0
  54. package/dist/vendor/ts/kernel/http.d.ts +46 -0
  55. package/dist/vendor/ts/kernel/json5.d.ts +46 -0
  56. package/dist/vendor/ts/kernel/layers.d.ts +35 -0
  57. package/dist/vendor/ts/kernel/md5.d.ts +19 -0
  58. package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
  59. package/dist/vendor/ts/kernel/mod.d.ts +89 -0
  60. package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
  61. package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
  62. package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
  63. package/dist/vendor/ts/kernel/otel.d.ts +365 -0
  64. package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
  65. package/dist/vendor/ts/kernel/png.d.ts +124 -0
  66. package/dist/vendor/ts/kernel/render.d.ts +111 -0
  67. package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
  68. package/dist/vendor/ts/kernel/semver.d.ts +94 -0
  69. package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
  70. package/dist/vendor/ts/kernel/signals.d.ts +371 -0
  71. package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
  72. package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
  73. package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
  74. package/dist/vendor/ts/kernel/toml.d.ts +51 -0
  75. package/dist/vendor/ts/kernel/trace.d.ts +169 -0
  76. package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
  77. package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
  78. package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
  79. package/dist/vendor/ts/kernel/xml.d.ts +73 -0
  80. package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
  81. package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
  82. package/ergonex.mjs +3480 -3765
  83. package/package.json +19 -5
@@ -0,0 +1,31 @@
1
+ /**
2
+ * What an external module answers to `--ergonex-manifest` (commons 0001-ergonex FR-008): JSON naming the version of this contract, the module's name and summary and its commands, which a typed decoder
3
+ * checks. Its JSON Schema is made from the same declaration of fields as the decoder, so that a module written in any language can be checked against the schema and `ergonex` against the decoder, and
4
+ * the two cannot differ. A module that does not answer, or whose answer does not decode, runs as an opaque command.
5
+ *
6
+ * @module
7
+ */
8
+ import { type Result } from "@intellectual-frontiers/core";
9
+ import type { JsonObject } from "../vendor/ts/kernel/mod.js";
10
+ /** The version of this contract an external module names. */
11
+ export declare const CONTRACT_VERSION = 1;
12
+ /** How long a module has to answer `--ergonex-manifest`, in milliseconds (0001-ergonex FR-008). */
13
+ export declare const MANIFEST_TIMEOUT_MS = 5000;
14
+ /** The word a module is asked for its manifest with. */
15
+ export declare const MANIFEST_FLAG = "--ergonex-manifest";
16
+ /** A command of an external module. */
17
+ export type ExternalCommand = {
18
+ readonly name: string;
19
+ readonly summary: string;
20
+ };
21
+ /** What an external module answers. */
22
+ export type ExternalManifest = {
23
+ readonly contract: number;
24
+ readonly name: string;
25
+ readonly summary: string;
26
+ readonly commands: readonly ExternalCommand[];
27
+ };
28
+ /** The module's manifest from the text it printed, or why it is not one: not JSON, not the shape, a name that is not a module name, or a contract this `ergonex` does not speak. */
29
+ export declare function decodeExternalManifest(text: string): Result<ExternalManifest, string>;
30
+ /** The JSON Schema (2020-12) of the answer, from the same fields the decoder checks. */
31
+ export declare function externalManifestSchema(): JsonObject;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The module convention of `ergonex` (commons 0001-ergonex FR-004 to FR-011): the name of a module and the nearest names to a typo, the order of the three sources and what a later source hides, the modules a
3
+ * workspace registers, the answer of an external module to `--ergonex-manifest` with its JSON Schema, and the typed contract of a module and a command with its four exit statuses. All pure.
4
+ *
5
+ * @module
6
+ */
7
+ export { CONTRACT_VERSION, decodeExternalManifest, type ExternalCommand, type ExternalManifest, externalManifestSchema, MANIFEST_FLAG, MANIFEST_TIMEOUT_MS, } from "./external.js";
8
+ export { describeNameError, MAX_MODULE_NAME, type ModuleName, moduleName, type NameError, nearestNames } from "./name.js";
9
+ export { type Candidates, decodeRegistered, findModule, type Found, hiddenFindings, programMatches, type RegisteredModule, type Resolved, resolveAll, } from "./registry.js";
10
+ export { type BaseContext, type Command, type CommandDefinition, type Context, defineCommand, type Dispatch, dispatch, EXIT_STATUSES, type EvidenceFacts, type Executed, type ExitStatus, exitCodeOf, type Failure, GLOBAL_OPTIONS, type Globals, globalsOf, type ErgonexModule, type Interact, MODULE_SOURCES, type ModuleSource, type Outcome, type Platform, precedenceOf, type Report, } from "./types.js";
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The name of a module (commons 0001-ergonex FR-005, FR-006): lower-case letters, digits and hyphens, beginning with a letter, at most 32 characters. A name with a path separator, a space, a dot or
3
+ * any other character is refused before it is looked for and is never passed to a shell; a name no module has is answered with the nearest names.
4
+ *
5
+ * @module
6
+ */
7
+ import { type Result } from "@intellectual-frontiers/core";
8
+ import type { Brand } from "@intellectual-frontiers/core";
9
+ /** The name of a module: `ergonex <name>` runs the module `ergonex-<name>`. */
10
+ export type ModuleName = Brand<string, "ModuleName">;
11
+ /** The longest name of a module. */
12
+ export declare const MAX_MODULE_NAME = 32;
13
+ /** Why a text is not a module name. */
14
+ export type NameError = {
15
+ readonly kind: "empty";
16
+ } | {
17
+ readonly kind: "too-long";
18
+ readonly length: number;
19
+ } | {
20
+ readonly kind: "bad-start";
21
+ readonly text: string;
22
+ } | {
23
+ readonly kind: "bad-character";
24
+ readonly text: string;
25
+ readonly character: string;
26
+ };
27
+ /** A refusal as one sentence. */
28
+ export declare function describeNameError(e: NameError): string;
29
+ /** A module name from text, or why it is refused. The text is judged as it is: no trimming and no case folding. */
30
+ export declare function moduleName(text: string): Result<ModuleName, NameError>;
31
+ /** The modules nearest a name nobody has: up to three, within an edit distance of two, the nearest first and, among equals, in alphabetical order. */
32
+ export declare function nearestNames(word: string, names: readonly string[]): readonly string[];
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Finding a module (commons 0001-ergonex FR-003, FR-004, FR-011): the typed built-in modules first, then the modules the workspace registers in `<home>/.ergonex/modules.auto.json`, then the
3
+ * executables named `ergonex-*` on the `PATH`, as Git finds `git-foo` for `git foo`. The first found runs; a module of a later source that it hides is an informational finding.
4
+ *
5
+ * @remarks
6
+ * Pure: the three lists are read by the host layer and handed over; this module orders them, picks the first of each name and names what is hidden. A registered module may carry the SHA-256 of its
7
+ * program, which `ergonex` checks before running it (the check is `programMatches`, the read of the program is the host's).
8
+ *
9
+ * @module
10
+ */
11
+ import { type Result } from "@intellectual-frontiers/core";
12
+ import { type Sha256 } from "../vendor/ts/kernel/mod.js";
13
+ import type { Finding } from "../findings.js";
14
+ import { type ModuleSource } from "./types.js";
15
+ /** A module the workspace registers. */
16
+ export type RegisteredModule = {
17
+ readonly name: string;
18
+ readonly program: string;
19
+ readonly sha256?: Sha256;
20
+ readonly summary?: string;
21
+ };
22
+ /** The modules a `modules.auto.json` registers, or why it cannot be read (a name that is not a module name, a hash that is not a SHA-256, the same name twice). */
23
+ export declare function decodeRegistered(text: string): Result<readonly RegisteredModule[], string>;
24
+ /** A module found: its name, where it was found, what it says it does and where its program is (`built-in` for a typed module). */
25
+ export type Found = {
26
+ readonly name: string;
27
+ readonly source: ModuleSource;
28
+ readonly summary: string;
29
+ readonly where: string;
30
+ readonly sha256?: Sha256;
31
+ };
32
+ /** The modules each source holds. */
33
+ export type Candidates = {
34
+ readonly [S in ModuleSource as Uncapitalize<S>]: readonly Found[];
35
+ };
36
+ /** The modules by name, each the first of its name in the order of the sources, and the ones that first hides. */
37
+ export type Resolved = {
38
+ readonly modules: readonly Found[];
39
+ readonly hidden: readonly {
40
+ readonly module: Found;
41
+ readonly by: Found;
42
+ }[];
43
+ };
44
+ /** The first module of each name in the order of the sources, in the order of the names, and every later one it hides. */
45
+ export declare function resolveAll(c: Candidates): Resolved;
46
+ /** The module a name finds, or undefined. */
47
+ export declare function findModule(c: Candidates, name: string): Found | undefined;
48
+ /** What a hidden module is told as: an informational finding naming both (0001-ergonex FR-004). */
49
+ export declare function hiddenFindings(r: Resolved, today: string): readonly Finding[];
50
+ /** Whether the bytes of a registered module's program are the ones the workspace pinned: true where it pinned none. */
51
+ export declare function programMatches(registered: RegisteredModule, actual: Sha256): boolean;
@@ -0,0 +1,178 @@
1
+ /**
2
+ * The typed contract of a module of `ergonex` (commons 0001-ergonex FR-007, FR-010, FR-022): a module is `ErgonexModule` (its name, its summary and its commands); a command is declared once as data
3
+ * (`defineCommand`: its name, its options with the five every command accepts, its arguments and `run`), parsed once at the boundary into a typed value, and returns a `Result` of a `Report` or a
4
+ * `Failure`; a run ends in one of four statuses. There is no `any`, and a `switch` over a union of statuses or sources is exhaustive.
5
+ *
6
+ * @remarks
7
+ * Pure: a command is given everything the host holds (the environment, the working folder, the day, the platform, where to write and whether to ask) in its `Context`, and does its work through
8
+ * the ports of that context and the host layer it imports, so that the same command is run in a test with a context of the test's making and by the controller with the real one. A module is
9
+ * built in (a value of this type that the compiler checks), registered by the workspace or found on the `PATH`; the last two are programs, which answer `--ergonex-manifest` (see `external.ts`).
10
+ *
11
+ * @module
12
+ */
13
+ import { type Result } from "@intellectual-frontiers/core";
14
+ import { type Args, type Operand, type Spec, type SpecCheck } from "../platform/k-args.js";
15
+ import type { Json } from "../vendor/ts/kernel/mod.js";
16
+ import type { Sha256 } from "../vendor/ts/kernel/mod.js";
17
+ import type { Finding } from "../findings.js";
18
+ import type { Places } from "../places.js";
19
+ import type { RunFacts } from "../setup/evidence.js";
20
+ /** How a run ends: the keys of the code list `ergonex:ExitStatus`. */
21
+ export type ExitStatus = "Ok" | "Findings" | "Usage" | "Environment";
22
+ /** The statuses, in the order of their numbers. */
23
+ export declare const EXIT_STATUSES: readonly ExitStatus[];
24
+ /** The number a run exits with (`ergonex:exitCode`). */
25
+ export declare function exitCodeOf(status: ExitStatus): 0 | 1 | 2 | 3;
26
+ /** Where a module was found: the keys of the code list `ergonex:ModuleSource`, looked in in this order. */
27
+ export type ModuleSource = "BuiltIn" | "Registered" | "Path";
28
+ /** The sources, in the order a module is looked for (`ergonex:precedence`). */
29
+ export declare const MODULE_SOURCES: readonly ModuleSource[];
30
+ /** The place of a source in the order: 1 is looked in first (`ergonex:precedence`). */
31
+ export declare function precedenceOf(source: ModuleSource): number;
32
+ /** What a run did, for a person and as data. */
33
+ export type Report = {
34
+ /** What is written to standard output without `--json`. */
35
+ readonly text: string;
36
+ /** What is written with `--json`, under `data`. */
37
+ readonly data: Json;
38
+ /** What the run found; its worst severity decides the status. */
39
+ readonly findings: readonly Finding[];
40
+ /** The status where it is not the findings' (`render --check` ends in `Findings` where a file would change). */
41
+ readonly status?: ExitStatus;
42
+ /** What the evidence record of the run names besides the findings. */
43
+ readonly facts?: EvidenceFacts;
44
+ /** The facts of a run whose evidence is the setup module's (`setup/host/evidence.ts`): `setup` and `tools`. Where it is given the controller writes the record from it. */
45
+ readonly runFacts?: RunFacts;
46
+ /** The run writes no evidence record: `ergonex shell <shell>` writes no file (0003-host FR-017), and a hook only reads (FR-015). */
47
+ readonly noEvidence?: boolean;
48
+ };
49
+ /** What a run adds to its evidence record (0002-workspace-model FR-042). */
50
+ export type EvidenceFacts = {
51
+ /** The hash of the plan the run made or carried out. */
52
+ readonly planSha256?: Sha256;
53
+ /** The hash of the state record after the run. */
54
+ readonly stateSha256?: Sha256;
55
+ /** The tools probed or installed, with the version of each. */
56
+ readonly tools?: readonly {
57
+ readonly name: string;
58
+ readonly version: string;
59
+ }[];
60
+ /** For a setup run: whether it changed anything (`ergonex:applied`). */
61
+ readonly applied?: boolean;
62
+ };
63
+ /** Why a run could not be done: a command line that does not fit, or a host that cannot do it. */
64
+ export type Failure = {
65
+ readonly kind: "usage" | "environment";
66
+ readonly message: string;
67
+ readonly noEvidence?: boolean;
68
+ };
69
+ /** What a command gives back. */
70
+ export type Outcome = Result<Report, Failure>;
71
+ /** The five options every command accepts (0001-ergonex FR-022); `--help` is the parser's own. */
72
+ export declare const GLOBAL_OPTIONS: {
73
+ home: import("@intellectual-frontiers/terminal/args").ValueOption<string, "none", never>;
74
+ json: import("@intellectual-frontiers/terminal/args").FlagOption<"default", never>;
75
+ sarif: import("@intellectual-frontiers/terminal/args").FlagOption<"default", never>;
76
+ noColor: import("@intellectual-frontiers/terminal/args").FlagOption<"default", never>;
77
+ };
78
+ /** The five options, as they were given. */
79
+ export type Globals = {
80
+ readonly home?: string;
81
+ readonly json: boolean;
82
+ readonly sarif: boolean;
83
+ readonly noColor: boolean;
84
+ };
85
+ /** The globals out of the options a command parsed (a decoder at the boundary: the one place that reads them). */
86
+ export declare function globalsOf(options: Readonly<Record<string, unknown>>): Globals;
87
+ /** The computer a run is on. */
88
+ export type Platform = {
89
+ readonly os: string;
90
+ readonly arch: string;
91
+ readonly windows: boolean;
92
+ };
93
+ /** How a command asks a person a question: only where a terminal is there to answer. */
94
+ export type Interact = {
95
+ readonly terminal: boolean;
96
+ /** The line the person typed, or undefined at the end of the input. */
97
+ readonly ask: (question: string) => Promise<string | undefined>;
98
+ };
99
+ /** What the controller gives every command, besides its words. */
100
+ export type BaseContext = {
101
+ readonly env: Readonly<Record<string, string | undefined>>;
102
+ readonly cwd: string;
103
+ /** The UTC day of the run, `YYYY-MM-DD`. */
104
+ readonly today: string;
105
+ readonly platform: Platform;
106
+ /** The folders Ergonex keeps its own files in (0031-install-locations); undefined where no home can be found. */
107
+ readonly places: Places | undefined;
108
+ /** The typed modules the command holds, which `list` and `help` read. */
109
+ readonly builtins: readonly ErgonexModule[];
110
+ readonly interact: Interact;
111
+ /** The root of the workspace for a run that says `--home` (or not): that, else `$ERGONEX_HOME`, else `$HOME/workspaces`; undefined where none can be found. */
112
+ readonly homeFor: (override: string | undefined) => string | undefined;
113
+ /** What is on standard input, read once (a Git hook is given its refs there). */
114
+ readonly stdin: () => Promise<string>;
115
+ /** Where a run writes what is not its report: a diff or a line of progress, to standard error. */
116
+ readonly note: (text: string) => void;
117
+ };
118
+ /** What a command is given: the base and the options every command has, decoded. */
119
+ export type Context = BaseContext & {
120
+ readonly globals: Globals;
121
+ /** The root of the workspace: `--home`, else `$ERGONEX_HOME`, else `$HOME/workspaces`; undefined where none can be found. */
122
+ readonly home: string | undefined;
123
+ };
124
+ /** What a command did, with the options it was given where they were read. */
125
+ export type Executed = {
126
+ readonly outcome: Outcome;
127
+ readonly globals?: Globals;
128
+ readonly command: string;
129
+ };
130
+ /** A command of a module: declared once, run on words. */
131
+ export type Command = {
132
+ readonly name: string;
133
+ readonly summary: string;
134
+ /** The help, from the declaration. */
135
+ readonly help: (program: string) => string;
136
+ /** Parses the words, and runs the command where they fit; where they do not, the outcome is a usage failure. */
137
+ readonly execute: (words: readonly string[], base: BaseContext) => Promise<Executed>;
138
+ };
139
+ /** A module of `ergonex`: `ergonex <name>` runs it. */
140
+ export type ErgonexModule = {
141
+ readonly name: string;
142
+ readonly summary: string;
143
+ readonly commands: readonly Command[];
144
+ };
145
+ /** The options every command accepts, and the type of a command's own. */
146
+ type GlobalSpec = typeof GLOBAL_OPTIONS;
147
+ /** What a command is declared with. */
148
+ export type CommandDefinition<S extends Spec & GlobalSpec> = {
149
+ readonly name: string;
150
+ readonly summary: string;
151
+ /** Its options: the five of `GLOBAL_OPTIONS` (spread them in) and its own. */
152
+ readonly options: S & SpecCheck<S>;
153
+ readonly operands?: readonly Operand[];
154
+ readonly run: (ctx: Context, args: Args<S>) => Promise<Outcome>;
155
+ };
156
+ /**
157
+ * A command from its declaration: the words are parsed against the options once, here; help is answered and runs nothing; a word that does not fit is a usage failure; and the command runs only on
158
+ * what decoded. The type of what `run` is given is inferred from the declaration.
159
+ */
160
+ export declare function defineCommand<S extends Spec & GlobalSpec>(d: CommandDefinition<S>): Command;
161
+ /** The module's command a word names, and the words left for it. */
162
+ export type Dispatch = {
163
+ readonly kind: "command";
164
+ readonly command: Command;
165
+ readonly words: readonly string[];
166
+ } | {
167
+ readonly kind: "help";
168
+ } | {
169
+ readonly kind: "unknown";
170
+ readonly word: string;
171
+ readonly known: readonly string[];
172
+ };
173
+ /**
174
+ * The command of a module that words name: a module with one command of its own name (`plan`) takes every word; a module of several (`worktree create`) takes its first word as the command's name,
175
+ * asks for its help where there is none or `--help` is first, and says what is unknown.
176
+ */
177
+ export declare function dispatch(m: ErgonexModule, words: readonly string[]): Dispatch;
178
+ export {};
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Where Ergonex keeps what it remembers and installs, as values (commons 0031-install-locations FR-001 to FR-005): what a person edits or other tools read stays with the workspace, in its `.ergonex/` folder beside the
3
+ * repositories, as `.vscode/` does (the manifest, the generated Git configuration, the hooks, the lists of tools and modules); what Ergonex only remembers is in the state folder (the state record, the evidence of
4
+ * every run, its lock); what it installs is in the data folder (the tools) and their shims are in `~/.local/bin` (on Windows, in the tools folder, which the shell snippet puts on the path).
5
+ *
6
+ * @remarks
7
+ * The plan, the state record and the generated files name a file of Ergonex's by a logical path that begins `.ergonex/`. `movedPath` is the one place that says which of them are kept elsewhere than in the workspace
8
+ * and where; any other path is below the root as it always was. Pure: `host/locations.ts` makes the folders from the environment.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * import { movedPath, type Places } from "./places.js";
13
+ * const p: Places = { os: "linux", data: "/d", state: "/s", cache: "/c", tools: "/d/tools", shims: "/h/.local/bin" };
14
+ * movedPath(p, ".ergonex/evidence/2026/11/19/x.json"); // "/s/evidence/2026/11/19/x.json"
15
+ * ```
16
+ *
17
+ * @module
18
+ */
19
+ /** The workspace's own folder, beside the repositories, and the logical name of the files in it. */
20
+ export declare const APP = ".ergonex";
21
+ /** The folders Ergonex keeps what it remembers and installs in. */
22
+ export type Places = {
23
+ readonly os: "linux" | "darwin" | "windows";
24
+ readonly data: string;
25
+ readonly state: string;
26
+ readonly cache: string;
27
+ /** The tools Ergonex installs: `<data>/tools`. */
28
+ readonly tools: string;
29
+ /** Where the shims of the tools it installs are: `~/.local/bin` on Linux and macOS, `<data>/tools/bin` on Windows. */
30
+ readonly shims: string;
31
+ };
32
+ /** Which of Ergonex's own files are kept elsewhere than in the workspace, from the path below `.ergonex/`: the state record, the evidence and the lock (state), and the installed tools (data). */
33
+ export declare function movedKind(rest: string): "state" | "tools" | undefined;
34
+ /** Where a path of Ergonex's is kept where it is not in the workspace: the state folder or the data folder, as the system writes it; undefined for a path that is below the root. */
35
+ export declare function movedPath(places: Places, path: string): string | undefined;
package/dist/plan.d.ts ADDED
@@ -0,0 +1,176 @@
1
+ import { type Sha256 } from "./vendor/ts/kernel/mod.js";
2
+ import type { RepoRef } from "./vendor/ts/githost/mod.js";
3
+ import { type RepoState } from "./state.js";
4
+ import type { BranchName, RepoPath, Version } from "./types.js";
5
+ /** The repository the manifest names, at its path. */
6
+ export type DesiredRepo = {
7
+ readonly path: RepoPath;
8
+ readonly ref: RepoRef;
9
+ /** The URL it is cloned from, with no credential. */
10
+ readonly cloneUrl: string;
11
+ /** The branch to check out when cloning; the remote's default where absent. */
12
+ readonly branch?: BranchName | undefined;
13
+ /** The local Git configuration the policy wants (`core.hooksPath`, the signing settings, the identity); key to value. */
14
+ readonly settings: Readonly<Record<string, string>>;
15
+ };
16
+ /** A worktree the manifest asks for. */
17
+ export type DesiredWorktree = {
18
+ readonly path: RepoPath;
19
+ readonly repo: RepoPath;
20
+ readonly branch: BranchName;
21
+ };
22
+ /** A generated file the templates give: its path and the SHA-256 of its bytes. */
23
+ export type DesiredFile = {
24
+ readonly path: RepoPath;
25
+ readonly sha256: Sha256;
26
+ };
27
+ /** A change of the host outside the workspace, which only `ergonex setup --apply` may plan. */
28
+ export type HostChange = {
29
+ readonly kind: "ConfigureHost";
30
+ readonly target: string;
31
+ readonly what: string;
32
+ } | {
33
+ readonly kind: "InstallTool";
34
+ readonly target: string;
35
+ readonly tool: string;
36
+ readonly version: Version;
37
+ };
38
+ /** What the manifest and its templates want. */
39
+ export type Desired = {
40
+ readonly repos: readonly DesiredRepo[];
41
+ readonly worktrees: readonly DesiredWorktree[];
42
+ readonly files: readonly DesiredFile[];
43
+ readonly hostChanges: readonly HostChange[];
44
+ };
45
+ /** What was observed of a repository. */
46
+ export type ObservedRepo = {
47
+ readonly state: RepoState;
48
+ /** Its local Git configuration, key to value (only the keys the policy sets need be here). */
49
+ readonly config: Readonly<Record<string, string>>;
50
+ /** Another person or agent is working in it (its own checkout or another worktree is in use). */
51
+ readonly busy: boolean;
52
+ };
53
+ /** What was observed of a generated file: its bytes on disk and the bytes the state record holds; undefined where there is none. */
54
+ export type ObservedFile = {
55
+ readonly onDisk?: Sha256 | undefined;
56
+ readonly recorded?: Sha256 | undefined;
57
+ };
58
+ /** What was observed of the workspace. A path with no entry is absent. */
59
+ export type Observed = {
60
+ readonly repos: Readonly<Record<string, ObservedRepo>>;
61
+ readonly worktrees: Readonly<Record<string, RepoState>>;
62
+ readonly files: Readonly<Record<string, ObservedFile>>;
63
+ };
64
+ /** Why an action does nothing. */
65
+ export type SkipWhy = {
66
+ readonly kind: "in-sync";
67
+ } | {
68
+ readonly kind: "uncommitted-changes";
69
+ } | {
70
+ readonly kind: "ahead";
71
+ readonly commits: number;
72
+ } | {
73
+ readonly kind: "diverged";
74
+ readonly ahead: number;
75
+ readonly behind: number;
76
+ } | {
77
+ readonly kind: "locked";
78
+ } | {
79
+ readonly kind: "detached";
80
+ } | {
81
+ readonly kind: "worktree-unneeded";
82
+ } | {
83
+ readonly kind: "worktree-exists";
84
+ } | {
85
+ readonly kind: "base-unavailable";
86
+ readonly state: string;
87
+ } | {
88
+ readonly kind: "file-current";
89
+ } | {
90
+ readonly kind: "file-absent";
91
+ };
92
+ /** Why an action is refused. */
93
+ export type RefuseWhy = {
94
+ readonly kind: "wrong-remote";
95
+ readonly found: string;
96
+ } | {
97
+ readonly kind: "not-a-repository";
98
+ } | {
99
+ readonly kind: "generated-edited";
100
+ };
101
+ /** A step of a plan, of one of the ten kinds of `ergonex:ActionKind` (`kind` is the key). */
102
+ export type Action = {
103
+ readonly kind: "Clone";
104
+ readonly target: RepoPath;
105
+ readonly url: string;
106
+ readonly branch?: BranchName | undefined;
107
+ } | {
108
+ readonly kind: "FastForward";
109
+ readonly target: RepoPath;
110
+ readonly commits: number;
111
+ } | {
112
+ readonly kind: "CreateWorktree";
113
+ readonly target: RepoPath;
114
+ readonly repo: RepoPath;
115
+ readonly branch: BranchName;
116
+ } | {
117
+ readonly kind: "ConfigureRepo";
118
+ readonly target: RepoPath;
119
+ readonly settings: Readonly<Record<string, string>>;
120
+ } | {
121
+ readonly kind: "ConfigureHost";
122
+ readonly target: string;
123
+ readonly what: string;
124
+ } | {
125
+ readonly kind: "WriteGenerated";
126
+ readonly target: RepoPath;
127
+ readonly sha256: Sha256;
128
+ } | {
129
+ readonly kind: "RemoveGenerated";
130
+ readonly target: RepoPath;
131
+ } | {
132
+ readonly kind: "InstallTool";
133
+ readonly target: string;
134
+ readonly tool: string;
135
+ readonly version: Version;
136
+ } | {
137
+ readonly kind: "Skip";
138
+ readonly target: string;
139
+ readonly why: SkipWhy;
140
+ } | {
141
+ readonly kind: "Refuse";
142
+ readonly target: string;
143
+ readonly why: RefuseWhy;
144
+ };
145
+ /** The kind of an action: a key of `ergonex:ActionKind`. */
146
+ export type ActionKind = Action["kind"];
147
+ /** An ordered list of actions: an `ergonex:Plan`, a plan in the sense of PROV-O. */
148
+ export type Plan = {
149
+ readonly actions: readonly Action[];
150
+ };
151
+ /** Whether an action removes what exists (`ergonex:destructive`): only `RemoveGenerated`. It is carried out only where the run says `--allow-destructive` (FR-029). */
152
+ export declare function isDestructive(action: Action | ActionKind): boolean;
153
+ /** Whether an action changes the host outside the workspace (`ergonex:hostChange`): `ConfigureHost` and `InstallTool`, which only `ergonex setup --apply` carries out (FR-030). */
154
+ export declare function isHostChange(action: Action | ActionKind): boolean;
155
+ /** Whether a folder in this state may be removed: never one that holds local work (FR-027). A layer that deletes anything asks this first, with a state it has just observed. */
156
+ export declare function mayRemove(state: RepoState): boolean;
157
+ /** An action in words, for a person: what will be done, or why not. */
158
+ export declare function describeAction(action: Action): string;
159
+ /** A reason for skipping, as one sentence. */
160
+ export declare function describeSkip(why: SkipWhy): string;
161
+ /** A reason for refusing, as one sentence. */
162
+ export declare function describeRefusal(why: RefuseWhy): string;
163
+ /** What a plan is made under. */
164
+ export type PlanOptions = {
165
+ /** True only for `ergonex setup --apply`: the only run whose plan may hold a change of the host (FR-030). */
166
+ readonly setupApply?: boolean;
167
+ };
168
+ /**
169
+ * The plan from what the manifest wants and what was observed. Pure: it reads and writes nothing and never mutates its arguments; the same arguments give the same plan, its actions in the order of
170
+ * their paths (repositories, then worktrees, then generated files, then the changes of the host a setup run may hold).
171
+ */
172
+ export declare function plan(desired: Desired, observed: Observed, options?: PlanOptions): Plan;
173
+ /** The SHA-256 of a plan: of its actions as JSON, in order. The same plan has the same hash; the evidence of a run names it (0002-workspace-model FR-042). */
174
+ export declare function planDigest(p: Plan): Promise<Sha256>;
175
+ /** Whether a plan changes nothing: every action is a `Skip` (FR-025). */
176
+ export declare function isSettled(p: Plan): boolean;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The command-line parser of the library `terminal`, by its package name (commons 0027-commons-libraries FR-004, 0032-lifting-libraries FR-003): what this library uses of it, each name once, re-exported so that
3
+ * the declarations of this package name the library and not the path of its sources.
4
+ *
5
+ * @module
6
+ */
7
+ export { editDistance, flag, formatUsageError, helpOf, parseArgs, value, type Args, type Operand, type Parser, type Spec, type SpecCheck, } from "@intellectual-frontiers/terminal/args";
@@ -0,0 +1,39 @@
1
+ /**
2
+ * What the workspace requires of itself (commons 0002-workspace-model FR-032, FR-033, 0003-host FR-015): the policy the manifest names, and the judgements that follow from it as pure
3
+ * functions: a regulated domain requires signed commits, a commit that is not signed and verified is an error there and a warning elsewhere, a hook that cannot run its checker fails there
4
+ * and says so elsewhere, and a Git host the policy does not allow is told.
5
+ *
6
+ * @module
7
+ */
8
+ import { type Severity } from "./findings.js";
9
+ /** The workspace's policy (`ergonex:WorkspacePolicy`). */
10
+ export type Policy = {
11
+ /** Whether a commit must be signed (OpenPGP or SSH) and verified; always true where a regulated domain is named. */
12
+ readonly requiresSignedCommits: boolean;
13
+ /** The regulated domains the manifest names (the keys of `ifccm:RegulatedDomain`); none means an unregulated workspace. */
14
+ readonly regulatedDomain: readonly string[];
15
+ /** How many days a tool or module outside the catalog is informational before it is a warning. */
16
+ readonly unapprovedGraceDays: number;
17
+ /** The Git hosts a repository of the manifest may be on; empty means any. */
18
+ readonly allowedGitHost: readonly string[];
19
+ };
20
+ /** What the manifest says of the policy, each part optional. */
21
+ export type PolicyInput = {
22
+ readonly requiresSignedCommits?: boolean | undefined;
23
+ readonly regulatedDomain?: readonly string[] | undefined;
24
+ readonly unapprovedGraceDays?: number | undefined;
25
+ readonly allowedGitHost?: readonly string[] | undefined;
26
+ };
27
+ /** The policy from what the manifest says: signed commits are required wherever a regulated domain is named, whatever else it says (FR-032). */
28
+ export declare function policyOf(input?: PolicyInput): Policy;
29
+ /** Whether the workspace names a regulated domain. */
30
+ export declare function isRegulated(policy: Policy): boolean;
31
+ /**
32
+ * The severity of a commit in a managed repository: nothing where the commit is signed and verified; an error where a regulated domain is named; a warning elsewhere (FR-032: "elsewhere
33
+ * the same commit MUST be a warning").
34
+ */
35
+ export declare function unsignedCommitSeverity(policy: Policy, signedAndVerified: boolean): Severity | undefined;
36
+ /** Whether a Git hook that cannot run its checker fails (exits non-zero) or only says so on standard error: it fails where a regulated domain is named (0003-host FR-015). */
37
+ export declare function hookFailsWhenUnableToCheck(policy: Policy): boolean;
38
+ /** Whether a Git host is allowed: any, where the policy lists none. */
39
+ export declare function hostAllowed(policy: Policy, host: string): boolean;