@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.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/compile.d.ts +94 -0
- package/dist/compile.js +130 -0
- package/dist/dirs.d.ts +19 -0
- package/dist/dirs.js +64 -0
- package/dist/discover.d.ts +43 -0
- package/dist/discover.js +118 -0
- package/dist/errors.d.ts +130 -0
- package/dist/errors.js +189 -0
- package/dist/fs.d.ts +263 -0
- package/dist/fs.js +826 -0
- package/dist/git.d.ts +63 -0
- package/dist/git.js +144 -0
- package/dist/job-plan.d.ts +207 -0
- package/dist/job-plan.js +563 -0
- package/dist/lock.d.ts +41 -0
- package/dist/lock.js +130 -0
- package/dist/mod.d.ts +28 -0
- package/dist/mod.js +29 -0
- package/dist/path.d.ts +47 -0
- package/dist/path.js +55 -0
- package/dist/proc.d.ts +257 -0
- package/dist/proc.js +589 -0
- package/dist/schedule.d.ts +99 -0
- package/dist/schedule.js +131 -0
- package/dist/stdio.d.ts +31 -0
- package/dist/stdio.js +170 -0
- package/dist/tty.d.ts +34 -0
- package/dist/tty.js +71 -0
- package/dist/watch.d.ts +42 -0
- package/dist/watch.js +342 -0
- package/package.json +113 -4
- package/src/compile.ts +178 -0
- package/src/dirs.ts +87 -0
- package/src/discover.ts +144 -0
- package/src/errors.ts +176 -0
- package/src/fs.ts +967 -0
- package/src/git.ts +163 -0
- package/src/job-plan.ts +660 -0
- package/src/lock.ts +149 -0
- package/src/mod.ts +29 -0
- package/src/path.ts +59 -0
- package/src/proc.ts +786 -0
- package/src/schedule.ts +173 -0
- package/src/stdio.ts +204 -0
- package/src/tty.ts +94 -0
- package/src/watch.ts +338 -0
package/src/lock.ts
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
// Spec: 0001-system FR-015
|
|
2
|
+
/**
|
|
3
|
+
* One run at a time (commons 0005-typescript-runtime FR-039): a lock file made only where none exists (`O_EXCL`, which every file system
|
|
4
|
+
* and operating system gives atomically, where `flock` has no `node:` form), holding who holds it (process id, command, since when). A
|
|
5
|
+
* waiting run polls until it is free, says once who it waits for, and takes over a lock whose holder's process no longer runs. A child of
|
|
6
|
+
* a holder can inherit the lock through an environment variable instead of waiting for its own parent. Taken from Stolos's
|
|
7
|
+
* `src/archon/core/lock.ts`, which locked through the runtime's own file lock.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* import { acquireLock } from "./lock.ts";
|
|
12
|
+
* const held = await acquireLock("/run/app.lock", { wait: true, command: "update", onWait: (h) => console.log(`waiting for ${h?.command}`) });
|
|
13
|
+
* try {
|
|
14
|
+
* // the work
|
|
15
|
+
* } finally {
|
|
16
|
+
* held?.release();
|
|
17
|
+
* }
|
|
18
|
+
* ```
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
import * as nfs from "node:fs";
|
|
23
|
+
import process from "node:process";
|
|
24
|
+
import { type Decoder, integer, json, object, string } from "@intellectual-frontiers/core";
|
|
25
|
+
import { AlreadyExists, mapError, NotFound } from "./errors.ts";
|
|
26
|
+
import { readTextFile, remove, writeTextFile } from "./fs.ts";
|
|
27
|
+
import { sleep } from "./proc.ts";
|
|
28
|
+
|
|
29
|
+
/** Who holds a lock. */
|
|
30
|
+
export type Holder = { readonly pid: number; readonly command: string; readonly since: string; readonly token: string };
|
|
31
|
+
|
|
32
|
+
const holderDecoder: Decoder<Holder> = object({ pid: integer, command: string, since: string, token: string });
|
|
33
|
+
|
|
34
|
+
/** How to take a lock. */
|
|
35
|
+
export type LockOptions = {
|
|
36
|
+
/** Wait until it is free (polling), or give up at once. */
|
|
37
|
+
readonly wait: boolean;
|
|
38
|
+
/** What the holder runs, said to whoever waits. */
|
|
39
|
+
readonly command?: string;
|
|
40
|
+
/** Called once, with the holder where it can be read, when the lock is not free. */
|
|
41
|
+
readonly onWait?: (holder: Holder | undefined) => void;
|
|
42
|
+
/** How often a waiting run looks again (250 ms by default). */
|
|
43
|
+
readonly pollMs?: number;
|
|
44
|
+
/** The variable that says a parent already holds the lock (no variable by default); it is set while the lock is held. */
|
|
45
|
+
readonly inheritEnv?: string;
|
|
46
|
+
/** How long a waiting run waits before it gives up and returns nothing (no limit by default). */
|
|
47
|
+
readonly timeoutMs?: number;
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
/** A lock taken. */
|
|
51
|
+
export type Held = {
|
|
52
|
+
/** Who holds it: this process. */
|
|
53
|
+
readonly holder: Holder;
|
|
54
|
+
/** The lock given back (the file removed where it is still this holder's); safe to call twice. */
|
|
55
|
+
release(): void;
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
/** Whether a process runs: a signal of 0 checks without sending one. A process of another account counts as running. */
|
|
59
|
+
export function processRuns(pid: number): boolean {
|
|
60
|
+
try {
|
|
61
|
+
process.kill(pid, 0);
|
|
62
|
+
return true;
|
|
63
|
+
} catch (e) {
|
|
64
|
+
return e instanceof Error && "code" in e && e.code === "EPERM";
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Who holds the lock at `path`, where its file can be read; whether that process still runs is not checked here. */
|
|
69
|
+
export async function readHolder(path: string): Promise<Holder | undefined> {
|
|
70
|
+
try {
|
|
71
|
+
const r = json(await readTextFile(path), holderDecoder);
|
|
72
|
+
return r.kind === "ok" ? r.value : undefined;
|
|
73
|
+
} catch {
|
|
74
|
+
return undefined;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** A holder as a person reads it: `update (pid 4242, for 3m 12s)`. */
|
|
79
|
+
export function describeHolder(h: Holder, now: number = Date.now()): string {
|
|
80
|
+
const secs = Math.max(0, Math.round((now - Date.parse(h.since)) / 1000));
|
|
81
|
+
const age = secs >= 60 ? `${Math.floor(secs / 60)}m ${secs % 60}s` : `${secs}s`;
|
|
82
|
+
return `${h.command} (pid ${h.pid}, for ${age})`;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The lock at `path` taken, or undefined where it is held by a running process and `wait` is false (or `timeoutMs` passed). A lock whose
|
|
87
|
+
* holder no longer runs, or whose file cannot be read, is taken over. Where `inheritEnv` is set in the environment, a parent holds it,
|
|
88
|
+
* and it is given at once (its release does nothing).
|
|
89
|
+
*/
|
|
90
|
+
export async function acquireLock(path: string, options: LockOptions): Promise<Held | undefined> {
|
|
91
|
+
const holder: Holder = {
|
|
92
|
+
pid: process.pid,
|
|
93
|
+
command:
|
|
94
|
+
options.command ??
|
|
95
|
+
(process.argv
|
|
96
|
+
.slice(2)
|
|
97
|
+
.filter((a) => !a.startsWith("-"))
|
|
98
|
+
.slice(0, 3)
|
|
99
|
+
.join(" ") ||
|
|
100
|
+
"a run"),
|
|
101
|
+
since: new Date().toISOString(),
|
|
102
|
+
token: crypto.randomUUID(),
|
|
103
|
+
};
|
|
104
|
+
const inherit = options.inheritEnv;
|
|
105
|
+
if (inherit !== undefined && process.env[inherit] === "1") return { holder, release: () => {} };
|
|
106
|
+
const started = Date.now();
|
|
107
|
+
let told = false;
|
|
108
|
+
for (;;) {
|
|
109
|
+
try {
|
|
110
|
+
await writeTextFile(path, `${JSON.stringify(holder)}\n`, { createNew: true, mode: 0o644 });
|
|
111
|
+
break;
|
|
112
|
+
} catch (e) {
|
|
113
|
+
if (!(e instanceof AlreadyExists)) throw e;
|
|
114
|
+
}
|
|
115
|
+
const current = await readHolder(path);
|
|
116
|
+
if (current === undefined || !processRuns(current.pid)) {
|
|
117
|
+
const again = await readHolder(path);
|
|
118
|
+
if (again?.token === current?.token)
|
|
119
|
+
await remove(path).catch((e: unknown) => {
|
|
120
|
+
if (!(e instanceof NotFound)) throw e;
|
|
121
|
+
});
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
if (!options.wait) return undefined;
|
|
125
|
+
if (options.timeoutMs !== undefined && Date.now() - started >= options.timeoutMs) return undefined;
|
|
126
|
+
if (!told) {
|
|
127
|
+
options.onWait?.(current);
|
|
128
|
+
told = true;
|
|
129
|
+
}
|
|
130
|
+
await sleep(options.pollMs ?? 250);
|
|
131
|
+
}
|
|
132
|
+
if (inherit !== undefined) process.env[inherit] = "1";
|
|
133
|
+
let released = false;
|
|
134
|
+
const release = (): void => {
|
|
135
|
+
if (released) return;
|
|
136
|
+
released = true;
|
|
137
|
+
if (inherit !== undefined) Reflect.deleteProperty(process.env, inherit);
|
|
138
|
+
process.off("exit", release);
|
|
139
|
+
try {
|
|
140
|
+
const text = nfs.readFileSync(path, "utf8");
|
|
141
|
+
if (text.includes(holder.token)) nfs.unlinkSync(path);
|
|
142
|
+
} catch (e) {
|
|
143
|
+
const mapped = mapError(e, path);
|
|
144
|
+
if (!(mapped instanceof NotFound)) throw mapped;
|
|
145
|
+
}
|
|
146
|
+
};
|
|
147
|
+
process.on("exit", release);
|
|
148
|
+
return { holder, release };
|
|
149
|
+
}
|
package/src/mod.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// Spec: 0001-system FR-020
|
|
2
|
+
/**
|
|
3
|
+
* System, the host of Intellectual Frontiers Commons as one typed library (its specification 0001-system): typed errors (as `errors`, with `mapError`, `RuntimeError` and `toError`), files (as `fs`), paths (as `path`),
|
|
4
|
+
* the folders a program keeps its files in (as `dirs`), one run at a time (as `lock`), file watching (as `watch`), programs found by the prefix of their name (as `discover`), the process and the programs it runs
|
|
5
|
+
* (as `proc`), Git read by running it (as `git`), a program built into one binary (as `compile`), the operating system's scheduled jobs installed (as `jobs`) and planned (as `jobPlan`), and the terminal's
|
|
6
|
+
* streams (as `tty` and `stdio`). It names `node:` builtins and no vendor's global, depends on core, formats and crypto, and runs the same on Bun and on Node 26.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { fs, path } from "@intellectual-frontiers/system";
|
|
11
|
+
* const text = await fs.readTextFile(path.join("a", "b.txt"));
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
export * as compile from "./compile.ts";
|
|
17
|
+
export * as dirs from "./dirs.ts";
|
|
18
|
+
export * as discover from "./discover.ts";
|
|
19
|
+
export { errors, mapError, RuntimeError, toError } from "./errors.ts";
|
|
20
|
+
export * as fs from "./fs.ts";
|
|
21
|
+
export * as git from "./git.ts";
|
|
22
|
+
export * as jobPlan from "./job-plan.ts";
|
|
23
|
+
export * as jobs from "./schedule.ts";
|
|
24
|
+
export * as lock from "./lock.ts";
|
|
25
|
+
export * as path from "./path.ts";
|
|
26
|
+
export * as proc from "./proc.ts";
|
|
27
|
+
export * as stdio from "./stdio.ts";
|
|
28
|
+
export * as tty from "./tty.ts";
|
|
29
|
+
export * as watch from "./watch.ts";
|
package/src/path.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// Spec: 0001-system FR-003
|
|
2
|
+
/**
|
|
3
|
+
* Paths, on `node:path` (commons 0005-typescript-runtime FR-021): the platform's own rules, and `posix` and `win32` for the other's, with
|
|
4
|
+
* `file:` URLs both ways. Taken from Stolos's `src/archon/core/path.ts`, which already used `node:path`; it replaces `@std/path`.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { basename, join } from "./path.ts";
|
|
9
|
+
* basename(join("a", "b", "c.txt")); // "c.txt"
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import * as nodePath from "node:path";
|
|
15
|
+
import { fileURLToPath, pathToFileURL } from "node:url";
|
|
16
|
+
|
|
17
|
+
/** Path segments joined and normalized. */
|
|
18
|
+
export const join: (...paths: string[]) => string = nodePath.join;
|
|
19
|
+
/** The folder a path is in. */
|
|
20
|
+
export const dirname: (path: string) => string = nodePath.dirname;
|
|
21
|
+
/** The last segment of a path, without `suffix` where it ends with it. */
|
|
22
|
+
export const basename: (path: string, suffix?: string) => string = nodePath.basename;
|
|
23
|
+
/** The extension of the last segment, with its dot (`.ts`), or `""`. */
|
|
24
|
+
export const extname: (path: string) => string = nodePath.extname;
|
|
25
|
+
/** The path from one to the other. */
|
|
26
|
+
export const relative: (from: string, to: string) => string = nodePath.relative;
|
|
27
|
+
/** An absolute path, the segments taken from the right until one is absolute, against the working folder. */
|
|
28
|
+
export const resolve: (...paths: string[]) => string = nodePath.resolve;
|
|
29
|
+
/** A path with `.` and `..` and repeated separators resolved. */
|
|
30
|
+
export const normalize: (path: string) => string = nodePath.normalize;
|
|
31
|
+
/** Whether a path is absolute. */
|
|
32
|
+
export const isAbsolute: (path: string) => boolean = nodePath.isAbsolute;
|
|
33
|
+
/** A path's root, folder, base, name and extension. */
|
|
34
|
+
export const parse: (path: string) => nodePath.ParsedPath = nodePath.parse;
|
|
35
|
+
/** A path made from its parts. */
|
|
36
|
+
export const format: (parts: nodePath.FormatInputPathObject) => string = nodePath.format;
|
|
37
|
+
/** This platform's separator between segments: `/`, or `\` on Windows. */
|
|
38
|
+
export const sep: string = nodePath.sep;
|
|
39
|
+
/** This platform's separator between paths in `PATH`: `:`, or `;` on Windows. */
|
|
40
|
+
export const delimiter: string = nodePath.delimiter;
|
|
41
|
+
/** The POSIX rules, on any platform. */
|
|
42
|
+
export const posix: typeof nodePath.posix = nodePath.posix;
|
|
43
|
+
/** The Windows rules, on any platform. */
|
|
44
|
+
export const win32: typeof nodePath.posix = nodePath.win32;
|
|
45
|
+
|
|
46
|
+
/** A `file:` URL as a path. */
|
|
47
|
+
export function fromFileUrl(url: string | URL): string {
|
|
48
|
+
return fileURLToPath(url);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** A path as a `file:` URL. */
|
|
52
|
+
export function toFileUrl(path: string): URL {
|
|
53
|
+
return pathToFileURL(path);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** A path with `/` between its segments whatever the platform, as archives and URLs write them. */
|
|
57
|
+
export function toPosix(path: string): string {
|
|
58
|
+
return path.split(nodePath.sep).join("/");
|
|
59
|
+
}
|