@intellectual-frontiers/system 0.0.0-stage → 0.1.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.
@@ -0,0 +1,173 @@
1
+ // Spec: 0001-system FR-017
2
+ /**
3
+ * The operating system's own scheduled job, installed and removed (commons 0005-typescript-runtime FR-046): `installJob` plans the job
4
+ * with the kernel's `planJob`, writes its files under the home folder (making their folders, with their modes) and runs the commands that
5
+ * load it; `removeJob` runs the commands that unload it, removes its files and runs what follows (systemd's `daemon-reload`). Each file and
6
+ * each command is reported as an outcome, and the first failure that matters is a typed error carrying the outcomes until then; a
7
+ * command marked `mayFail` (nothing to unload) never stops the rest. The scheduler, the home folder, the user's id and the program that
8
+ * runs a command are parameters, defaulting to this computer's (`build.os`, `homeDir()`, `uid()`, `run`), so a test plans and installs any
9
+ * scheduler's job in a temporary folder with a fake runner, and no real systemctl, launchctl or schtasks runs. Taken from Stolos's
10
+ * `src/archon/export/schedule.ts` (`installJob`, `uninstallJob`), which took its file and command functions as dependencies and threw;
11
+ * here the files go through `./fs.ts`, the commands through `./proc.ts` or a given runner, and errors are values.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * import { jobName, schedule } from "./job-plan.ts";
16
+ * import { installJob } from "./schedule.ts";
17
+ * const name = jobName("backup");
18
+ * const when = schedule({ kind: "weekly", day: "sun", hour: 3, minute: 30 });
19
+ * if (name.kind === "ok" && when.kind === "ok") {
20
+ * const r = await installJob({ name: name.value, owner: { domain: "org.example", folder: "Example" }, argv: ["/usr/bin/backup"], workdir: "/srv", when: when.value });
21
+ * if (r.kind === "err") console.error(r.error.kind);
22
+ * }
23
+ * ```
24
+ *
25
+ * @module
26
+ */
27
+ import { absurd, err, ok, type Result } from "@intellectual-frontiers/core";
28
+ import { type JobPlan, type JobSpec, planJob, type ScheduleError, type SchedulerOs, type Step } from "./job-plan.ts";
29
+ import { NotFound } from "./errors.ts";
30
+ import { mkdir, remove, writeTextFile } from "./fs.ts";
31
+ import { dirname, join } from "./path.ts";
32
+ import { build, homeDir, run, uid } from "./proc.ts";
33
+
34
+ /** What a command did: its exit status (127 where it could not be started) and what it said (standard error, else standard output, trimmed). */
35
+ export type StepResult = { readonly code: number; readonly output: string };
36
+
37
+ /** Runs one command by its argument vector; the default runs it with `./proc.ts`, a test gives a fake. Never rejects for a failure of the command. */
38
+ export type StepRunner = (argv: readonly string[]) => Promise<StepResult>;
39
+
40
+ /** The default runner: the program run with `run`, never through a shell; one that cannot be started gives status 127 and the reason. */
41
+ export const runStep: StepRunner = async (argv) => {
42
+ try {
43
+ const r = await run(argv);
44
+ return { code: r.code, output: r.stderr.trim() === "" ? r.stdout.trim() : r.stderr.trim() };
45
+ } catch (e) {
46
+ return { code: 127, output: e instanceof Error ? e.message : String(e) };
47
+ }
48
+ };
49
+
50
+ /** Where and how to install or remove a job; every field defaults to this computer. */
51
+ export type JobOptions = {
52
+ /** The scheduler (`build.os` by default). */
53
+ readonly os?: SchedulerOs;
54
+ /** The user's home folder, under which the files go (`homeDir()` by default). */
55
+ readonly home?: string;
56
+ /** The user's numeric id, for launchctl's `gui/<uid>` domain (`uid()` by default). */
57
+ readonly uid?: number;
58
+ /** What runs each command (`runStep` by default). */
59
+ readonly runner?: StepRunner;
60
+ };
61
+
62
+ /** One thing done: a file written or removed (its absolute path, and whether it was there), or a command run (its status and output). */
63
+ export type Outcome =
64
+ | { readonly kind: "wrote"; readonly path: string }
65
+ | { readonly kind: "removed"; readonly path: string; readonly existed: boolean }
66
+ | { readonly kind: "ran"; readonly argv: readonly string[]; readonly code: number; readonly output: string; readonly mayFail: boolean };
67
+
68
+ /** A job installed or removed: its plan and what was done, in order. */
69
+ export type JobReport = { readonly plan: JobPlan; readonly outcomes: readonly Outcome[] };
70
+
71
+ /** Why installing or removing stopped, with what was done until then. */
72
+ export type JobError =
73
+ | { readonly kind: "unsupported"; readonly os: string; readonly outcomes: readonly Outcome[] }
74
+ | { readonly kind: "plan"; readonly error: ScheduleError; readonly outcomes: readonly Outcome[] }
75
+ | { readonly kind: "write"; readonly path: string; readonly message: string; readonly outcomes: readonly Outcome[] }
76
+ | { readonly kind: "remove"; readonly path: string; readonly message: string; readonly outcomes: readonly Outcome[] }
77
+ | {
78
+ readonly kind: "step";
79
+ readonly argv: readonly string[];
80
+ readonly code: number;
81
+ readonly output: string;
82
+ readonly outcomes: readonly Outcome[];
83
+ };
84
+
85
+ /** A job error as one line. */
86
+ export function formatJobError(e: JobError): string {
87
+ switch (e.kind) {
88
+ case "unsupported":
89
+ return `this OS (${e.os}) has no scheduler this module knows: Linux, macOS or Windows`;
90
+ case "plan":
91
+ return `${e.error.field}: ${e.error.message}`;
92
+ case "write":
93
+ return `could not write ${e.path}: ${e.message}`;
94
+ case "remove":
95
+ return `could not remove ${e.path}: ${e.message}`;
96
+ case "step":
97
+ return `${e.argv.join(" ")} failed (${e.code})${e.output === "" ? "" : `: ${e.output}`}`;
98
+ default:
99
+ return absurd(e);
100
+ }
101
+ }
102
+
103
+ const SCHEDULERS: readonly string[] = ["linux", "darwin", "windows"];
104
+ const isScheduler = (os: string): os is SchedulerOs => SCHEDULERS.includes(os);
105
+
106
+ type Prepared = { readonly plan: JobPlan; readonly home: string; readonly runner: StepRunner };
107
+
108
+ function prepare(job: JobSpec, options: JobOptions): Result<Prepared, JobError> {
109
+ const os = options.os ?? build.os;
110
+ if (!isScheduler(os)) return err({ kind: "unsupported", os, outcomes: [] });
111
+ const home = options.home ?? homeDir();
112
+ const id = options.uid ?? uid();
113
+ const plan = planJob(job, { os, home, ...(id === undefined ? {} : { uid: id }) });
114
+ if (plan.kind === "err") return err({ kind: "plan", error: plan.error, outcomes: [] });
115
+ return ok({ plan: plan.value, home, runner: options.runner ?? runStep });
116
+ }
117
+
118
+ const message = (e: unknown): string => (e instanceof Error ? e.message : String(e));
119
+
120
+ /** The commands run in turn, each an outcome; the first that fails and may not is the error. */
121
+ async function runSteps(steps: readonly Step[], runner: StepRunner, outcomes: Outcome[]): Promise<Result<void, JobError>> {
122
+ for (const s of steps) {
123
+ const r = await runner(s.argv);
124
+ outcomes.push({ kind: "ran", argv: s.argv, code: r.code, output: r.output, mayFail: s.mayFail });
125
+ if (r.code !== 0 && !s.mayFail) return err({ kind: "step", argv: s.argv, code: r.code, output: r.output, outcomes: [...outcomes] });
126
+ }
127
+ return ok(undefined);
128
+ }
129
+
130
+ /** A planned file's absolute path on this computer: the home folder and the parts of its relative path. */
131
+ const hostPath = (home: string, rel: string): string => join(home, ...rel.split("/"));
132
+
133
+ /** A job scheduled: planned, its files written (their folders made, their modes set), then the commands that load it run. */
134
+ export async function installJob(job: JobSpec, options: JobOptions = {}): Promise<Result<JobReport, JobError>> {
135
+ const p = prepare(job, options);
136
+ if (p.kind === "err") return p;
137
+ const { plan, home, runner } = p.value;
138
+ const outcomes: Outcome[] = [];
139
+ for (const f of plan.files) {
140
+ const path = hostPath(home, f.path);
141
+ try {
142
+ await mkdir(dirname(path), { recursive: true });
143
+ await writeTextFile(path, f.content, f.mode === undefined ? {} : { mode: f.mode });
144
+ } catch (e) {
145
+ return err({ kind: "write", path, message: message(e), outcomes });
146
+ }
147
+ outcomes.push({ kind: "wrote", path });
148
+ }
149
+ const steps = await runSteps(plan.install, runner, outcomes);
150
+ return steps.kind === "err" ? steps : ok({ plan, outcomes });
151
+ }
152
+
153
+ /** A job unscheduled: the commands that unload it run, its files removed (one already gone is no error), then what follows run. */
154
+ export async function removeJob(job: JobSpec, options: JobOptions = {}): Promise<Result<JobReport, JobError>> {
155
+ const p = prepare(job, options);
156
+ if (p.kind === "err") return p;
157
+ const { plan, home, runner } = p.value;
158
+ const outcomes: Outcome[] = [];
159
+ const before = await runSteps(plan.remove, runner, outcomes);
160
+ if (before.kind === "err") return before;
161
+ for (const f of plan.files) {
162
+ const path = hostPath(home, f.path);
163
+ try {
164
+ await remove(path);
165
+ outcomes.push({ kind: "removed", path, existed: true });
166
+ } catch (e) {
167
+ if (!(e instanceof NotFound)) return err({ kind: "remove", path, message: message(e), outcomes });
168
+ outcomes.push({ kind: "removed", path, existed: false });
169
+ }
170
+ }
171
+ const after = await runSteps(plan.afterRemove, runner, outcomes);
172
+ return after.kind === "err" ? after : ok({ plan, outcomes });
173
+ }
package/src/stdio.ts ADDED
@@ -0,0 +1,204 @@
1
+ // Spec: 0001-system FR-019
2
+ /**
3
+ * Standard input, output and error for what a program reads (commons 0005-typescript-runtime FR-054): JSON, a protocol on standard input
4
+ * and output, bytes passed along a pipe. The names are plain (`read`, `readable`, `write`,
5
+ * `writeSync`, `writable`). This file and `runtime/console.ts` are the only files of the runtime that write to
6
+ * standard output or standard error: what a person reads goes through the console (0006-signals FR-026), what a program reads through here.
7
+ *
8
+ * Writes: `write` waits until the bytes are handed to the system and gives their length; `writeSync` writes them all to the file
9
+ * descriptor before it returns (retrying while a non-blocking pipe is full), so it suits the last words of a process that is about to
10
+ * exit. Both write the whole of what they are given. A closed pipe (`EPIPE`) rejects `write` and throws from `writeSync` as the runtime's
11
+ * error; it never ends the process as an uncaught error.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * import { stdin, stdout } from "./stdio.ts";
16
+ * const request = JSON.parse(await stdin.text());
17
+ * await stdout.write(`${JSON.stringify({ ok: true, request })}\n`);
18
+ * ```
19
+ *
20
+ * @module
21
+ */
22
+ import { writeSync as fdWriteSync } from "node:fs";
23
+ import process from "node:process";
24
+ import { Readable, type Writable } from "node:stream";
25
+ import { mapError } from "./errors.ts";
26
+
27
+ // ---------------------------------------------------------------------------------------------------------------------------------
28
+ // Standard input
29
+ // ---------------------------------------------------------------------------------------------------------------------------------
30
+
31
+ /** Standard input. */
32
+ export type Stdin = {
33
+ /** The whole of standard input as a web stream; made once, on first use. Bytes `read` took but did not give come first. */
34
+ readonly readable: ReadableStream<Uint8Array>;
35
+ /** Reads into `buffer` and gives how many bytes it read, or null at the end of the input. */
36
+ read(buffer: Uint8Array): Promise<number | null>;
37
+ /** The rest of standard input, to its end, as bytes. */
38
+ bytes(): Promise<Uint8Array>;
39
+ /** The rest of standard input, to its end, as text (UTF-8). */
40
+ text(): Promise<string>;
41
+ };
42
+
43
+ /** Byte arrays joined into one. */
44
+ function joined(parts: readonly Uint8Array[]): Uint8Array {
45
+ const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
46
+ let at = 0;
47
+ for (const p of parts) {
48
+ out.set(p, at);
49
+ at += p.length;
50
+ }
51
+ return out;
52
+ }
53
+
54
+ /**
55
+ * Standard input over a source stream, made on first use: `read` keeps what did not fit in its buffer for the next `read`, and `readable`
56
+ * gives that first. Exported so a test can drive it with a stream of its own.
57
+ */
58
+ export function stdinOf(source: () => ReadableStream<Uint8Array>): Stdin {
59
+ let base: ReadableStream<Uint8Array> | undefined;
60
+ let whole: ReadableStream<Uint8Array> | undefined;
61
+ let left: Uint8Array = new Uint8Array(0);
62
+ const opened = (): ReadableStream<Uint8Array> => (base ??= source());
63
+ const read = async (buffer: Uint8Array): Promise<number | null> => {
64
+ if (buffer.length === 0) return 0;
65
+ if (left.length === 0) {
66
+ const reader = opened().getReader();
67
+ try {
68
+ const r = await reader.read();
69
+ if (r.done) return null;
70
+ left = r.value;
71
+ } finally {
72
+ reader.releaseLock();
73
+ }
74
+ }
75
+ const n = Math.min(buffer.length, left.length);
76
+ buffer.set(left.subarray(0, n));
77
+ left = left.subarray(n);
78
+ return n;
79
+ };
80
+ const readable = (): ReadableStream<Uint8Array> => {
81
+ if (whole !== undefined) return whole;
82
+ const reader = opened().getReader();
83
+ whole = new ReadableStream<Uint8Array>({
84
+ pull: async (controller): Promise<void> => {
85
+ if (left.length > 0) {
86
+ controller.enqueue(left);
87
+ left = new Uint8Array(0);
88
+ return;
89
+ }
90
+ const r = await reader.read();
91
+ if (r.done) controller.close();
92
+ else controller.enqueue(r.value);
93
+ },
94
+ cancel: async (reason: unknown): Promise<void> => reader.cancel(reason),
95
+ });
96
+ return whole;
97
+ };
98
+ const bytes = async (): Promise<Uint8Array> => {
99
+ const parts: Uint8Array[] = [];
100
+ const reader = readable().getReader();
101
+ try {
102
+ for (;;) {
103
+ const r = await reader.read();
104
+ if (r.done) break;
105
+ parts.push(r.value);
106
+ }
107
+ } finally {
108
+ reader.releaseLock();
109
+ }
110
+ return joined(parts);
111
+ };
112
+ return {
113
+ get readable(): ReadableStream<Uint8Array> {
114
+ return readable();
115
+ },
116
+ read,
117
+ bytes,
118
+ text: async (): Promise<string> => new TextDecoder().decode(await bytes()),
119
+ };
120
+ }
121
+
122
+ /** This process's standard input. */
123
+ export const stdin: Stdin = stdinOf(
124
+ // Node's stream becomes a web stream; its type is `node:stream/web`'s, which is the same class as the global one.
125
+ () => Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>,
126
+ );
127
+
128
+ // ---------------------------------------------------------------------------------------------------------------------------------
129
+ // Standard output and standard error
130
+ // ---------------------------------------------------------------------------------------------------------------------------------
131
+
132
+ /** Standard output or standard error, for output a program reads. */
133
+ export type Stdout = {
134
+ /** Writes bytes, or text as UTF-8, and gives how many bytes were written, once they are handed to the system. */
135
+ write(data: Uint8Array | string): Promise<number>;
136
+ /** Writes bytes, or text as UTF-8, all of them, before it returns; gives how many bytes were written. */
137
+ writeSync(data: Uint8Array | string): number;
138
+ /** A web stream onto it; closing the stream leaves the file descriptor open, as other writers may still use it. */
139
+ readonly writable: WritableStream<Uint8Array>;
140
+ };
141
+
142
+ const encoder = new TextEncoder();
143
+ const bytesOf = (data: Uint8Array | string): Uint8Array => (typeof data === "string" ? encoder.encode(data) : data);
144
+
145
+ /** Waits about a millisecond without giving way to the event loop, while a non-blocking pipe is full. */
146
+ function pause(): void {
147
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
148
+ }
149
+
150
+ /** Where a writer writes: a file descriptor for `writeSync`, a Node stream for `write`. */
151
+ type Sink = {
152
+ readonly fd: number;
153
+ readonly stream: () => Writable;
154
+ };
155
+
156
+ function stdoutOf(sink: Sink): Stdout {
157
+ let guarded = false;
158
+ const stream = (): Writable => {
159
+ const s = sink.stream();
160
+ if (!guarded) {
161
+ guarded = true;
162
+ // A closed pipe is reported to the writer that wrote, not as an uncaught error that ends the process.
163
+ s.on("error", () => undefined);
164
+ }
165
+ return s;
166
+ };
167
+ const write = (data: Uint8Array | string): Promise<number> => {
168
+ const bytes = bytesOf(data);
169
+ return new Promise<number>((resolve, reject) => {
170
+ stream().write(bytes, (e?: Error | null) => (e === undefined || e === null ? resolve(bytes.length) : reject(mapError(e))));
171
+ });
172
+ };
173
+ const writeSync = (data: Uint8Array | string): number => {
174
+ const bytes = bytesOf(data);
175
+ let at = 0;
176
+ while (at < bytes.length) {
177
+ try {
178
+ at += fdWriteSync(sink.fd, bytes, at, bytes.length - at);
179
+ } catch (e) {
180
+ if (typeof e === "object" && e !== null && "code" in e && e.code === "EAGAIN") pause();
181
+ else throw mapError(e);
182
+ }
183
+ }
184
+ return bytes.length;
185
+ };
186
+ let writable: WritableStream<Uint8Array> | undefined;
187
+ return {
188
+ write,
189
+ writeSync,
190
+ get writable(): WritableStream<Uint8Array> {
191
+ return (writable ??= new WritableStream<Uint8Array>({
192
+ write: async (chunk): Promise<void> => {
193
+ await write(chunk);
194
+ },
195
+ }));
196
+ },
197
+ };
198
+ }
199
+
200
+ /** This process's standard output, for what a program reads. */
201
+ export const stdout: Stdout = stdoutOf({ fd: 1, stream: () => process.stdout });
202
+
203
+ /** This process's standard error, for what a program reads (a person's messages go through `runtime/console.ts`). */
204
+ export const stderr: Stdout = stdoutOf({ fd: 2, stream: () => process.stderr });
package/src/tty.ts ADDED
@@ -0,0 +1,94 @@
1
+ // Spec: 0001-system FR-018
2
+ /**
3
+ * The terminal (commons 0005-typescript-runtime FR-023): whether a stream is one, its size, raw mode, and the choice of colour and emoji the
4
+ * three `ui` modules each made (Stolos's `core/ui.ts`, the setup's `ui.ts`, erga's console). The choice is a pure function of the
5
+ * environment and the facts about the terminal (`lookOf`), so it is tested without one; `currentLook` reads them from the host.
6
+ *
7
+ * Rules: colour only where `NO_COLOR` is unset or empty, and only at a terminal unless `FORCE_COLOR` is set; a terminal whose `TERM` is
8
+ * `dumb` counts as none; emoji where the locale is UTF-8, or on Windows in a terminal that says so (`WT_SESSION`, `TERM_PROGRAM`,
9
+ * `ConEmuANSI=ON`), or on a Mac with `TERM_PROGRAM`.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import { lookOf } from "./tty.ts";
14
+ * lookOf({ env: { LANG: "en_US.UTF-8" }, terminal: true, os: "linux", columns: 120 });
15
+ * // { tty: true, colour: true, emoji: true, columns: 120 }
16
+ * ```
17
+ *
18
+ * @module
19
+ */
20
+ import { isatty } from "node:tty";
21
+ import process from "node:process";
22
+ import { NotSupported } from "./errors.ts";
23
+ import { build, env, type Os } from "./proc.ts";
24
+
25
+ /** A standard stream of the process. */
26
+ export type StdStream = "stdin" | "stdout" | "stderr";
27
+
28
+ const FD: Readonly<Record<StdStream, number>> = { stdin: 0, stdout: 1, stderr: 2 };
29
+
30
+ /** Whether a standard stream is a terminal. */
31
+ export function isTerminal(stream: StdStream): boolean {
32
+ try {
33
+ return isatty(FD[stream]);
34
+ } catch {
35
+ return false;
36
+ }
37
+ }
38
+
39
+ /** The size of the terminal on standard output or, failing that, standard error; undefined where neither is one. */
40
+ export function consoleSize(): { readonly columns: number; readonly rows: number } | undefined {
41
+ for (const s of [process.stdout, process.stderr]) {
42
+ if (s.isTTY === true && typeof s.columns === "number" && typeof s.rows === "number") return { columns: s.columns, rows: s.rows };
43
+ }
44
+ return undefined;
45
+ }
46
+
47
+ /** Raw mode on standard input turned on (every key as it is pressed, no echo) or off; `NotSupported` where standard input is not a terminal. */
48
+ export function setRaw(on: boolean): void {
49
+ const stdin = process.stdin;
50
+ if (stdin.isTTY !== true || typeof stdin.setRawMode !== "function") throw new NotSupported("standard input is not a terminal", "ENOTTY");
51
+ stdin.setRawMode(on);
52
+ }
53
+
54
+ /** How output should look. */
55
+ export type Look = { readonly tty: boolean; readonly colour: boolean; readonly emoji: boolean; readonly columns: number };
56
+
57
+ /** What the choice of a look depends on. */
58
+ export type LookFacts = {
59
+ /** The environment's variables. */
60
+ readonly env: Readonly<Record<string, string | undefined>>;
61
+ /** Whether the stream written to is a terminal. */
62
+ readonly terminal: boolean;
63
+ /** The operating system. */
64
+ readonly os: Os;
65
+ /** The terminal's width, where known. */
66
+ readonly columns?: number;
67
+ };
68
+
69
+ const set = (v: string | undefined): boolean => v !== undefined && v !== "";
70
+
71
+ /** The look the facts call for: see the module's rules. The width is the terminal's where it is at least 40, else 80. */
72
+ export function lookOf(facts: LookFacts): Look {
73
+ const e = facts.env;
74
+ const tty = facts.terminal && (e["TERM"] ?? "") !== "dumb";
75
+ const colour = !set(e["NO_COLOR"]) && (tty || set(e["FORCE_COLOR"]));
76
+ const utf8 = /utf-?8/i.test(e["LC_ALL"] || e["LC_CTYPE"] || e["LANG"] || "");
77
+ const emoji =
78
+ utf8 ||
79
+ (facts.os === "windows" && (set(e["WT_SESSION"]) || set(e["TERM_PROGRAM"]) || e["ConEmuANSI"] === "ON")) ||
80
+ (facts.os === "darwin" && set(e["TERM_PROGRAM"]));
81
+ const columns = tty && facts.columns !== undefined && facts.columns >= 40 ? facts.columns : 80;
82
+ return { tty, colour, emoji, columns };
83
+ }
84
+
85
+ /** The look for writing to a standard stream (standard error by default) of this process. */
86
+ export function currentLook(stream: StdStream = "stderr"): Look {
87
+ const size = consoleSize();
88
+ return lookOf({
89
+ env: env.toObject(),
90
+ terminal: isTerminal(stream),
91
+ os: build.os,
92
+ ...(size === undefined ? {} : { columns: size.columns }),
93
+ });
94
+ }