@intellectual-frontiers/ergonex 0.2.5 → 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 +140 -140
- package/package.json +17 -5
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { type Attributes, type LogRecord, type SpanData, type SpanEvent } from "./otel.js";
|
|
2
|
+
import { type Capabilities, type MarkKind } from "./palette.js";
|
|
3
|
+
import { type Declarations, type Registry, type Source, type SpanStart } from "./signals.js";
|
|
4
|
+
/** How the console writes: see the module. */
|
|
5
|
+
export type Mode = "attended" | "plain" | "quiet" | "silent" | "json";
|
|
6
|
+
/** Every mode, in a fixed order. */
|
|
7
|
+
export declare const MODES: readonly Mode[];
|
|
8
|
+
/** A mode by its name; undefined for another text. */
|
|
9
|
+
export declare function parseMode(text: string): Mode | undefined;
|
|
10
|
+
/** The mode to use: the one asked for where it names one, else `attended` at a terminal and `plain` elsewhere (FR-026). */
|
|
11
|
+
export declare function chooseMode(facts: {
|
|
12
|
+
readonly requested?: string | undefined;
|
|
13
|
+
readonly tty: boolean;
|
|
14
|
+
}): Mode;
|
|
15
|
+
/** What the renderer is given: the processor's signals, a failed export, a tick of the clock (to redraw elapsed times), the end of the run. */
|
|
16
|
+
export type Input = {
|
|
17
|
+
readonly kind: "span-start";
|
|
18
|
+
readonly span: SpanStart;
|
|
19
|
+
readonly source: Source;
|
|
20
|
+
} | {
|
|
21
|
+
readonly kind: "span-event";
|
|
22
|
+
readonly span: SpanStart;
|
|
23
|
+
readonly event: SpanEvent;
|
|
24
|
+
readonly source: Source;
|
|
25
|
+
} | {
|
|
26
|
+
readonly kind: "span-end";
|
|
27
|
+
readonly span: SpanData;
|
|
28
|
+
readonly source: Source;
|
|
29
|
+
} | {
|
|
30
|
+
readonly kind: "log";
|
|
31
|
+
readonly record: LogRecord;
|
|
32
|
+
readonly source: Source;
|
|
33
|
+
} | {
|
|
34
|
+
readonly kind: "export-warning";
|
|
35
|
+
readonly message: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly kind: "tick";
|
|
38
|
+
} | {
|
|
39
|
+
readonly kind: "finish";
|
|
40
|
+
};
|
|
41
|
+
/** What a renderer is made with. */
|
|
42
|
+
export type RenderConfig = {
|
|
43
|
+
readonly mode: Mode;
|
|
44
|
+
/** What the terminal shows: colour, emoji, its width (a `Look` of `runtime/tty.ts` is one). */
|
|
45
|
+
readonly look: Capabilities;
|
|
46
|
+
/** The registry that gives each kind its presentation role. */
|
|
47
|
+
readonly registry: Registry<Declarations>;
|
|
48
|
+
/** A signal's text from its kind and attributes; `defaultText` where not given (a log record's string body comes first). */
|
|
49
|
+
readonly text?: (name: string, attributes: Attributes) => string;
|
|
50
|
+
/** The most lines the live region takes (10 by default, at least 2); the spans beyond are counted on its last line. */
|
|
51
|
+
readonly maxLive?: number;
|
|
52
|
+
};
|
|
53
|
+
type Known = {
|
|
54
|
+
readonly depth: number;
|
|
55
|
+
readonly shown: boolean;
|
|
56
|
+
readonly anchor: string | undefined;
|
|
57
|
+
};
|
|
58
|
+
type Progress = {
|
|
59
|
+
readonly done: number;
|
|
60
|
+
readonly total: number | undefined;
|
|
61
|
+
};
|
|
62
|
+
type Live = {
|
|
63
|
+
readonly key: string;
|
|
64
|
+
readonly anchor: string | undefined;
|
|
65
|
+
readonly depth: number;
|
|
66
|
+
readonly text: string;
|
|
67
|
+
readonly start: bigint;
|
|
68
|
+
readonly progress: Progress | undefined;
|
|
69
|
+
};
|
|
70
|
+
/** The renderer's state: what is open, what the screen shows of the live region, the warnings kept for the end. */
|
|
71
|
+
export type State = {
|
|
72
|
+
readonly config: RenderConfig;
|
|
73
|
+
/** Every span started and not ended, shown or not, by trace and span id. */
|
|
74
|
+
readonly spans: ReadonlyMap<string, Known>;
|
|
75
|
+
/** The shown spans in progress, in the order they started. */
|
|
76
|
+
readonly live: readonly Live[];
|
|
77
|
+
/** The lines of the live region on the screen (attended). */
|
|
78
|
+
readonly drawn: number;
|
|
79
|
+
/** The export warnings, each once, said at the end. */
|
|
80
|
+
readonly warnings: readonly string[];
|
|
81
|
+
/** The last source seen, for the records `json` writes of its own. */
|
|
82
|
+
readonly source: Source | undefined;
|
|
83
|
+
/** Whether the run has finished; nothing is written after. */
|
|
84
|
+
readonly finished: boolean;
|
|
85
|
+
};
|
|
86
|
+
/** A reducer's step: the next state and the frames to write (empty for none). */
|
|
87
|
+
export type Step = {
|
|
88
|
+
readonly state: State;
|
|
89
|
+
readonly frames: string;
|
|
90
|
+
};
|
|
91
|
+
/** The state a renderer starts in. */
|
|
92
|
+
export declare function initial(config: RenderConfig): State;
|
|
93
|
+
/** A text with every control character but the line feed replaced (a tab by a space, the rest by `?`), so it never moves the cursor. */
|
|
94
|
+
export declare function clean(text: string): string;
|
|
95
|
+
/**
|
|
96
|
+
* The text of a signal by default: a span's is its kind and its attributes' values, in their order, separated by spaces (`build site`); a
|
|
97
|
+
* log record's is its attributes' values alone, or its kind where it has none (a log record with a string body shows the body).
|
|
98
|
+
*/
|
|
99
|
+
export declare function defaultText(name: string, attributes: Attributes, signal?: "span" | "log"): string;
|
|
100
|
+
/** A duration in nanoseconds as a person reads it: `420ms`, `1.2s`, `3m04s`, `2h05m` (cut, never rounded up; a negative one is `0ms`). */
|
|
101
|
+
export declare function duration(ns: bigint): string;
|
|
102
|
+
/** How far a span has come: `done/total` and the percentage where there is a positive total, else `done`. */
|
|
103
|
+
export declare function progressText(done: number, total?: number): string;
|
|
104
|
+
/** How a span ended, as a mark: a `skipped` or `cancelled` event first, then its status. */
|
|
105
|
+
export declare function outcomeOf(span: SpanData): MarkKind;
|
|
106
|
+
/**
|
|
107
|
+
* The next state and the frames to write for an input at the time `now` (nanoseconds since the Unix epoch). Pure: the same state, input
|
|
108
|
+
* and time give the same step. After `finish`, every input gives no frame.
|
|
109
|
+
*/
|
|
110
|
+
export declare function render(state: State, input: Input, now: bigint): Step;
|
|
111
|
+
export {};
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The operating system's own scheduled job, planned without touching it (commons 0005-typescript-runtime FR-046): from a job's name, the
|
|
3
|
+
* argument vector it runs, its working folder, its environment and when it runs, `planJob` gives the files to write and the commands that
|
|
4
|
+
* load and unload the job, for one of three schedulers, and writes or runs nothing itself (`runtime/schedule.ts` does).
|
|
5
|
+
*
|
|
6
|
+
* | OS | what is planned | loaded by |
|
|
7
|
+
* | ------- | ---------------------------------------------------------------------------- | ------------------------------------------------ |
|
|
8
|
+
* | Linux | a systemd user service (one shot) and its timer in `~/.config/systemd/user/` | `systemctl --user enable --now <label>.timer` |
|
|
9
|
+
* | macOS | a LaunchAgent, `~/Library/LaunchAgents/<label>.plist` | `launchctl bootstrap gui/<uid> <plist>` |
|
|
10
|
+
* | Windows | a `.cmd` file in `~\AppData\Local\<folder>\` and a Task Scheduler task | `schtasks /Create /F /TN <folder>\<name> /TR ...` |
|
|
11
|
+
*
|
|
12
|
+
* The caller names its jobs with an owner: a reverse-DNS `domain` (`org.example.backup`), which makes the launchd label and the systemd
|
|
13
|
+
* unit `<domain>.<name>`, and a Task Scheduler `folder` (`Example`), which makes the task `<folder>\<name>` and the folder of its `.cmd`
|
|
14
|
+
* file. Paths in `files` are relative to the user's home folder, with `/` between their parts, so the caller writes them on any host; the
|
|
15
|
+
* absolute paths the commands need (the plist for `launchctl`, the `.cmd` file for `schtasks`) are built from the given home folder with
|
|
16
|
+
* the target's own separator.
|
|
17
|
+
*
|
|
18
|
+
* When a job runs is one of five kinds, each expressed on every scheduler at the same minutes of local time:
|
|
19
|
+
*
|
|
20
|
+
* | kind | systemd `OnCalendar=` | launchd `StartCalendarInterval` | `schtasks` |
|
|
21
|
+
* | --------- | ---------------------- | ---------------------------------------- | ------------------------------------ |
|
|
22
|
+
* | `minutes` | `*-*-* *:00/N:00` | one `Minute` dict for each of 0, N, 2N.. | `/SC MINUTE /MO N /ST 00:00` |
|
|
23
|
+
* | `hourly` | `*-*-* *:MM:00` | `Minute` | `/SC HOURLY /ST 00:MM` |
|
|
24
|
+
* | `daily` | `*-*-* HH:MM:00` | `Hour`, `Minute` | `/SC DAILY /ST HH:MM` |
|
|
25
|
+
* | `weekly` | `Fri *-*-* HH:MM:00` | `Weekday` (0 is Sunday), `Hour`, `Minute` | `/SC WEEKLY /D FRI /ST HH:MM` |
|
|
26
|
+
* | `monthly` | `*-*-DD HH:MM:00` | `Day`, `Hour`, `Minute` | `/SC MONTHLY /D DD /ST HH:MM` |
|
|
27
|
+
*
|
|
28
|
+
* `minutes` takes a divisor of 60 below 60 (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30), so that all three run at the same minutes of every
|
|
29
|
+
* hour; `monthly` takes a day from 1 to 28, which every month has.
|
|
30
|
+
*
|
|
31
|
+
* Every argument is quoted for the file that carries it, and what cannot be carried safely is refused with a `ScheduleError`, never
|
|
32
|
+
* altered. systemd's `ExecStart=` and `Environment=` get double quotes with C escapes (`\\`, `\"`, `\t`, `\xHH`), `%%` for `%` and, in
|
|
33
|
+
* `ExecStart=`, `$$` for `$`; a carriage return, a line feed or NUL is refused, and so is an argument that is only `;` and a program that
|
|
34
|
+
* begins with one of systemd's prefixes (`@-:+!|`). The `.cmd` file gets double quotes around any argument that is not plain, `%%` for `%`
|
|
35
|
+
* (a batch file's own escape, inside quotes or not), the trailing backslashes of a quoted argument doubled (the C runtime's rule), delayed
|
|
36
|
+
* expansion turned off (so `!` is plain) and the UTF-8 code page; a double quote (cmd.exe's quoting cannot hold one safely) and any
|
|
37
|
+
* control character but tab are refused. The plist is written with the kernel's XML writer, which escapes the markup; a character XML
|
|
38
|
+
* cannot carry (a control character but tab and line feed, a carriage return, which XML reads as a line feed, or a lone surrogate) is
|
|
39
|
+
* refused.
|
|
40
|
+
*
|
|
41
|
+
* Taken from Stolos's `src/archon/export/schedule.ts` (spec 092), which built the jobs of `stolos export schedule` from an export job and
|
|
42
|
+
* a fleet. What changed: the job is generic (an argument vector, a working folder, an environment, an optional log) and named by the
|
|
43
|
+
* caller's owner instead of Stolos's; the schedule is a discriminated union, with every N minutes added; the files are relative to the
|
|
44
|
+
* home folder; the plist is built as an XML tree; quoting follows each format's rules in full and refuses what it cannot hold, where Stolos
|
|
45
|
+
* quoted a few characters; and errors are values.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```ts
|
|
49
|
+
* import { jobName, planJob, schedule } from "./schedule.js";
|
|
50
|
+
* const name = jobName("backup");
|
|
51
|
+
* const when = schedule({ kind: "daily", hour: 6, minute: 10 });
|
|
52
|
+
* if (name.kind === "ok" && when.kind === "ok") {
|
|
53
|
+
* const plan = planJob(
|
|
54
|
+
* { name: name.value, owner: { domain: "org.example", folder: "Example" }, argv: ["/usr/bin/backup", "--all"], workdir: "/srv", when: when.value },
|
|
55
|
+
* { os: "linux", home: "/home/ada" },
|
|
56
|
+
* );
|
|
57
|
+
* // plan.value.files: .config/systemd/user/org.example.backup.service and .timer, with OnCalendar=*-*-* 06:10:00
|
|
58
|
+
* // plan.value.install: systemctl --user daemon-reload, then systemctl --user enable --now org.example.backup.timer
|
|
59
|
+
* }
|
|
60
|
+
* ```
|
|
61
|
+
*
|
|
62
|
+
* @module
|
|
63
|
+
*/
|
|
64
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
65
|
+
import type { Brand } from "@intellectual-frontiers/core";
|
|
66
|
+
/** The schedulers a job can be planned for: systemd on Linux, launchd on macOS, Task Scheduler on Windows. */
|
|
67
|
+
export type SchedulerOs = "linux" | "darwin" | "windows";
|
|
68
|
+
/** Why a job cannot be planned: the field at fault (`name`, `argv[2]`, `env.PATH`, `when.minute`...), and whether its value is not valid or cannot be carried safely. */
|
|
69
|
+
export type ScheduleError = {
|
|
70
|
+
readonly kind: "schedule";
|
|
71
|
+
readonly field: string;
|
|
72
|
+
readonly reason: "invalid" | "unsafe";
|
|
73
|
+
readonly message: string;
|
|
74
|
+
};
|
|
75
|
+
/** A schedule error as one line: `argv[1]: a line feed cannot be carried in a systemd unit`. */
|
|
76
|
+
export declare function formatScheduleError(e: ScheduleError): string;
|
|
77
|
+
/** A job's name, safe in a file name, a unit name, a plist label and a task name: 1 to 64 lowercase letters, digits and dashes, beginning and ending with a letter or digit. */
|
|
78
|
+
export type JobName = Brand<string, "JobName">;
|
|
79
|
+
/** A job's name, validated. */
|
|
80
|
+
export declare function jobName(s: string): Result<JobName, ScheduleError>;
|
|
81
|
+
/** The day of a weekly schedule. */
|
|
82
|
+
export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
|
|
83
|
+
/** When a job runs, in local time: every N minutes on the clock, every hour at a minute, every day, every week on a day, or every month on a day. */
|
|
84
|
+
export type When = {
|
|
85
|
+
readonly kind: "minutes";
|
|
86
|
+
readonly every: number;
|
|
87
|
+
} | {
|
|
88
|
+
readonly kind: "hourly";
|
|
89
|
+
readonly minute: number;
|
|
90
|
+
} | {
|
|
91
|
+
readonly kind: "daily";
|
|
92
|
+
readonly hour: number;
|
|
93
|
+
readonly minute: number;
|
|
94
|
+
} | {
|
|
95
|
+
readonly kind: "weekly";
|
|
96
|
+
readonly day: Weekday;
|
|
97
|
+
readonly hour: number;
|
|
98
|
+
readonly minute: number;
|
|
99
|
+
} | {
|
|
100
|
+
readonly kind: "monthly";
|
|
101
|
+
readonly day: number;
|
|
102
|
+
readonly hour: number;
|
|
103
|
+
readonly minute: number;
|
|
104
|
+
};
|
|
105
|
+
/** A `When` whose numbers are in range, made only by `schedule`. */
|
|
106
|
+
export type Schedule = Brand<When, "Schedule">;
|
|
107
|
+
/** The intervals `minutes` takes: the divisors of 60 below 60, so every scheduler runs the job at the same minutes of every hour. */
|
|
108
|
+
export declare const MINUTE_STEPS: readonly number[];
|
|
109
|
+
/** A schedule, validated: hours 0 to 23, minutes 0 to 59, a day of the month 1 to 28, a weekday by its three letters, a step of `MINUTE_STEPS`. */
|
|
110
|
+
export declare function schedule(when: When): Result<Schedule, ScheduleError>;
|
|
111
|
+
/** When a schedule runs, as a sentence's end: `every 15 minutes`, `every hour at minute 05`, `every day at 06:10`, `every Friday at 08:00`, `on day 3 of every month at 05:00`. */
|
|
112
|
+
export declare function describeSchedule(s: Schedule): string;
|
|
113
|
+
/** systemd's `OnCalendar=` expression for a schedule (systemd.time(7)). */
|
|
114
|
+
export declare function onCalendar(s: Schedule): string;
|
|
115
|
+
/** One launchd calendar interval: the job runs whenever every key given matches (`Weekday` 0 is Sunday). */
|
|
116
|
+
export type CalendarInterval = {
|
|
117
|
+
readonly Minute: number;
|
|
118
|
+
readonly Hour?: number;
|
|
119
|
+
readonly Day?: number;
|
|
120
|
+
readonly Weekday?: number;
|
|
121
|
+
};
|
|
122
|
+
/** launchd's `StartCalendarInterval` for a schedule: one interval, or one for each minute of the hour the job runs at. */
|
|
123
|
+
export declare function calendarIntervals(s: Schedule): readonly CalendarInterval[];
|
|
124
|
+
/** The arguments `schtasks /Create` takes for a schedule, from `/SC` on. */
|
|
125
|
+
export declare function schtasksSchedule(s: Schedule): readonly string[];
|
|
126
|
+
/**
|
|
127
|
+
* One argument as a word of systemd's `ExecStart=` (systemd.service(5), "Command lines"): as it is where it is plain, else in double
|
|
128
|
+
* quotes with C escapes, `%%` for a specifier's `%` and `$$` for a variable's `$`. Refused: NUL, a carriage return or a line feed; an
|
|
129
|
+
* argument that is only `;` (a command separator); and, for the program (`first`), an empty one or one that begins with a prefix
|
|
130
|
+
* character (`@-:+!|`).
|
|
131
|
+
*/
|
|
132
|
+
export declare function quoteSystemdArg(arg: string, first?: boolean): Result<string, ScheduleError>;
|
|
133
|
+
/** An argument vector as systemd's `ExecStart=` value, each word quoted by `quoteSystemdArg`; the first refusal names its index. */
|
|
134
|
+
export declare function quoteSystemdArgs(argv: readonly string[]): Result<string, ScheduleError>;
|
|
135
|
+
/**
|
|
136
|
+
* One argument as a word of a line of a `.cmd` file that runs a program: as it is where it is plain, else in double quotes, inside which
|
|
137
|
+
* cmd.exe takes `&|<>^()` as text; `%%` for `%` (a batch file's escape, which holds inside quotes too); and the trailing backslashes of a
|
|
138
|
+
* quoted argument doubled, so the C runtime's parser does not read the closing quote as an escaped one (not for the program, `first`,
|
|
139
|
+
* whose name the parser takes as written). Refused: a double quote, which cmd.exe's quoting cannot hold safely, and any control character
|
|
140
|
+
* but tab; and, for the program, an empty one. Expects delayed expansion off (the `.cmd` file turns it off), so `!` is plain text.
|
|
141
|
+
*/
|
|
142
|
+
export declare function quoteCmdArg(arg: string, first?: boolean): Result<string, ScheduleError>;
|
|
143
|
+
/** An argument vector as a command of a `.cmd` file, each word quoted by `quoteCmdArg`; the first refusal names its index. */
|
|
144
|
+
export declare function quoteCmdArgs(argv: readonly string[]): Result<string, ScheduleError>;
|
|
145
|
+
/** Who a job belongs to: a reverse-DNS `domain` for the launchd label and the systemd unit, and a Task Scheduler `folder`. */
|
|
146
|
+
export type JobOwner = {
|
|
147
|
+
/** Lowercase labels of letters, digits and dashes, two or more, joined by dots (`org.example.backup`). */
|
|
148
|
+
readonly domain: string;
|
|
149
|
+
/** Letters, digits, dots, dashes and underscores, beginning and ending with a letter or digit (`Example`). */
|
|
150
|
+
readonly folder: string;
|
|
151
|
+
};
|
|
152
|
+
/** A job to schedule. */
|
|
153
|
+
export type JobSpec = {
|
|
154
|
+
/** Its name, unique under its owner. */
|
|
155
|
+
readonly name: JobName;
|
|
156
|
+
/** Its owner, which makes its label and where its files go. */
|
|
157
|
+
readonly owner: JobOwner;
|
|
158
|
+
/** The program and its arguments, run without a shell (by the scheduler, or by the `.cmd` file on Windows). */
|
|
159
|
+
readonly argv: readonly string[];
|
|
160
|
+
/** The absolute folder it runs in. */
|
|
161
|
+
readonly workdir: string;
|
|
162
|
+
/** Variables added to its environment. */
|
|
163
|
+
readonly env?: Readonly<Record<string, string>>;
|
|
164
|
+
/** When it runs. */
|
|
165
|
+
readonly when: Schedule;
|
|
166
|
+
/** An absolute file its output and errors are appended to (systemd's journal, and nothing on macOS and Windows, without it). */
|
|
167
|
+
readonly log?: string;
|
|
168
|
+
};
|
|
169
|
+
/** The computer a job is planned for: its scheduler, the user's home folder in its own form, and on macOS the user's numeric id (launchctl's `gui/<uid>` domain). */
|
|
170
|
+
export type Target = {
|
|
171
|
+
readonly os: SchedulerOs;
|
|
172
|
+
readonly home: string;
|
|
173
|
+
readonly uid?: number;
|
|
174
|
+
};
|
|
175
|
+
/** A file to write: its path relative to the home folder, parts joined by `/`; its text; and its mode where it matters (POSIX permission bits). */
|
|
176
|
+
export type PlannedFile = {
|
|
177
|
+
readonly path: string;
|
|
178
|
+
readonly content: string;
|
|
179
|
+
readonly mode?: number;
|
|
180
|
+
};
|
|
181
|
+
/** A command to run, by its argument vector and never through a shell; `mayFail` where a failure is expected and stops nothing (nothing to unload). */
|
|
182
|
+
export type Step = {
|
|
183
|
+
readonly argv: readonly string[];
|
|
184
|
+
readonly mayFail: boolean;
|
|
185
|
+
};
|
|
186
|
+
/** What scheduling a job takes: the files to write, then `install`; to remove it, `remove`, then the files removed, then `afterRemove`. */
|
|
187
|
+
export type JobPlan = {
|
|
188
|
+
/** The scheduler. */
|
|
189
|
+
readonly os: SchedulerOs;
|
|
190
|
+
/** The job's label: the systemd timer, the launchd label, or the task's name. */
|
|
191
|
+
readonly label: string;
|
|
192
|
+
/** When it runs, in words. */
|
|
193
|
+
readonly description: string;
|
|
194
|
+
/** The files to write before `install`, and to remove after `remove`. */
|
|
195
|
+
readonly files: readonly PlannedFile[];
|
|
196
|
+
/** The commands that load and enable the job. */
|
|
197
|
+
readonly install: readonly Step[];
|
|
198
|
+
/** The commands that disable and unload it, before its files are removed. */
|
|
199
|
+
readonly remove: readonly Step[];
|
|
200
|
+
/** The commands to run once its files are removed (systemd forgets the units). */
|
|
201
|
+
readonly afterRemove: readonly Step[];
|
|
202
|
+
};
|
|
203
|
+
/**
|
|
204
|
+
* What scheduling a job on a computer takes: the files (relative to the home folder) and the commands, built and checked, written and run
|
|
205
|
+
* by nothing here. A value that is not valid, or that a file cannot carry safely, is an error naming the field.
|
|
206
|
+
*/
|
|
207
|
+
export declare function planJob(job: JobSpec, target: Target): Result<JobPlan, ScheduleError>;
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Versions: semantic versions by the rules of semver.org 2.0.0 (parsed, printed, ordered and bumped), and the looser dotted versions that
|
|
3
|
+
* programs print (`2.9.8`, `1.4.4`, `26.13.1`), compared part by part (commons 0005-typescript-runtime FR-007); and npm's ranges, read and
|
|
4
|
+
* satisfied as node-semver reads them (FR-067). Taken from erga's kernel (`semver.ts`) and toolchain (`atLeast`), Stolos's
|
|
5
|
+
* `tools/version.ts` and the machine setup.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { atLeast, compareSemVer, parseSemVer } from "./semver.js";
|
|
10
|
+
* atLeast("2.10.0", "2.9.8"); // true
|
|
11
|
+
* const a = parseSemVer("1.0.0-rc.1"), b = parseSemVer("1.0.0");
|
|
12
|
+
* if (a.kind === "ok" && b.kind === "ok") compareSemVer(a.value, b.value); // negative: a pre-release comes first
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* @module
|
|
16
|
+
*/
|
|
17
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
18
|
+
/** A semantic version: major, minor and patch, and an optional pre-release and build, each as its dot-separated text. */
|
|
19
|
+
export type SemVer = {
|
|
20
|
+
readonly major: number;
|
|
21
|
+
readonly minor: number;
|
|
22
|
+
readonly patch: number;
|
|
23
|
+
readonly pre?: string;
|
|
24
|
+
readonly build?: string;
|
|
25
|
+
};
|
|
26
|
+
/** Text read as a semantic version (a leading `v` allowed, as tags carry it), or why it is not one. */
|
|
27
|
+
export declare function parseSemVer(text: string): Result<SemVer, string>;
|
|
28
|
+
/** A version as text: `1.2.3`, `1.2.3-rc.1` or `1.2.3-rc.1+build.5`. */
|
|
29
|
+
export declare function formatSemVer(v: SemVer): string;
|
|
30
|
+
/**
|
|
31
|
+
* Negative where `a` comes before `b`, positive where after, zero where they have the same precedence (semver.org 2.0.0 §11): numbers
|
|
32
|
+
* numerically, a pre-release before its release, pre-release identifiers one by one (numeric ones numerically and before the others), and
|
|
33
|
+
* the build ignored.
|
|
34
|
+
*/
|
|
35
|
+
export declare function compareSemVer(a: SemVer, b: SemVer): number;
|
|
36
|
+
/** Which part of a version a change raises. */
|
|
37
|
+
export type Level = "major" | "minor" | "patch";
|
|
38
|
+
/** The next version at a level: the parts after it reset to zero, and the pre-release and build dropped. */
|
|
39
|
+
export declare function bump(v: SemVer, level: Level): SemVer;
|
|
40
|
+
/** The change a surface made, and so the least its version must change by. */
|
|
41
|
+
export type Change = {
|
|
42
|
+
readonly kind: "none";
|
|
43
|
+
} | {
|
|
44
|
+
readonly kind: "fix";
|
|
45
|
+
} | {
|
|
46
|
+
readonly kind: "addition";
|
|
47
|
+
} | {
|
|
48
|
+
readonly kind: "breaking";
|
|
49
|
+
};
|
|
50
|
+
/** Whether moving from `before` to `after` is enough for `change`; before 1.0 a breaking change needs only the minor raised. */
|
|
51
|
+
export declare function bumpSuffices(before: SemVer, after: SemVer, change: Change): boolean;
|
|
52
|
+
/** The numbers of a dotted version: split at `.`, `+`, `_` and `-`, each part's leading digits, and 0 where a part has none. */
|
|
53
|
+
export declare function dottedParts(version: string): readonly number[];
|
|
54
|
+
/** Negative, zero or positive as dotted version `a` is below, equal to or above `b`, part by part; a missing part counts as 0. */
|
|
55
|
+
export declare function compareDotted(a: string, b: string): number;
|
|
56
|
+
/** Whether dotted version `have` is at least `want`. */
|
|
57
|
+
export declare function atLeast(have: string, want: string): boolean;
|
|
58
|
+
/** The first dotted version in a program's output (`bun 1.4.4 (...)` gives `1.4.4`), or undefined. */
|
|
59
|
+
export declare function versionIn(text: string): string | undefined;
|
|
60
|
+
/** How a comparator compares a version with its bound. */
|
|
61
|
+
export type Operator = "<" | "<=" | ">" | ">=" | "=";
|
|
62
|
+
/** A version compared with one bound: `>=1.2.3`, `<2.0.0-0`. */
|
|
63
|
+
export type Comparator = {
|
|
64
|
+
readonly op: Operator;
|
|
65
|
+
readonly version: SemVer;
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* A range: sets of comparators joined by `||`. A version satisfies it where it satisfies every comparator of one set; an empty set holds
|
|
69
|
+
* every version (`*`), and no set at all holds none.
|
|
70
|
+
*/
|
|
71
|
+
export type Range = {
|
|
72
|
+
readonly kind: "range";
|
|
73
|
+
readonly sets: readonly (readonly Comparator[])[];
|
|
74
|
+
};
|
|
75
|
+
/**
|
|
76
|
+
* Text read as an npm range (FR-067), by node-semver's grammar and its desugaring: comparators (`<`, `<=`, `>`, `>=`, `=`) joined by
|
|
77
|
+
* spaces, sets joined by `||`, hyphen ranges (`1.2.3 - 2.3.4`), x-ranges (`*`, `x`, `X` or a missing part), tilde (`~`, `~>`) and caret
|
|
78
|
+
* (`^`) ranges, a space allowed after an operator, a leading `v` and builds ignored. Anything else is an error naming the part.
|
|
79
|
+
*/
|
|
80
|
+
export declare function parseRange(text: string): Result<Range, string>;
|
|
81
|
+
/** A range as text: each set's comparators joined by spaces (`=` written as the bare version, an empty set as `*`), the sets by ` || `. */
|
|
82
|
+
export declare function formatRange(range: Range): string;
|
|
83
|
+
/** Whether pre-releases are held to the comparators alone (`includePrerelease`), rather than only where a bound names their release. */
|
|
84
|
+
export type SatisfiesOptions = {
|
|
85
|
+
readonly includePrerelease?: boolean;
|
|
86
|
+
};
|
|
87
|
+
/**
|
|
88
|
+
* Whether a version satisfies a range (FR-067): every comparator of one of its sets holds. A pre-release version satisfies a set only where
|
|
89
|
+
* one of its comparators is a pre-release of the same major, minor and patch (`1.2.3-beta.4` satisfies `^1.2.3-beta.2`, `1.2.4-beta`
|
|
90
|
+
* does not satisfy `^1.2.3`), as node-semver has it, unless `includePrerelease` is given, when the comparators alone decide.
|
|
91
|
+
*/
|
|
92
|
+
export declare function satisfies(version: SemVer, range: Range, options?: SatisfiesOptions): boolean;
|
|
93
|
+
/** The highest of the versions that satisfy the range, or undefined where none does. */
|
|
94
|
+
export declare function maxSatisfying(versions: readonly SemVer[], range: Range, options?: SatisfiesOptions): SemVer | undefined;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SHA-256 through Web Crypto (`crypto.subtle`, in every runtime and browser), and a typed `Sha256`: 64 lower-case hexadecimal digits that
|
|
3
|
+
* the compiler keeps apart from any other string, so a checksum is never confused with a version or a path (commons 0005-typescript-runtime
|
|
4
|
+
* FR-008). Taken from the machine setup's `result.ts` and `net.ts`, and the many call sites that write the hex loop by hand.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { sha256, sha256Of } from "./sha256.js";
|
|
9
|
+
* const sum = await sha256(new TextEncoder().encode("abc"));
|
|
10
|
+
* sum === sha256Of("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"); // true
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import type { Brand } from "@intellectual-frontiers/core";
|
|
16
|
+
/** 64 lower-case hexadecimal digits: a SHA-256 checksum. */
|
|
17
|
+
export type Sha256 = Brand<string, "Sha256">;
|
|
18
|
+
/** The text as a checksum where it is one (upper-case digits are lowered), else undefined. */
|
|
19
|
+
export declare function sha256Of(text: string): Sha256 | undefined;
|
|
20
|
+
/** Bytes as lower-case hexadecimal, two digits each. */
|
|
21
|
+
export declare function toHex(bytes: Uint8Array): string;
|
|
22
|
+
/** Hexadecimal text as bytes, or undefined where it is not an even number of hexadecimal digits. */
|
|
23
|
+
export declare function fromHex(text: string): Uint8Array | undefined;
|
|
24
|
+
/** The SHA-256 of bytes, or of text as UTF-8. */
|
|
25
|
+
export declare function sha256(data: Uint8Array | string): Promise<Sha256>;
|
|
26
|
+
/** Whether two checksums are the same, compared in constant time for their length. */
|
|
27
|
+
export declare function sameSha256(a: Sha256, b: Sha256): boolean;
|
|
28
|
+
/** The lines of a `sha256sum` or `SHASUMS256.txt` file, as file name to checksum; lines that are not a checksum and a name are skipped. */
|
|
29
|
+
export declare function parseSha256Sums(text: string): ReadonlyMap<string, Sha256>;
|