@intellectual-frontiers/system 0.0.0-stage → 0.1.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.
- 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/dist/git.d.ts
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A Git repository read by running `git` (commons 0007-grc FR-021): the commit at `HEAD`, whether the working tree is clean, the paths
|
|
3
|
+
* changed between two revisions, and a file's bytes as it is at a revision. Each runs `git -C REPO ...` by its argument vector, never
|
|
4
|
+
* through a shell, with no pager, no terminal prompt, no optional locks and messages in English; paths are read NUL-separated (`-z`), so
|
|
5
|
+
* spaces, quotes and non-ASCII names come back as they are. Every failure is an `Err` naming what went wrong, a repository that is not
|
|
6
|
+
* there and a `git` that is not installed included; nothing here throws.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { changedPaths, head } from "./git.js";
|
|
11
|
+
* const h = await head(".");
|
|
12
|
+
* if (h.kind === "ok") console.log(h.value);
|
|
13
|
+
* const changed = await changedPaths(".", "HEAD~1", "HEAD"); // { kind: "ok", value: ["src/a.ts", ...] }
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* @module
|
|
17
|
+
*/
|
|
18
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
19
|
+
import type { Brand } from "@intellectual-frontiers/core";
|
|
20
|
+
/** A commit's object id: 40 (SHA-1) or 64 (SHA-256) lower-case hexadecimal digits, made only by `commitIdOf`. */
|
|
21
|
+
export type CommitId = Brand<string, "CommitId">;
|
|
22
|
+
/** Text as a commit id, or undefined where it is not 40 or 64 lower-case hexadecimal digits. */
|
|
23
|
+
export declare function commitIdOf(text: string): CommitId | undefined;
|
|
24
|
+
/** Why a repository could not be read. */
|
|
25
|
+
export type GitError = {
|
|
26
|
+
readonly kind: "git-missing";
|
|
27
|
+
readonly program: string;
|
|
28
|
+
} | {
|
|
29
|
+
readonly kind: "not-a-repository";
|
|
30
|
+
readonly repo: string;
|
|
31
|
+
readonly message: string;
|
|
32
|
+
} | {
|
|
33
|
+
readonly kind: "bad-revision";
|
|
34
|
+
readonly rev: string;
|
|
35
|
+
readonly message: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly kind: "no-such-path";
|
|
38
|
+
readonly rev: string;
|
|
39
|
+
readonly path: string;
|
|
40
|
+
readonly message: string;
|
|
41
|
+
} | {
|
|
42
|
+
readonly kind: "failed";
|
|
43
|
+
readonly args: readonly string[];
|
|
44
|
+
readonly code: number;
|
|
45
|
+
readonly message: string;
|
|
46
|
+
};
|
|
47
|
+
/** A Git error as one sentence. */
|
|
48
|
+
export declare function formatGitError(e: GitError): string;
|
|
49
|
+
/** How `git` is run: the program (`git` on PATH by default). */
|
|
50
|
+
export type GitOptions = {
|
|
51
|
+
readonly program?: string;
|
|
52
|
+
};
|
|
53
|
+
/** The commit `HEAD` points to; `bad-revision` in a repository with no commit yet. */
|
|
54
|
+
export declare function head(repo: string, options?: GitOptions): Promise<Result<CommitId, GitError>>;
|
|
55
|
+
/** Whether the working tree and the index match `HEAD`, with no untracked file that is not ignored. */
|
|
56
|
+
export declare function isClean(repo: string, options?: GitOptions): Promise<Result<boolean, GitError>>;
|
|
57
|
+
/**
|
|
58
|
+
* The paths (relative to the repository's top, `/`-separated) whose content differs between two revisions, in Git's order, each once;
|
|
59
|
+
* a rename gives both its old and its new path.
|
|
60
|
+
*/
|
|
61
|
+
export declare function changedPaths(repo: string, from: string, to: string, options?: GitOptions): Promise<Result<readonly string[], GitError>>;
|
|
62
|
+
/** A file's bytes as it is at a revision, its path relative to the repository's top (`/`-separated); `no-such-path` where it is not there. */
|
|
63
|
+
export declare function fileAt(repo: string, rev: string, path: string, options?: GitOptions): Promise<Result<Uint8Array, GitError>>;
|
package/dist/git.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
// Spec: 0001-system FR-014
|
|
2
|
+
/**
|
|
3
|
+
* A Git repository read by running `git` (commons 0007-grc FR-021): the commit at `HEAD`, whether the working tree is clean, the paths
|
|
4
|
+
* changed between two revisions, and a file's bytes as it is at a revision. Each runs `git -C REPO ...` by its argument vector, never
|
|
5
|
+
* through a shell, with no pager, no terminal prompt, no optional locks and messages in English; paths are read NUL-separated (`-z`), so
|
|
6
|
+
* spaces, quotes and non-ASCII names come back as they are. Every failure is an `Err` naming what went wrong, a repository that is not
|
|
7
|
+
* there and a `git` that is not installed included; nothing here throws.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* import { changedPaths, head } from "./git.ts";
|
|
12
|
+
* const h = await head(".");
|
|
13
|
+
* if (h.kind === "ok") console.log(h.value);
|
|
14
|
+
* const changed = await changedPaths(".", "HEAD~1", "HEAD"); // { kind: "ok", value: ["src/a.ts", ...] }
|
|
15
|
+
* ```
|
|
16
|
+
*
|
|
17
|
+
* @module
|
|
18
|
+
*/
|
|
19
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
20
|
+
import { NotFound } from "./errors.js";
|
|
21
|
+
import { output } from "./proc.js";
|
|
22
|
+
/** Text as a commit id, or undefined where it is not 40 or 64 lower-case hexadecimal digits. */
|
|
23
|
+
export function commitIdOf(text) {
|
|
24
|
+
return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(text) ? text : undefined; // checked just now: the brand's one constructor
|
|
25
|
+
}
|
|
26
|
+
/** A Git error as one sentence. */
|
|
27
|
+
export function formatGitError(e) {
|
|
28
|
+
switch (e.kind) {
|
|
29
|
+
case "git-missing":
|
|
30
|
+
return `${e.program} is not installed (or not on PATH)`;
|
|
31
|
+
case "not-a-repository":
|
|
32
|
+
return `${e.repo} is not a Git repository: ${e.message}`;
|
|
33
|
+
case "bad-revision":
|
|
34
|
+
return `no revision ${e.rev}: ${e.message}`;
|
|
35
|
+
case "no-such-path":
|
|
36
|
+
return `no file ${e.path} at ${e.rev}: ${e.message}`;
|
|
37
|
+
case "failed":
|
|
38
|
+
return `git ${e.args.join(" ")} failed (${e.code}): ${e.message}`;
|
|
39
|
+
default:
|
|
40
|
+
return absurd(e);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
const ENV = {
|
|
44
|
+
GIT_TERMINAL_PROMPT: "0",
|
|
45
|
+
GIT_PAGER: "cat",
|
|
46
|
+
PAGER: "cat",
|
|
47
|
+
GIT_OPTIONAL_LOCKS: "0",
|
|
48
|
+
LC_ALL: "C",
|
|
49
|
+
LANGUAGE: "C",
|
|
50
|
+
};
|
|
51
|
+
/** `git --no-pager -C repo ...args`, its output, or `git-missing` where there is no git. */
|
|
52
|
+
async function git(repo, args, options) {
|
|
53
|
+
const program = options.program ?? "git";
|
|
54
|
+
try {
|
|
55
|
+
const r = await output([program, "--no-pager", "-C", repo, ...args], { env: ENV });
|
|
56
|
+
return ok({ stdout: r.stdout, stderr: new TextDecoder().decode(r.stderr).trim(), code: r.code });
|
|
57
|
+
}
|
|
58
|
+
catch (e) {
|
|
59
|
+
if (e instanceof NotFound)
|
|
60
|
+
return err({ kind: "git-missing", program });
|
|
61
|
+
return err({ kind: "failed", args, code: -1, message: e instanceof Error ? e.message : String(e) });
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/** A failed run as the error it says it is: no repository (or no folder) there, else `fallback`. */
|
|
65
|
+
function failure(repo, args, r, fallback) {
|
|
66
|
+
if (/not a git repository|cannot change to/i.test(r.stderr))
|
|
67
|
+
return { kind: "not-a-repository", repo, message: r.stderr };
|
|
68
|
+
return fallback ?? { kind: "failed", args, code: r.code, message: r.stderr };
|
|
69
|
+
}
|
|
70
|
+
/** A revision that would read as an option is refused rather than passed to git. */
|
|
71
|
+
function checkRev(rev) {
|
|
72
|
+
return rev === "" || rev.startsWith("-")
|
|
73
|
+
? err({ kind: "bad-revision", rev, message: "a revision may not be empty or start with -" })
|
|
74
|
+
: ok(rev);
|
|
75
|
+
}
|
|
76
|
+
/** The NUL-separated fields of git's `-z` output, as text. */
|
|
77
|
+
function nulFields(bytes) {
|
|
78
|
+
const text = new TextDecoder().decode(bytes);
|
|
79
|
+
return text.split("\0").filter((p) => p !== "");
|
|
80
|
+
}
|
|
81
|
+
/** The commit `HEAD` points to; `bad-revision` in a repository with no commit yet. */
|
|
82
|
+
export async function head(repo, options = {}) {
|
|
83
|
+
const args = ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"];
|
|
84
|
+
const r = await git(repo, args, options);
|
|
85
|
+
if (r.kind === "err")
|
|
86
|
+
return r;
|
|
87
|
+
if (r.value.code !== 0)
|
|
88
|
+
return err(failure(repo, args, r.value, { kind: "bad-revision", rev: "HEAD", message: r.value.stderr || "no commit yet" }));
|
|
89
|
+
const text = new TextDecoder().decode(r.value.stdout).trim();
|
|
90
|
+
const id = commitIdOf(text);
|
|
91
|
+
return id === undefined ? err({ kind: "failed", args, code: 0, message: `not a commit id: ${text}` }) : ok(id);
|
|
92
|
+
}
|
|
93
|
+
/** Whether the working tree and the index match `HEAD`, with no untracked file that is not ignored. */
|
|
94
|
+
export async function isClean(repo, options = {}) {
|
|
95
|
+
const args = ["status", "--porcelain=v1", "-z", "--untracked-files=normal", "--ignore-submodules=none"];
|
|
96
|
+
const r = await git(repo, args, options);
|
|
97
|
+
if (r.kind === "err")
|
|
98
|
+
return r;
|
|
99
|
+
if (r.value.code !== 0)
|
|
100
|
+
return err(failure(repo, args, r.value));
|
|
101
|
+
return ok(r.value.stdout.length === 0);
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* The paths (relative to the repository's top, `/`-separated) whose content differs between two revisions, in Git's order, each once;
|
|
105
|
+
* a rename gives both its old and its new path.
|
|
106
|
+
*/
|
|
107
|
+
export async function changedPaths(repo, from, to, options = {}) {
|
|
108
|
+
for (const rev of [from, to]) {
|
|
109
|
+
const c = checkRev(rev);
|
|
110
|
+
if (c.kind === "err")
|
|
111
|
+
return c;
|
|
112
|
+
const v = await git(repo, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], options);
|
|
113
|
+
if (v.kind === "err")
|
|
114
|
+
return v;
|
|
115
|
+
if (v.value.code !== 0)
|
|
116
|
+
return err(failure(repo, ["rev-parse", rev], v.value, { kind: "bad-revision", rev, message: v.value.stderr || "unknown revision" }));
|
|
117
|
+
}
|
|
118
|
+
const args = ["diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--no-textconv", from, to, "--"];
|
|
119
|
+
const r = await git(repo, args, options);
|
|
120
|
+
if (r.kind === "err")
|
|
121
|
+
return r;
|
|
122
|
+
if (r.value.code !== 0)
|
|
123
|
+
return err(failure(repo, args, r.value));
|
|
124
|
+
return ok([...new Set(nulFields(r.value.stdout))]);
|
|
125
|
+
}
|
|
126
|
+
/** A file's bytes as it is at a revision, its path relative to the repository's top (`/`-separated); `no-such-path` where it is not there. */
|
|
127
|
+
export async function fileAt(repo, rev, path, options = {}) {
|
|
128
|
+
const c = checkRev(rev);
|
|
129
|
+
if (c.kind === "err")
|
|
130
|
+
return c;
|
|
131
|
+
const v = await git(repo, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], options);
|
|
132
|
+
if (v.kind === "err")
|
|
133
|
+
return v;
|
|
134
|
+
if (v.value.code !== 0)
|
|
135
|
+
return err(failure(repo, ["rev-parse", rev], v.value, { kind: "bad-revision", rev, message: v.value.stderr || "unknown revision" }));
|
|
136
|
+
const rel = path.replaceAll("\\", "/").replace(/^\.\//, "");
|
|
137
|
+
const args = ["cat-file", "blob", `${rev}:${rel}`];
|
|
138
|
+
const r = await git(repo, args, options);
|
|
139
|
+
if (r.kind === "err")
|
|
140
|
+
return r;
|
|
141
|
+
if (r.value.code !== 0)
|
|
142
|
+
return err(failure(repo, args, r.value, { kind: "no-such-path", rev, path: rel, message: r.value.stderr }));
|
|
143
|
+
return ok(r.value.stdout);
|
|
144
|
+
}
|
|
@@ -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 "./job-plan.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>;
|