@niwa-labs/workflow 0.0.0-stage → 0.0.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.
Files changed (114) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +13 -2
  3. package/package.json +55 -4
  4. package/src/actions.ts +408 -0
  5. package/src/agent.ts +211 -0
  6. package/src/ask.ts +84 -0
  7. package/src/bridge.ts +710 -0
  8. package/src/catalogue.ts +74 -0
  9. package/src/check.ts +880 -0
  10. package/src/child.ts +1378 -0
  11. package/src/cockpit/actions.ts +128 -0
  12. package/src/cockpit/catalogue-actions.ts +97 -0
  13. package/src/cockpit/dashboard.tsx +134 -0
  14. package/src/cockpit/groups.ts +45 -0
  15. package/src/cockpit/index.tsx +50 -0
  16. package/src/cockpit/launch.tsx +136 -0
  17. package/src/cockpit/plan.ts +101 -0
  18. package/src/cockpit/run-commands.tsx +102 -0
  19. package/src/cockpit/run-page.tsx +140 -0
  20. package/src/cockpit/run-summary.ts +16 -0
  21. package/src/cockpit/runs.tsx +73 -0
  22. package/src/cockpit/statistics.tsx +176 -0
  23. package/src/cockpit/track.tsx +159 -0
  24. package/src/cockpit/workflows.tsx +383 -0
  25. package/src/describe-cache.ts +122 -0
  26. package/src/describe.ts +174 -0
  27. package/src/guide.ts +213 -0
  28. package/src/index.ts +2813 -0
  29. package/src/inspect.ts +235 -0
  30. package/src/installation.ts +90 -0
  31. package/src/language.ts +217 -0
  32. package/src/records-entry.ts +63 -0
  33. package/src/records.ts +574 -0
  34. package/src/registry.ts +250 -0
  35. package/src/revise.ts +89 -0
  36. package/src/runner.ts +339 -0
  37. package/src/script-types.ts +549 -0
  38. package/src/stats.ts +460 -0
  39. package/src/status.ts +512 -0
  40. package/src/store.ts +259 -0
  41. package/src/subscriptions.ts +102 -0
  42. package/src/waiting.ts +61 -0
  43. package/test/cockpit-actions.test.ts +20 -0
  44. package/test/cockpit-groups.test.ts +42 -0
  45. package/test/cockpit-plan.test.ts +118 -0
  46. package/test/fixtures/branches-host.ts +58 -0
  47. package/test/fixtures/branches-script.js +23 -0
  48. package/test/fixtures/bridge-host.ts +23 -0
  49. package/test/fixtures/bridge-keys-script.js +15 -0
  50. package/test/fixtures/bridge-wait-script.js +8 -0
  51. package/test/fixtures/cancel-host.ts +58 -0
  52. package/test/fixtures/cancel-script.js +12 -0
  53. package/test/fixtures/crash-host.ts +61 -0
  54. package/test/fixtures/crash-script.js +14 -0
  55. package/test/fixtures/ping-records.ts +20 -0
  56. package/test/fixtures/revision-host.ts +57 -0
  57. package/test/fixtures/revision-script.js +11 -0
  58. package/test/fixtures/running-host.ts +61 -0
  59. package/test/fixtures/running-script.js +12 -0
  60. package/test/fixtures/with-data/flow.ts +2 -0
  61. package/test/fixtures/with-data/table.json +1 -0
  62. package/test/git-repo.ts +45 -0
  63. package/test/git-worktree.test.ts +413 -0
  64. package/test/question-format.test.ts +279 -0
  65. package/test/workflow-agent-caps.test.ts +91 -0
  66. package/test/workflow-agent-lifetime.test.ts +93 -0
  67. package/test/workflow-agent-options.test.ts +216 -0
  68. package/test/workflow-agent-schema.test.ts +386 -0
  69. package/test/workflow-agent-typings.test.ts +241 -0
  70. package/test/workflow-ask-resume.test.ts +145 -0
  71. package/test/workflow-branch-keys.test.ts +133 -0
  72. package/test/workflow-bridge-inproc.test.ts +230 -0
  73. package/test/workflow-bridge.test.ts +141 -0
  74. package/test/workflow-builtin-candidate.test.ts +230 -0
  75. package/test/workflow-builtin.test.ts +197 -0
  76. package/test/workflow-cancel-agent.test.ts +144 -0
  77. package/test/workflow-cancel.test.ts +166 -0
  78. package/test/workflow-chain.test.ts +84 -0
  79. package/test/workflow-check-options.test.ts +144 -0
  80. package/test/workflow-check-uses.test.ts +148 -0
  81. package/test/workflow-check.test.ts +282 -0
  82. package/test/workflow-contract.test.ts +295 -0
  83. package/test/workflow-crash-resume.test.ts +141 -0
  84. package/test/workflow-deadline.test.ts +102 -0
  85. package/test/workflow-describe-cache.test.ts +240 -0
  86. package/test/workflow-directory.test.ts +73 -0
  87. package/test/workflow-emits.test.ts +261 -0
  88. package/test/workflow-group-keys.test.ts +72 -0
  89. package/test/workflow-harnesses.test.ts +262 -0
  90. package/test/workflow-inspect.test.ts +152 -0
  91. package/test/workflow-language-types.test.ts +148 -0
  92. package/test/workflow-manifest.test.ts +93 -0
  93. package/test/workflow-manual-pause.test.ts +116 -0
  94. package/test/workflow-owners.test.ts +154 -0
  95. package/test/workflow-pause.test.ts +200 -0
  96. package/test/workflow-phases.test.ts +445 -0
  97. package/test/workflow-plugin-entries.test.ts +59 -0
  98. package/test/workflow-record-refs.test.ts +310 -0
  99. package/test/workflow-replay.test.ts +206 -0
  100. package/test/workflow-resume-once.test.ts +188 -0
  101. package/test/workflow-revision.test.ts +216 -0
  102. package/test/workflow-scope.test.ts +505 -0
  103. package/test/workflow-script-defaults.test.ts +119 -0
  104. package/test/workflow-script-error.test.ts +228 -0
  105. package/test/workflow-script-libraries.test.ts +88 -0
  106. package/test/workflow-script-packages.test.ts +119 -0
  107. package/test/workflow-stdout.test.ts +89 -0
  108. package/test/workflow-stop.test.ts +299 -0
  109. package/test/workflow-store.test.ts +220 -0
  110. package/test/workflow-visible.test.ts +136 -0
  111. package/test/workflow-wait-version.test.ts +54 -0
  112. package/test/workflow-wait.test.ts +224 -0
  113. package/test/workflow-waiting-agent.test.ts +64 -0
  114. package/tsconfig.json +15 -0
package/src/store.ts ADDED
@@ -0,0 +1,259 @@
1
+ /**
2
+ * The code of the registered workflows, kept in the home of the host.
3
+ *
4
+ * A registration copies the source closure of its version — exactly the files whose hash is the version — under
5
+ * `<home>/workflows/<wf-id>/<version>/`, laid out as they were relative to each other, so the relative imports
6
+ * resolve in the copy as they did in the original. Next to the folder, `<version>.json` names the entry in it and
7
+ * the file the version was registered from; it is written last, so a version is stored once it is there.
8
+ *
9
+ * The manifest is what the version is: the sha256 of every code file and of every data file of the copy, the
10
+ * packages it imports by name with the version of each as it was found, and the script ABI it was registered
11
+ * for. A start, a check and a run read the copy through it: a copy whose files are not the ones it names, or
12
+ * one made for another ABI, is refused. A manifest that names only the entry is completed from the copy,
13
+ * which is the version when its hash says so.
14
+ *
15
+ * What a registered version runs, is checked and resumed on is its copy: the file it was registered from may be
16
+ * edited or deleted. A version is written once: the same version is the same folder, it is not written again.
17
+ *
18
+ * A script takes `z`, `workflow` and `niwa` as globals and its types from `@niwa-labs/script`, which the check maps
19
+ * wherever the script is. A package it imports by name is found as the runtime and the check find any: in a
20
+ * `node_modules` above the file. `<home>/workflows/node_modules` is a link to the packages niwa runs with, so a
21
+ * copy finds the ones a script in niwa's own tree finds. The folder of each workflow holds a link to each package a
22
+ * plugin offers to scripts from outside niwa's tree (`<wf-id>/node_modules/@niwa-labs/forge`), so its copies find it as
23
+ * the script did where it was written. The links are inside the folder a box may read: a box that cannot list a folder
24
+ * does not find the `node_modules` in it.
25
+ */
26
+
27
+ import { createHash } from "node:crypto";
28
+ import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
29
+ import { dirname, isAbsolute, join, relative, sep } from "node:path";
30
+
31
+ import { SCRIPT_ABI } from "@niwa-labs/script";
32
+ import { z } from "zod";
33
+
34
+ import { modulesDir } from "./installation.ts";
35
+ import { closureOf, isCode, packageImportsOf, versionOf, versionOfClosure } from "./registry.ts";
36
+ import type { SourceClosure } from "./registry.ts";
37
+ import type { WorkflowId, WorkflowVersion } from "./records.ts";
38
+
39
+ /** The folder of the stored workflows in a home. */
40
+ export const WORKFLOWS_DIR = "workflows";
41
+
42
+ const Manifest = z.object({
43
+ /** The entry of the script, relative to the folder of the version. */
44
+ entry: z.string(),
45
+ /** The file the version was registered from. */
46
+ from: z.string(),
47
+ /** The script ABI the version was registered for. */
48
+ abi: z.number().int().positive(),
49
+ /** The code files of the copy, by their path in it, with their sha256. */
50
+ files: z.record(z.string(), z.string()),
51
+ /** The data files the code imports, by their path in the copy, with their sha256. */
52
+ data: z.record(z.string(), z.string()),
53
+ /** The packages the code imports by name, with the version of each as it was found; null for one that was not. */
54
+ imports: z.record(z.string(), z.string().nullable()),
55
+ });
56
+ type Manifest = z.infer<typeof Manifest>;
57
+
58
+ /** A manifest written before it said more than where the entry is. */
59
+ const EntryOnly = Manifest.pick({ entry: true, from: true });
60
+
61
+ const sha256 = (bytes: Buffer): string => createHash("sha256").update(bytes).digest("hex");
62
+
63
+ /** The version of the package a specifier names, as it is found from `from`; null when it is not found. */
64
+ function packageVersionOf(specifier: string, from: string): string | null {
65
+ const name = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : (specifier.split("/")[0] ?? specifier);
66
+ let entry: string;
67
+ try {
68
+ entry = Bun.resolveSync(specifier, from);
69
+ } catch {
70
+ return null;
71
+ }
72
+ for (let dir = dirname(entry); dirname(dir) !== dir; dir = dirname(dir)) {
73
+ const manifest = join(dir, "package.json");
74
+ if (!existsSync(manifest)) continue;
75
+ const found = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string; version?: string };
76
+ if (found.name === name) return found.version ?? null;
77
+ }
78
+ return null;
79
+ }
80
+
81
+ /** The manifest of a closure laid out under `root`. */
82
+ function manifestOfClosure(closure: SourceClosure, root: string, from: string): Manifest {
83
+ const files: Record<string, string> = {};
84
+ const data: Record<string, string> = {};
85
+ for (const [path, bytes] of [...closure.files].sort(([a], [b]) => a.localeCompare(b))) {
86
+ (isCode(path) ? files : data)[relative(root, path)] = sha256(bytes);
87
+ }
88
+ const imports = Object.fromEntries(packageImportsOf(closure).map((specifier) => [specifier, packageVersionOf(specifier, closure.entry)]));
89
+ return { entry: relative(root, closure.entry), from, abi: SCRIPT_ABI, files, data, imports };
90
+ }
91
+
92
+ function writeManifest(path: string, manifest: Manifest): void {
93
+ const aside = `${path}.tmp-${String(process.pid)}`;
94
+ writeFileSync(aside, `${JSON.stringify(manifest, null, 2)}\n`);
95
+ renameSync(aside, path);
96
+ }
97
+
98
+ /**
99
+ * The folder of the stored copies in a home. A box that runs a copy may read it: the copy finds the packages
100
+ * it imports by name by looking for `node_modules` in the folders above it, up to the link in this one.
101
+ */
102
+ export const workflowsDir = (home: string): string => join(home, WORKFLOWS_DIR);
103
+
104
+ /** Make `link` a link to the folder `target`, when it is not that link already; it is swapped in whole. */
105
+ function linkFolder(link: string, target: string): void {
106
+ const present = lstatSync(link, { throwIfNoEntry: false });
107
+ if (present?.isSymbolicLink() === true && readlinkSync(link) === target) return;
108
+ mkdirSync(dirname(link), { recursive: true });
109
+ const aside = `${link}.tmp-${String(process.pid)}`;
110
+ rmSync(aside, { force: true });
111
+ symlinkSync(target, aside, "dir");
112
+ renameSync(aside, link);
113
+ }
114
+
115
+ /** Link `<home>/workflows/node_modules` to the packages niwa runs with, when it is not that link already. */
116
+ function linkPackages(home: string): void {
117
+ const modules = modulesDir();
118
+ if (modules === undefined) return;
119
+ linkFolder(join(workflowsDir(home), "node_modules"), realpathSync(modules));
120
+ }
121
+
122
+ /** A package a plugin offers to scripts, with its folder. */
123
+ export interface OfferedPackage {
124
+ /** `@niwa-labs/<name>`. */
125
+ readonly name: string;
126
+ /** Its folder, with the links resolved. */
127
+ readonly root: string;
128
+ }
129
+
130
+ /** A package a plugin offers to scripts, as it is found: its name and folder, or why it is not one. */
131
+ export function offeredPackageOf(name: string, root: string): OfferedPackage | string {
132
+ if (!/^@niwa-labs\/[a-z0-9][a-z0-9._-]*$/.test(name)) return `"${name}" is not a package of @niwa-labs`;
133
+ if (!isAbsolute(root)) return `the folder of ${name} is not an absolute path: ${root}`;
134
+ let found: unknown;
135
+ try {
136
+ found = (JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { name?: unknown }).name;
137
+ } catch {
138
+ found = undefined;
139
+ }
140
+ if (found !== name) return `${root} is not the folder of ${name}`;
141
+ return { name, root: realpathSync(root) };
142
+ }
143
+
144
+ /**
145
+ * Make the folder of every stored workflow hold a link to each package plugins offer to scripts now, and nothing else:
146
+ * a package no plugin offers any more is not found by a copy.
147
+ */
148
+ export function linkOfferedPackages(home: string, packages: readonly OfferedPackage[]): void {
149
+ const dir = workflowsDir(home);
150
+ if (!existsSync(dir)) return;
151
+ const wanted = new Map(packages.map((one) => [one.name.slice("@niwa-labs/".length), one.root]));
152
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
153
+ if (!entry.isDirectory() || !entry.name.startsWith("wf-")) continue;
154
+ const scope = join(dir, entry.name, "node_modules", "@niwa-labs");
155
+ if (existsSync(scope)) {
156
+ for (const name of readdirSync(scope)) if (!wanted.has(name)) rmSync(join(scope, name), { force: true });
157
+ }
158
+ for (const [name, root] of wanted) linkFolder(join(scope, name), root);
159
+ }
160
+ }
161
+
162
+ const versionDir = (home: string, id: WorkflowId, version: WorkflowVersion): string => join(home, WORKFLOWS_DIR, id, version);
163
+ const manifestOf = (home: string, id: WorkflowId, version: WorkflowVersion): string => join(home, WORKFLOWS_DIR, id, `${version}.json`);
164
+
165
+ /** A stored version read through its manifest: the entry of its copy, or why the copy does not run. */
166
+ export type StoredVersion = { entry: string } | { problem: string };
167
+
168
+ /**
169
+ * The stored copy of a version as its manifest says it is: its entry, or why it is not what was registered.
170
+ * Undefined when niwa holds no copy of it.
171
+ */
172
+ export function storedVersion(home: string, id: WorkflowId, version: WorkflowVersion): StoredVersion | undefined {
173
+ const path = manifestOf(home, id, version);
174
+ if (!existsSync(path)) return undefined;
175
+ const dir = versionDir(home, id, version);
176
+ const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
177
+ let manifest: Manifest;
178
+ const full = Manifest.safeParse(raw);
179
+ if (full.success) {
180
+ manifest = full.data;
181
+ } else {
182
+ const { entry, from } = EntryOnly.parse(raw);
183
+ const closure = closureOf(join(dir, entry));
184
+ if (closure === undefined || versionOfClosure(closure) !== version) return { problem: `the copy of the version ${version} of ${id} is not that version: register it again` };
185
+ manifest = manifestOfClosure(closure, dir, from);
186
+ writeManifest(path, manifest);
187
+ }
188
+ if (manifest.abi !== SCRIPT_ABI) {
189
+ return { problem: `the version ${version} of ${id} was registered for the script ABI ${String(manifest.abi)}, and niwa reads ${String(SCRIPT_ABI)}: register it again` };
190
+ }
191
+ for (const [file, hash] of [...Object.entries(manifest.files), ...Object.entries(manifest.data)]) {
192
+ const at = join(dir, file);
193
+ if (!existsSync(at) || sha256(readFileSync(at)) !== hash) {
194
+ return { problem: `the copy of the version ${version} of ${id} changed: "${file}" is not the file it was registered with` };
195
+ }
196
+ }
197
+ return { entry: join(dir, manifest.entry) };
198
+ }
199
+
200
+ /** The entry of the stored copy of a version, or undefined when niwa holds no copy of it that is the version. */
201
+ export function storedEntry(home: string, id: WorkflowId, version: WorkflowVersion): string | undefined {
202
+ const stored = storedVersion(home, id, version);
203
+ return stored !== undefined && "entry" in stored ? stored.entry : undefined;
204
+ }
205
+
206
+ /** The folder all the files of a closure are under. */
207
+ function commonRoot(paths: readonly string[]): string {
208
+ const [first, ...rest] = paths.map((path) => dirname(path).split(sep));
209
+ let common = first ?? [];
210
+ for (const parts of rest) {
211
+ let at = 0;
212
+ while (at < common.length && at < parts.length && common[at] === parts[at]) at += 1;
213
+ common = common.slice(0, at);
214
+ }
215
+ return common.join(sep) || sep;
216
+ }
217
+
218
+ /**
219
+ * Keep the code of a version: copy the source closure of `file` into the home and answer the entry of the copy.
220
+ * The closure must be the version (a script edited since its check is not stored); a version already stored is
221
+ * left as it is.
222
+ */
223
+ export function storeVersion(home: string, id: WorkflowId, version: WorkflowVersion, file: string): string {
224
+ linkPackages(home);
225
+ const known = storedVersion(home, id, version);
226
+ if (known !== undefined) {
227
+ if ("problem" in known) throw new Error(known.problem);
228
+ return known.entry;
229
+ }
230
+ const closure = closureOf(file);
231
+ if (closure === undefined || versionOfClosure(closure) !== version) {
232
+ throw new Error(`the script "${file}" changed while it was registered: register it again`);
233
+ }
234
+ const root = commonRoot([...closure.files.keys()]);
235
+ const dir = versionDir(home, id, version);
236
+ const entry = relative(root, closure.entry);
237
+ if (!existsSync(dir)) {
238
+ // The folder is written aside and moved in whole: a version is never half a copy.
239
+ const aside = `${dir}.tmp-${String(process.pid)}-${String(Date.now())}`;
240
+ for (const [path, bytes] of closure.files) {
241
+ const target = join(aside, relative(root, path));
242
+ mkdirSync(dirname(target), { recursive: true });
243
+ writeFileSync(target, bytes);
244
+ }
245
+ if (versionOf(join(aside, entry)) !== version) {
246
+ rmSync(aside, { recursive: true, force: true });
247
+ throw new Error(`the copy of "${file}" is not its version ${version}`);
248
+ }
249
+ try {
250
+ renameSync(aside, dir);
251
+ } catch (error) {
252
+ rmSync(aside, { recursive: true, force: true });
253
+ // Another registration of the same version moved its copy in first: it is the same code.
254
+ if (!existsSync(dir)) throw error;
255
+ }
256
+ }
257
+ writeManifest(manifestOf(home, id, version), manifestOfClosure(closure, root, closure.entry));
258
+ return join(dir, entry);
259
+ }
@@ -0,0 +1,102 @@
1
+ /**
2
+ * The installations of the workflow module as the journal holds them.
3
+ *
4
+ * An installation is a `workflow.subscription.installed` record, and it lasts until a
5
+ * `workflow.subscription.uninstalled` record of the same id that comes after it. Nothing is kept
6
+ * outside the journal, so a restart of the host loses nothing.
7
+ */
8
+
9
+ import { CORE_TYPES, RuleSpecSchema, grant } from "@niwa-labs/core";
10
+ import type { EntityDescription, Grant, IssuedId, JournalReader, Principal, StoredRecord } from "@niwa-labs/core";
11
+ import { z } from "zod";
12
+
13
+ import type { WorkflowPhases } from "./language.ts";
14
+ import { SubscriptionInstalled, SubscriptionUninstalled } from "./records.ts";
15
+ import type { Builtin, ContractHash, InstallationId, JsonSchemaValue, Subscription, WorkflowId, WorkflowVersion } from "./records.ts";
16
+
17
+ /** One installation, with the places in the journal where it began and where it ended. */
18
+ export interface Installation {
19
+ id: InstallationId;
20
+ description: EntityDescription;
21
+ /** The registered workflow that was installed, and its version, when it was installed by its id. */
22
+ workflow?: WorkflowId;
23
+ version?: WorkflowVersion;
24
+ /** The record that made it: the seed of its id. */
25
+ record: StoredRecord["id"];
26
+ file: string;
27
+ hash: string;
28
+ on: Subscription[];
29
+ uses: string[];
30
+ /** What the script declared at the installation: its schemas as JSON Schema, and their hash. */
31
+ input?: JsonSchemaValue;
32
+ output?: JsonSchemaValue;
33
+ contract: ContractHash;
34
+ /** The plan declared by the installed script. */
35
+ phases?: WorkflowPhases;
36
+ /** Absent when nothing limited the installer. */
37
+ installer?: Principal;
38
+ /** Whether its runs are boxed. */
39
+ box?: boolean;
40
+ /** The built-in it is, when the workflow module made it for a plugin. */
41
+ builtin?: Builtin;
42
+ /** The position of the record that installed it: only records after it start runs. */
43
+ seq: number;
44
+ /** The position of the record that ended it, when it has ended. */
45
+ removed?: number;
46
+ }
47
+
48
+ /** The profile the runs of an installation are held to. */
49
+ export const profileOf = (id: InstallationId): string => `wf:${id}`;
50
+
51
+ /** Every installation the journal holds, the ended ones too, in the order they were made. */
52
+ export function installationsOf(journal: JournalReader): Installation[] {
53
+ const ends = journal.find({ type: SubscriptionUninstalled.name }).map((row) => ({
54
+ seq: row.seq,
55
+ id: SubscriptionUninstalled.schema.parse(row.data).installation,
56
+ }));
57
+ return journal.find({ type: SubscriptionInstalled.name }).map((row): Installation => {
58
+ const data = SubscriptionInstalled.schema.parse(row.data);
59
+ const removed = ends.find((end) => end.id === data.installation && end.seq > row.seq)?.seq;
60
+ return {
61
+ id: data.installation,
62
+ description: data.description,
63
+ ...(data.workflow === undefined ? {} : { workflow: data.workflow }),
64
+ ...(data.version === undefined ? {} : { version: data.version }),
65
+ record: row.id,
66
+ file: data.file,
67
+ hash: data.hash,
68
+ on: data.on,
69
+ uses: data.uses,
70
+ ...(data.input === undefined ? {} : { input: data.input }),
71
+ ...(data.output === undefined ? {} : { output: data.output }),
72
+ contract: data.contract,
73
+ ...(data.phases === undefined ? {} : { phases: data.phases }),
74
+ ...(data.installer === undefined ? {} : { installer: data.installer }),
75
+ ...(data.box === undefined ? {} : { box: data.box }),
76
+ ...(data.builtin === undefined ? {} : { builtin: data.builtin }),
77
+ seq: row.seq,
78
+ ...(removed === undefined ? {} : { removed }),
79
+ };
80
+ });
81
+ }
82
+
83
+ /** The installations that stood at a position of the journal: made before it, not ended before it. */
84
+ export function standingAt(installations: readonly Installation[], at: number): Installation[] {
85
+ return installations.filter((one) => one.seq < at && (one.removed === undefined || one.removed > at));
86
+ }
87
+
88
+ /** The installations that stand now. */
89
+ export const standing = (journal: JournalReader): Installation[] => standingAt(installationsOf(journal), journal.last() + 1);
90
+
91
+ /** The installation ids that were issued, each with the record it was born in. */
92
+ export const installationIdsOf = (journal: JournalReader): IssuedId[] =>
93
+ installationsOf(journal).map((one) => ({ id: one.id, seed: one.record }));
94
+
95
+ const ProfileData = z.object({ name: z.string(), rules: z.array(RuleSpecSchema) });
96
+
97
+ /** The rules the profile has now, as its latest `niwa.access.profile` record says; none when it was never set. */
98
+ export function profileRulesOf(journal: JournalReader, id: InstallationId): Grant | undefined {
99
+ const last = journal.find({ type: CORE_TYPES.accessProfile, field: "name", equals: profileOf(id) }).at(-1);
100
+ if (last === undefined) return undefined;
101
+ return grant(ProfileData.parse(last.data).rules);
102
+ }
package/src/waiting.ts ADDED
@@ -0,0 +1,61 @@
1
+ /**
2
+ * What a run that is going waits for, read from its journal: the
3
+ * oldest step of its latest start that has begun and not ended, in a few words.
4
+ */
5
+
6
+ import { CORE_TYPES, WAIT_ACTION } from "@niwa-labs/core";
7
+ import type { JournalReader } from "@niwa-labs/core";
8
+ import { SessionStarted, SessionTurnStarted } from "@niwa-labs/sessions/records";
9
+ import { SleepRequested, clockOf } from "@niwa-labs/timer/records";
10
+ import { z } from "zod";
11
+
12
+ import { WAIT_NAME } from "./bridge.ts";
13
+ import { RunRequested, RunStarted } from "./records.ts";
14
+
15
+ const Intent = z.object({ action: z.string(), key: z.string(), operationId: z.string(), input: z.unknown().optional() });
16
+
17
+ const START = "session.start";
18
+
19
+ /** The text after `label:`, or the key as it is. */
20
+ const labelOf = (key: string): string => key.replace(/^label:/, "");
21
+
22
+ /**
23
+ * What the run waits for: `sleep <label> until HH:MM:SS`, `ask <request>`, `session <harness> <session> turn N`, `wait <type>`, or the action it calls. Nothing when it is not waiting for anything.
24
+ */
25
+ export function waitingFor(journal: JournalReader, run: string, requests: readonly string[]): string | undefined {
26
+ const asked = requests[0];
27
+ if (asked !== undefined) return `ask ${asked}`;
28
+ const requested = journal.find({ type: RunRequested.name, field: "run", equals: run }).at(-1);
29
+ const started = journal.find({ type: RunStarted.name, field: "run", equals: run, after: requested?.seq }).at(-1);
30
+ if (requested === undefined || started?.actor.kind !== "handler") return undefined;
31
+ const invocation = String(started.actor.invocation);
32
+ const ended = journal.find({ type: CORE_TYPES.stepOutcome, field: "invocation", equals: invocation });
33
+ const intent = journal
34
+ .find({ type: CORE_TYPES.stepIntent, field: "invocation", equals: invocation })
35
+ .find((row) => !ended.some((outcome) => outcome.seq > row.seq && (outcome.data as { key?: unknown }).key === (row.data as { key?: unknown }).key));
36
+ if (intent === undefined) return undefined;
37
+ const { action, key, operationId, input } = Intent.parse(intent.data);
38
+ const given = (input ?? {}) as { type?: unknown; types?: unknown; verb?: unknown; name?: unknown; session?: unknown };
39
+ if (action === START || action.startsWith(`${START}.`) || action === "session.ask") {
40
+ const row = action === "session.ask" && typeof given.session === "string"
41
+ ? journal.find({ type: SessionStarted.name, field: "id", equals: given.session }).at(-1)
42
+ : journal.find({ type: SessionStarted.name }).findLast((row) =>
43
+ row.actor.kind === "handler" && row.actor.invocation === invocation &&
44
+ (row.id.startsWith(`${operationId}/emit/`) || row.id.startsWith(`${operationId}.step-`)));
45
+ if (row === undefined) return action === "session.ask" ? "session turn" : `starting session ${action.slice(START.length + 1)}`.trim();
46
+ const started = SessionStarted.schema.parse(row.data);
47
+ const turn = journal.find({ type: SessionTurnStarted.name, field: "session", equals: started.session }).at(-1);
48
+ const harness = started.session.slice(0, started.session.indexOf(" "));
49
+ return `session ${harness} ${started.id}${turn === undefined ? "" : ` turn ${String(SessionTurnStarted.schema.parse(turn.data).turn)}`}`;
50
+ }
51
+ if (action === WAIT_ACTION || action === WAIT_NAME) {
52
+ if (given.type === "timer.slept") {
53
+ const sleeping = journal.find({ type: SleepRequested.name, field: "key", equals: `${invocation}:${key}` }).at(-1);
54
+ const until = sleeping === undefined ? "" : ` until ${clockOf(SleepRequested.schema.parse(sleeping.data).at)}`;
55
+ return `sleep ${labelOf(key)}${until}`;
56
+ }
57
+ return `wait ${typeof given.type === "string" ? given.type : Array.isArray(given.types) ? given.types.join(",") : labelOf(key)}`;
58
+ }
59
+ if (action === "workflow.authorize") return `permission ${String(given.verb)} ${String(given.name)}`;
60
+ return `call ${action}`;
61
+ }
@@ -0,0 +1,20 @@
1
+ // The copy of the workflow actions the cockpit module keeps reads what the host answers and sends what it takes.
2
+
3
+ import { expect, test } from "bun:test";
4
+ import { unreadable, unsendable } from "@niwa-labs/testing";
5
+
6
+ import { workflowCancel, workflowInspect, workflowResume, workflowRuns, workflowStop } from "../src/index.ts";
7
+ import { cancelAction, inspectAction, resumeAction, runsAction, stopAction } from "../src/cockpit/actions.ts";
8
+
9
+ test.each([
10
+ ["workflow.runs", runsAction, workflowRuns],
11
+ ["workflow.inspect", inspectAction, workflowInspect],
12
+ ["workflow.resume", resumeAction, workflowResume],
13
+ ["workflow.cancel", cancelAction, workflowCancel],
14
+ ["workflow.stop", stopAction, workflowStop],
15
+ ] as const)("%s is sent as the host takes it and its answer is read", (name, copy, real) => {
16
+ expect(copy.name).toBe(name);
17
+ expect(String(real.name)).toBe(name);
18
+ expect(unsendable(copy.input, real.input)).toEqual([]);
19
+ expect(unreadable(copy.output, real.output)).toEqual([]);
20
+ });
@@ -0,0 +1,42 @@
1
+ // The runs of the home page, in blocks by the directory they were started for.
2
+
3
+ import { expect, test } from "bun:test";
4
+
5
+ import type { RunEntry } from "../src/cockpit/actions.ts";
6
+ import { directoryName, groupByDirectory } from "../src/cockpit/groups.ts";
7
+
8
+ function entry(run: string, requestedAt: string, directory?: string): RunEntry {
9
+ return { run, name: run, state: "finished", requestedAt, about: "", requests: 0, ...(directory === undefined ? {} : { directory }) };
10
+ }
11
+
12
+ test("a directory is named by its last part", () => {
13
+ expect(directoryName("/work/niwa")).toBe("niwa");
14
+ expect(directoryName("/work/niwa/")).toBe("niwa");
15
+ expect(directoryName("C:\\work\\niwa")).toBe("niwa");
16
+ expect(directoryName("/")).toBe("/");
17
+ });
18
+
19
+ test("runs of one directory are one block, the latest run first", () => {
20
+ const groups = groupByDirectory([entry("a", "2026-01-01T00:00:00Z", "/work/x"), entry("b", "2026-01-03T00:00:00Z", "/work/x"), entry("c", "2026-01-02T00:00:00Z", "/work/x")]);
21
+ expect(groups).toHaveLength(1);
22
+ expect(groups[0]).toMatchObject({ directory: "/work/x", name: "x" });
23
+ expect(groups[0]?.runs.map((run) => run.run)).toEqual(["b", "c", "a"]);
24
+ });
25
+
26
+ test("blocks go by their latest run, and the runs with no directory come last", () => {
27
+ const groups = groupByDirectory([
28
+ entry("old", "2026-01-01T00:00:00Z", "/work/old"),
29
+ entry("loose", "2026-01-09T00:00:00Z"),
30
+ entry("new", "2026-01-05T00:00:00Z", "/work/new"),
31
+ ]);
32
+ expect(groups.map((group) => group.directory)).toEqual(["/work/new", "/work/old", undefined]);
33
+ expect(groups.at(-1)?.name).toBe("No directory");
34
+ });
35
+
36
+ test("a trailing separator does not make a second block, and an empty directory is none", () => {
37
+ const groups = groupByDirectory([entry("a", "2026-01-01T00:00:00Z", "/work/x"), entry("b", "2026-01-02T00:00:00Z", "/work/x/"), entry("c", "2026-01-03T00:00:00Z", "")]);
38
+ expect(groups.map((group) => [group.directory, group.runs.length])).toEqual([
39
+ ["/work/x", 2],
40
+ [undefined, 1],
41
+ ]);
42
+ });
@@ -0,0 +1,118 @@
1
+ // The plan of a run page: the declared phases, then the steps that named none.
2
+
3
+ import { expect, test } from "bun:test";
4
+
5
+ import { describeRecompute } from "@niwa-labs/ui-kit";
6
+ import { decide } from "../src/revise.ts";
7
+ import type { Inspection, Step } from "../src/cockpit/actions.ts";
8
+ import { planOf, recomputeOf, stepDuration, stepState, STEPS_PHASE, stopOf } from "../src/cockpit/plan.ts";
9
+
10
+ function step(id: string, status: Step["status"], extra: Partial<Step> = {}): Step {
11
+ return { id, label: id, key: id, action: "niwa.now", startedAt: "2026-01-01T00:00:00.000Z", status, ...extra };
12
+ }
13
+
14
+ function inspection(over: Partial<Inspection>): Inspection {
15
+ return {
16
+ run: "run-1",
17
+ status: { run: "run-1", state: "running", requests: [] },
18
+ origin: { file: "/w/a.js", requestedAt: "2026-01-01T00:00:00.000Z" },
19
+ phases: [],
20
+ steps: [],
21
+ ...over,
22
+ };
23
+ }
24
+
25
+ const plain = (one: Step) => ({ id: one.id, title: one.label, state: stepState(one) });
26
+
27
+ test("a step status is shown as the state of a ring", () => {
28
+ expect(stepState(step("a", "paused"))).toBe("waiting");
29
+ expect(stepState(step("a", "completed"))).toBe("done");
30
+ expect(stepState(step("a", "cancelled"))).toBe("stopped");
31
+ expect(stepState(step("a", "unknown"))).toBe("unknown");
32
+ expect(stepState(step("a", "unknown", { reused: true }))).toBe("unknown");
33
+ });
34
+
35
+ test("selecting a send with an unknown outcome warns about repeating its effect", () => {
36
+ const send = step("Send", "unknown", { effect: true });
37
+ const later = step("Later", "completed", { effect: true, key: "left/after" });
38
+ const sibling = step("Sibling", "completed", { key: "right/other" });
39
+ const inspected = inspection({ steps: [send, later, sibling] });
40
+ const target = { phase: "steps", step: send.id };
41
+ const phases = planOf(inspected, (one) => ({ ...plain(one), effect: one.effect }));
42
+ const resume = recomputeOf(inspected, target);
43
+ expect(resume).toEqual({ run: inspected.run, from: send.key });
44
+ const confirmation = describeRecompute(phases, target);
45
+ expect(confirmation).toContain("unknown outcome");
46
+ expect(confirmation).toContain("Previously sent messages or other external changes may be repeated.");
47
+ for (const [one, after, expected] of [[send, false, false], [later, true, true], [sibling, false, true]] as const) {
48
+ const call = { key: one.key, action: one.action, input: {} };
49
+ const previous = { ...call, finished: one.status === "completed", recovery: one.effect ? "do-not-repeat" as const : "repeat" as const, invocation: "previous" };
50
+ expect(decide(previous, call, { after, recompute: resume.from === one.key }).taken).toBe(expected);
51
+ }
52
+ });
53
+
54
+ test("how long a step took is known once it ended", () => {
55
+ expect(stepDuration(step("a", "running"))).toBeUndefined();
56
+ expect(stepDuration(step("a", "completed", { endedAt: "2026-01-01T00:00:02.500Z" }))).toBe(2500);
57
+ expect(stepDuration(step("a", "completed", { endedAt: "2025-12-31T00:00:00.000Z" }))).toBeUndefined();
58
+ });
59
+
60
+ test("a script with no phases has one phase that holds its steps and its controls", () => {
61
+ const plan = planOf(inspection({ steps: [step("s1", "completed")] }), plain);
62
+ expect(plan).toHaveLength(1);
63
+ expect(plan[0]).toMatchObject({ title: "Run", state: "running", steps: [{ id: "s1", state: "done" }] });
64
+ });
65
+
66
+ test("a run with no step yet still has a row", () => {
67
+ const plan = planOf(inspection({}), plain);
68
+ expect(plan).toMatchObject([{ title: "Run", state: "running", steps: [] }]);
69
+ });
70
+
71
+ test("declared phases keep their order, and the steps outside every phase follow as the last", () => {
72
+ const plan = planOf(
73
+ inspection({
74
+ phases: [
75
+ { title: "Plan", state: "done", steps: [step("p1", "completed")] },
76
+ { title: "Build", state: "current", steps: [step("b1", "paused")] },
77
+ { title: "Ship", state: "ahead", steps: [] },
78
+ ],
79
+ steps: [step("loose", "running")],
80
+ status: { run: "run-1", state: "paused", requests: ["req-1"], reason: "asks" },
81
+ }),
82
+ plain,
83
+ );
84
+ expect(plan.map((phase) => [phase.title, phase.state])).toEqual([
85
+ ["Plan", "done"],
86
+ ["Build", "waiting"],
87
+ ["Ship", "pending"],
88
+ [STEPS_PHASE, "running"],
89
+ ]);
90
+ });
91
+
92
+ test("the current phase takes on how the run ended", () => {
93
+ const phases = [{ title: "Build", state: "current" as const, steps: [] }];
94
+ expect(planOf(inspection({ phases, status: { run: "r", state: "finished", requests: [], outcome: { status: "failed", error: { message: "boom" } } } }), plain)[0]?.state).toBe("failed");
95
+ expect(planOf(inspection({ phases, status: { run: "r", state: "finished", requests: [], outcome: { status: "cancelled" } } }), plain)[0]?.state).toBe("stopped");
96
+ });
97
+
98
+ test("a step a later start took is shown as reused, and a step with an effect says so to the plan", () => {
99
+ expect(stepState(step("a", "completed", { reused: true }))).toBe("reused");
100
+ expect(stepState(step("a", "completed"))).toBe("done");
101
+ });
102
+
103
+ test("recomputing a step runs again from its key, a phase from its title, and the row of loose steps from the top", () => {
104
+ const run = inspection({
105
+ phases: [{ title: "Review", state: "done", steps: [step("r1", "completed", { key: "label:review" })] }],
106
+ steps: [step("s1", "completed", { key: "call-3" })],
107
+ });
108
+ expect(recomputeOf(run, { phase: "phase-0", step: "r1" })).toEqual({ run: "run-1", from: "label:review" });
109
+ expect(recomputeOf(run, { phase: "phase-0" })).toEqual({ run: "run-1", from: "Review" });
110
+ expect(recomputeOf(run, { phase: "steps", step: "s1" })).toEqual({ run: "run-1", from: "call-3" });
111
+ expect(recomputeOf(run, { phase: "steps" })).toEqual({ run: "run-1" });
112
+ });
113
+
114
+ test("stopping a step stops it by its key and leaves the run going; stopping a phase stops the run", () => {
115
+ const run = inspection({ steps: [step("s1", "running", { key: "@review.a.call-1", branch: "@review.a" })] });
116
+ expect(stopOf(run, { phase: "steps", step: "s1" })).toEqual({ run: "run-1", at: "@review.a.call-1" });
117
+ expect(stopOf(run, { phase: "steps" })).toEqual({ run: "run-1" });
118
+ });
@@ -0,0 +1,58 @@
1
+ // The host program where the key of an unlabeled call says its branch.
2
+ //
3
+ // It installs the workflow plugin with a stub agent action. The action counts its calls and
4
+ // waits on a gate of its own prompt, so the branches of the script answer in the order the
5
+ // test opens the gates: the second branch may answer before the first.
6
+ //
7
+ // The home directory comes from argv[2].
8
+
9
+ import { action } from "@niwa-labs/core";
10
+ import { plugin } from "@niwa-labs/plugin";
11
+ import { counter, gate } from "@niwa-labs/testing";
12
+ import { workflow } from "../../src/index.ts";
13
+ import { z } from "zod";
14
+
15
+
16
+
17
+ const AgentInput = z.object({
18
+ prompt: z.string(),
19
+ harness: z.string().optional(),
20
+ label: z.string().optional(),
21
+ });
22
+
23
+ const AgentOutput = z.object({ answer: z.string() });
24
+
25
+ if (import.meta.main) {
26
+ const home = process.argv[2];
27
+ if (!home) {
28
+ console.error("usage: bun branches-host.ts <home>");
29
+ process.exit(2);
30
+ }
31
+
32
+ const calls = counter(home, "branches.agent");
33
+
34
+ const agent = action("branches.agent", {
35
+ description: "A stubbed agent: it counts its calls and waits on the gate of its prompt.",
36
+ input: AgentInput,
37
+ output: AgentOutput,
38
+ recovery: "repeat",
39
+ effect: "write",
40
+ async run(input: z.infer<typeof AgentInput>): Promise<z.infer<typeof AgentOutput>> {
41
+ calls.hit();
42
+ // The gate of the call: the test opens the gates in the order it wants the calls to end.
43
+ await gate(home, `branches.gate.${input.prompt}`).wait();
44
+ return { answer: `answered: ${input.prompt}` };
45
+ },
46
+ });
47
+
48
+ const { createNiwa } = await import("@niwa-labs/testing");
49
+ const niwa = createNiwa({ home });
50
+ // The stub is an action of the host too, so a script may name it in `meta.uses`: the owner who starts the run holds a grant.
51
+ niwa.use(plugin("branches-agent", (api) => api.action(agent)));
52
+ niwa.use(workflow({ agentAction: agent }));
53
+ await niwa.serve();
54
+
55
+ process.on("SIGTERM", () => {
56
+ void niwa.close().then(() => process.exit(0));
57
+ });
58
+ }