@niwa-labs/script 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.
- package/LICENSE +21 -0
- package/README.md +2 -2
- package/package.json +12 -4
- package/src/header.ts +213 -0
- package/src/index.ts +10 -0
- package/src/script-api.ts +404 -0
- package/test/api-imports.test.ts +29 -0
- package/test/api-types.test.ts +112 -0
- package/test/header.test.ts +70 -0
- package/tsconfig.json +7 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/script
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The types of the workflow script language: step signatures, the `ScriptApi` interface and the declarations a script makes, in a file that imports nothing. It also holds the reader of a script's header (`scriptOn` and the helpers under it), which reads the declaration from the text without running the script. It needs no host and depends on its schema library and on `typescript`, which is loaded only when a script is read.
|
package/package.json
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/script",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./api": "./src/script-api.ts"
|
|
9
|
+
},
|
|
10
|
+
"dependencies": {
|
|
11
|
+
"typescript": "~5.9.3",
|
|
12
|
+
"zod": "^4.6.7"
|
|
13
|
+
}
|
|
14
|
+
}
|
package/src/header.ts
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The header of a script, read from its text without running it: the declaration
|
|
3
|
+
* `export default workflow({ ... }, fn)` and the literals written in it. The part of the check that needs no
|
|
4
|
+
* knowledge of the host: `on` is read here (`scriptOn`); the rest of what a script declares is read by the script
|
|
5
|
+
* checker of the workflow package with the same helpers. `typescript` is loaded only when a script is read.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import type * as Ts from "typescript";
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
|
|
11
|
+
/** The script as it is: its path, and the text that was read. */
|
|
12
|
+
export interface ScriptSource {
|
|
13
|
+
file: string;
|
|
14
|
+
text: string;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** The record a script starts on: its type, and the fields the data of the record must hold. */
|
|
18
|
+
export const Subscription = z.object({
|
|
19
|
+
type: z.string().min(1),
|
|
20
|
+
filter: z.record(z.string(), z.unknown()).optional(),
|
|
21
|
+
});
|
|
22
|
+
export type Subscription = z.infer<typeof Subscription>;
|
|
23
|
+
|
|
24
|
+
/** The place of a node in the file, as the checker reports it. */
|
|
25
|
+
export function placeOf(ts: typeof Ts, source: Ts.SourceFile, node: Ts.Node): { line: number; column: number } {
|
|
26
|
+
const at = source.getLineAndCharacterOfPosition(node.getStart(source));
|
|
27
|
+
return { line: at.line + 1, column: at.character + 1 };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** The expression without the `as`, `satisfies` and parentheses around it. */
|
|
31
|
+
export function bare(ts: typeof Ts, expression: Ts.Expression): Ts.Expression {
|
|
32
|
+
let inner = expression;
|
|
33
|
+
while (ts.isAsExpression(inner) || ts.isSatisfiesExpression(inner) || ts.isParenthesizedExpression(inner)) inner = inner.expression;
|
|
34
|
+
return inner;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The declaration of a script: the first argument of `export default workflow(...)`, when the text is that. */
|
|
38
|
+
export type Declaration = { object: Ts.ObjectLiteralExpression } | { opaque: { line: number; column: number } } | undefined;
|
|
39
|
+
|
|
40
|
+
export function declarationOf(ts: typeof Ts, source: Ts.SourceFile): Declaration {
|
|
41
|
+
for (const statement of source.statements) {
|
|
42
|
+
if (!ts.isExportAssignment(statement) || statement.isExportEquals === true) continue;
|
|
43
|
+
const call = bare(ts, statement.expression);
|
|
44
|
+
if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== "workflow") continue;
|
|
45
|
+
const first = call.arguments[0] === undefined ? undefined : bare(ts, call.arguments[0]);
|
|
46
|
+
return first !== undefined && ts.isObjectLiteralExpression(first) ? { object: first } : { opaque: placeOf(ts, source, call) };
|
|
47
|
+
}
|
|
48
|
+
return undefined;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** What the declaration of a script says about one of its keys, read in the order the members are written. */
|
|
52
|
+
export interface DeclaredField {
|
|
53
|
+
/** The value of the last key written under that name, when there is one. */
|
|
54
|
+
value?: Ts.Expression;
|
|
55
|
+
/**
|
|
56
|
+
* What may decide the key where the text does not, written after the last key of that name: a spread, a key
|
|
57
|
+
* computed at run time, or a getter, setter or method that is, or may be, under that name. The node is where the
|
|
58
|
+
* declaration takes it from.
|
|
59
|
+
*/
|
|
60
|
+
unknown?: Ts.Node;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** The name a member is written under, when the text says it. */
|
|
64
|
+
function keyOf(ts: typeof Ts, name: Ts.PropertyName): string | undefined {
|
|
65
|
+
if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name) || ts.isNumericLiteral(name)) return name.text;
|
|
66
|
+
if (ts.isComputedPropertyName(name)) {
|
|
67
|
+
const written = bare(ts, name.expression);
|
|
68
|
+
return ts.isStringLiteral(written) || ts.isNoSubstitutionTemplateLiteral(written) ? written.text : undefined;
|
|
69
|
+
}
|
|
70
|
+
return undefined;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* One key of the declaration of a script, read from the text. The last key of the name wins, as it does when the
|
|
75
|
+
* object is built; a spread, a computed key or an accessor or method that may be under that name, written after it,
|
|
76
|
+
* may replace it, so the text does not settle the value then. A later key of that name written as a property
|
|
77
|
+
* settles it again.
|
|
78
|
+
*/
|
|
79
|
+
export function declaredField(ts: typeof Ts, source: Ts.SourceFile, field: string): DeclaredField | undefined {
|
|
80
|
+
const declaration = declarationOf(ts, source);
|
|
81
|
+
if (declaration === undefined || !("object" in declaration)) return undefined;
|
|
82
|
+
const declared: DeclaredField = {};
|
|
83
|
+
for (const property of declaration.object.properties) {
|
|
84
|
+
if (ts.isSpreadAssignment(property)) {
|
|
85
|
+
declared.unknown = property.expression;
|
|
86
|
+
} else if (ts.isShorthandPropertyAssignment(property)) {
|
|
87
|
+
if (property.name.text === field) {
|
|
88
|
+
declared.value = property.name;
|
|
89
|
+
delete declared.unknown;
|
|
90
|
+
}
|
|
91
|
+
} else if (ts.isPropertyAssignment(property)) {
|
|
92
|
+
const key = keyOf(ts, property.name);
|
|
93
|
+
if (key === field) {
|
|
94
|
+
declared.value = property.initializer;
|
|
95
|
+
delete declared.unknown;
|
|
96
|
+
} else if (key === undefined && ts.isComputedPropertyName(property.name)) {
|
|
97
|
+
declared.unknown = property.name.expression;
|
|
98
|
+
} else if (key === "__proto__" && !ts.isComputedPropertyName(property.name) && declared.value === undefined) {
|
|
99
|
+
// `__proto__: x` sets the prototype, which may hold the key: an own key written before it still wins.
|
|
100
|
+
declared.unknown = property.initializer;
|
|
101
|
+
}
|
|
102
|
+
} else if (ts.isMethodDeclaration(property) || ts.isGetAccessorDeclaration(property) || ts.isSetAccessorDeclaration(property)) {
|
|
103
|
+
// A member that is not a plain value replaces the key of its name, and a computed one may be any name.
|
|
104
|
+
const key = keyOf(ts, property.name);
|
|
105
|
+
if (key === field || (key === undefined && ts.isComputedPropertyName(property.name))) declared.unknown = property.name;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return declared.value === undefined && declared.unknown === undefined ? undefined : declared;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** What the declaration of a script says of one key: the value written, or that the text does not settle it. Absent: no such key. */
|
|
112
|
+
export type DeclarationField = { value: Ts.Expression } | { unsettled: Ts.Node };
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* One key of the declaration of a script, read from the text, in three results: absent (`undefined`), a value the
|
|
116
|
+
* text settles, or a key the text does not settle (a later spread, computed key, accessor or method may decide it).
|
|
117
|
+
* What may replace a key is never given as its value: a reader that takes the value as it reads it would take a
|
|
118
|
+
* spread of a literal for the list the script wrote.
|
|
119
|
+
*/
|
|
120
|
+
export function declarationField(ts: typeof Ts, source: Ts.SourceFile, field: string): DeclarationField | undefined {
|
|
121
|
+
const declared = declaredField(ts, source, field);
|
|
122
|
+
if (declared === undefined) return undefined;
|
|
123
|
+
return declared.unknown !== undefined ? { unsettled: declared.unknown } : declared.value === undefined ? undefined : { value: declared.value };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** A value written as a literal in the text: text, a number, a boolean, null, a list or an object of them. */
|
|
127
|
+
export function literalOf(ts: typeof Ts, node: Ts.Expression): { value: unknown } | undefined {
|
|
128
|
+
const expression = bare(ts, node);
|
|
129
|
+
if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return { value: expression.text };
|
|
130
|
+
if (ts.isNumericLiteral(expression)) return { value: Number(expression.text) };
|
|
131
|
+
if (ts.isPrefixUnaryExpression(expression) && expression.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(expression.operand)) {
|
|
132
|
+
return { value: -Number(expression.operand.text) };
|
|
133
|
+
}
|
|
134
|
+
if (expression.kind === ts.SyntaxKind.TrueKeyword) return { value: true };
|
|
135
|
+
if (expression.kind === ts.SyntaxKind.FalseKeyword) return { value: false };
|
|
136
|
+
if (expression.kind === ts.SyntaxKind.NullKeyword) return { value: null };
|
|
137
|
+
if (ts.isArrayLiteralExpression(expression)) {
|
|
138
|
+
const items: unknown[] = [];
|
|
139
|
+
for (const element of expression.elements) {
|
|
140
|
+
const item = literalOf(ts, element);
|
|
141
|
+
if (item === undefined) return undefined;
|
|
142
|
+
items.push(item.value);
|
|
143
|
+
}
|
|
144
|
+
return { value: items };
|
|
145
|
+
}
|
|
146
|
+
if (ts.isObjectLiteralExpression(expression)) {
|
|
147
|
+
const fields: Record<string, unknown> = {};
|
|
148
|
+
for (const property of expression.properties) {
|
|
149
|
+
if (!ts.isPropertyAssignment(property)) return undefined;
|
|
150
|
+
if (!ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name)) return undefined;
|
|
151
|
+
const item = literalOf(ts, property.initializer);
|
|
152
|
+
if (item === undefined) return undefined;
|
|
153
|
+
fields[property.name.text] = item.value;
|
|
154
|
+
}
|
|
155
|
+
return { value: fields };
|
|
156
|
+
}
|
|
157
|
+
return undefined;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** What `on` holds: the subscriptions, or the place and the reason where it is not a list of them. */
|
|
161
|
+
export type On = { subscriptions: Array<Subscription & { line: number; column: number }> } | { bad: { line: number; column: number; message: string } };
|
|
162
|
+
|
|
163
|
+
/** What the error of a type named in `on` by an expression says. */
|
|
164
|
+
const AS_TEXT = 'the header is read as text: name the type as text, as in on: ["task.done"]; a type imported by reference is for wait and read.records';
|
|
165
|
+
|
|
166
|
+
/** Whether an entry of `on` names its type by an expression, a reference, rather than as text. */
|
|
167
|
+
function namedInCode(ts: typeof Ts, item: Ts.Expression): boolean {
|
|
168
|
+
const reference = (node: Ts.Expression): boolean => {
|
|
169
|
+
const inner = bare(ts, node);
|
|
170
|
+
return ts.isIdentifier(inner) || ts.isPropertyAccessExpression(inner);
|
|
171
|
+
};
|
|
172
|
+
if (!ts.isObjectLiteralExpression(item)) return reference(item);
|
|
173
|
+
return item.properties.some(
|
|
174
|
+
(property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === "type" && reference(property.initializer),
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* `on` of a parsed script: the records that start it, each a type or a type with a filter.
|
|
180
|
+
*
|
|
181
|
+
* Absent when the script declares none. The filter is read from the text as a literal, never by
|
|
182
|
+
* running the script.
|
|
183
|
+
*/
|
|
184
|
+
export function onOf(ts: typeof Ts, source: Ts.SourceFile): On | undefined {
|
|
185
|
+
const declared = declaredField(ts, source, "on");
|
|
186
|
+
if (declared === undefined) return undefined;
|
|
187
|
+
const shape = "on must be a list of record types, or of { type, filter } with the filter written as a literal";
|
|
188
|
+
// Something the text does not settle may decide `on`: report that, never a trigger the script may not have.
|
|
189
|
+
if (declared.unknown !== undefined) {
|
|
190
|
+
return { bad: { ...placeOf(ts, source, declared.unknown), message: "on is not settled by the declaration: a spread or a computed key may decide it. " + shape } };
|
|
191
|
+
}
|
|
192
|
+
const list = bare(ts, declared.value as Ts.Expression);
|
|
193
|
+
if (!ts.isArrayLiteralExpression(list)) return { bad: { ...placeOf(ts, source, list), message: shape } };
|
|
194
|
+
const subscriptions: Array<Subscription & { line: number; column: number }> = [];
|
|
195
|
+
for (const element of list.elements) {
|
|
196
|
+
const where = placeOf(ts, source, element);
|
|
197
|
+
const item = bare(ts, element);
|
|
198
|
+
const written = ts.isStringLiteral(item) || ts.isNoSubstitutionTemplateLiteral(item)
|
|
199
|
+
? { type: item.text }
|
|
200
|
+
: ts.isObjectLiteralExpression(item) ? literalOf(ts, item)?.value : undefined;
|
|
201
|
+
// A bare type and an object are held to the same schema, so an empty type is refused in both.
|
|
202
|
+
const parsed = Subscription.strict().safeParse(written);
|
|
203
|
+
if (!parsed.success) return { bad: { ...where, message: namedInCode(ts, item) ? `${shape}. ${AS_TEXT}` : shape } };
|
|
204
|
+
subscriptions.push({ ...parsed.data, ...where });
|
|
205
|
+
}
|
|
206
|
+
return { subscriptions };
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/** `on` of a script, read from the text without running it; absent when the script has none. */
|
|
210
|
+
export async function scriptOn(source: ScriptSource): Promise<On | undefined> {
|
|
211
|
+
const ts = (await import("typescript")).default;
|
|
212
|
+
return onOf(ts, ts.createSourceFile(source.file, source.text, ts.ScriptTarget.ESNext, true));
|
|
213
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// The script entry: what a workflow script is given (`script-api.ts`: types only, no import) and the reader of its header.
|
|
2
|
+
|
|
3
|
+
export * from "./script-api.ts";
|
|
4
|
+
export * from "./header.ts";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The version of the script ABI: what a script is given and how its module is read. A registered version
|
|
8
|
+
* keeps the one it was registered for, and does not run under another: it is registered again.
|
|
9
|
+
*/
|
|
10
|
+
export const SCRIPT_ABI = 2;
|
|
@@ -0,0 +1,404 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The types a workflow script is given, with no import: the check of a script can load this one file in place of the
|
|
3
|
+
* package entry, so a script that imports `ScriptApi` does not pull the rest of niwa into the type checker.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** A duration as a script writes it: milliseconds, or a text such as "500ms", "30s", "5m", "2h", "1d". */
|
|
7
|
+
export type Duration = number | string;
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* What every call of a script may carry: the label is the key of the call; the reason is why an
|
|
11
|
+
* action is called, shown to the owner when a rule of the script's grant asks.
|
|
12
|
+
*/
|
|
13
|
+
export interface CallOptions {
|
|
14
|
+
label?: string;
|
|
15
|
+
reason?: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** The worktree an `ask({ worktree })` call left: present when the work changed something in it. */
|
|
19
|
+
export interface AskWorktree {
|
|
20
|
+
id: string;
|
|
21
|
+
path: string;
|
|
22
|
+
branch: string;
|
|
23
|
+
changed: boolean;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export type SessionPrompt = string | { sections: { id: string; tier: "constant" | "stable" | "volatile"; text: string }[] };
|
|
27
|
+
export interface ScriptSession {
|
|
28
|
+
readonly id: string;
|
|
29
|
+
readonly ref: string;
|
|
30
|
+
readonly address: { kind: "session"; harness: string; id: string };
|
|
31
|
+
readonly worktree?: Omit<AskWorktree, "changed">;
|
|
32
|
+
ask<S extends import("zod").z.ZodType>(prompt: SessionPrompt, options: { schema: S; label?: string }): Promise<import("zod").z.output<S>>;
|
|
33
|
+
ask(prompt: SessionPrompt, options?: { label?: string }): Promise<{ answer: string }>;
|
|
34
|
+
end(options?: CallOptions): Promise<void>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** One thing a box asks for: a profile by its name, `"project"`, `"toolchains"`, or a path or a host. */
|
|
38
|
+
export type BoxItem = string | { read: string } | { write: string } | { net: string };
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* What an `ask()` call may ask for besides its schema. The options of the harness's kind go in the
|
|
42
|
+
* block named after the kind; the block of another kind is refused. A kind with no option of its own
|
|
43
|
+
* takes an empty block.
|
|
44
|
+
*/
|
|
45
|
+
export interface SessionOptions {
|
|
46
|
+
harness?: string;
|
|
47
|
+
label?: string;
|
|
48
|
+
visible?: string[];
|
|
49
|
+
tools?: "all" | "niwa-only" | { allow: readonly string[] };
|
|
50
|
+
model?: string;
|
|
51
|
+
effort?: string;
|
|
52
|
+
mode?: "ask" | "auto" | "full";
|
|
53
|
+
cwd?: string;
|
|
54
|
+
/** How long a turn of the session may go with no progress before it counts as stuck: kept in the record of the session. */
|
|
55
|
+
stuckAfter?: Duration;
|
|
56
|
+
/** Run the session in a new git worktree; removed at the end when clean with no new commit, else the answer carries `worktree`. */
|
|
57
|
+
worktree?: true | { repo?: string; base?: string; description?: string };
|
|
58
|
+
/**
|
|
59
|
+
* What the session's box has besides the host's default (`allow`) or instead of it (`only`): `"project"`,
|
|
60
|
+
* `"toolchains"`, a profile by its name, `{ read }`, `{ write }`, `{ net }`. Beyond the default takes the run's `box.*` rules.
|
|
61
|
+
*/
|
|
62
|
+
box?: { allow: BoxItem[] } | { only: BoxItem[] };
|
|
63
|
+
/** Claude Code (`claude-code`, `claude-sdk`): `advisor: false` takes its advisor tool away from the session. */
|
|
64
|
+
claude?: { advisor?: boolean };
|
|
65
|
+
codex?: Record<string, never>;
|
|
66
|
+
mcode?: Record<string, never>;
|
|
67
|
+
ncode?: Record<string, never>;
|
|
68
|
+
pi?: Record<string, never>;
|
|
69
|
+
zcode?: Record<string, never>;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** An option of `ask.choice` and `ask.multi`: the id alone, or the id with how it is shown. */
|
|
73
|
+
export type AskOption = string | { id: string; label?: string; description?: string };
|
|
74
|
+
|
|
75
|
+
/** The id of an option: what the script gets back. */
|
|
76
|
+
export type AskOptionId<T> = T extends string ? T : T extends { id: infer I extends string } ? I : never;
|
|
77
|
+
|
|
78
|
+
/** What an `ask.<kind>` call may carry. */
|
|
79
|
+
export interface AskCallOptions {
|
|
80
|
+
timeout?: Duration;
|
|
81
|
+
label?: string;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** A phase of a script: its title, which `phase(title)` names, and a line of what is done in it. */
|
|
85
|
+
export interface WorkflowPhase {
|
|
86
|
+
title: string;
|
|
87
|
+
detail?: string;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** What a script declares besides its schemas and the record it starts on. */
|
|
91
|
+
export interface WorkflowDeclaration {
|
|
92
|
+
name?: string;
|
|
93
|
+
description?: string;
|
|
94
|
+
uses?: string[];
|
|
95
|
+
/** The phases of the script, in order: `phase(title)` enters one, and a run shows which are done, current and ahead. */
|
|
96
|
+
phases?: WorkflowPhase[];
|
|
97
|
+
/** The records the script writes: what `record(name, schema)` gives. */
|
|
98
|
+
emits?: RecordDeclaration[];
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** What the default export of a script is: what `workflow(...)` gives. */
|
|
102
|
+
export interface WorkflowScript {
|
|
103
|
+
readonly niwaWorkflow: true;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** What a function of a script returns: what its `output` says, or nothing when it has none. */
|
|
107
|
+
type WorkflowResult<O extends import("zod").z.ZodType> = [O] extends [never] ? void : import("zod").z.output<O>;
|
|
108
|
+
|
|
109
|
+
/** What `wait()` answers when the record did not come in time. */
|
|
110
|
+
export interface TimedOut {
|
|
111
|
+
timedOut: true;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** What `wait()` answers with: the data of the record, and its position, to wait or read on from. */
|
|
115
|
+
export interface ScriptWaited<D = any> {
|
|
116
|
+
data: D;
|
|
117
|
+
at: number;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* A record type a plugin declares, as a script imports it from the plugin's records entry
|
|
122
|
+
* (`import { TaskDone } from "@niwa-labs/tasks/records"`): a wait or a read that names it gives the
|
|
123
|
+
* data its schema gives. The host refuses one it does not know, or of a version it does not write.
|
|
124
|
+
*/
|
|
125
|
+
export interface ScriptRecordRef<D = unknown> {
|
|
126
|
+
readonly kind: "record";
|
|
127
|
+
readonly name: string;
|
|
128
|
+
readonly version: number;
|
|
129
|
+
readonly schema: { readonly _zod: { readonly output: D } };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** The data of the records of a referenced type. */
|
|
133
|
+
export type ScriptRecordData<R> = R extends { readonly schema: { readonly _zod: { readonly output: infer D } } } ? D : unknown;
|
|
134
|
+
|
|
135
|
+
/** The dotted paths into data: a field, or a field of a field, four levels deep at most. */
|
|
136
|
+
export type ScriptDataPath<D, Depth extends unknown[] = []> = Depth["length"] extends 4
|
|
137
|
+
? never
|
|
138
|
+
: D extends readonly unknown[]
|
|
139
|
+
? never
|
|
140
|
+
: D extends object
|
|
141
|
+
? { [K in keyof D & string]-?: K | `${K}.${ScriptDataPath<NonNullable<D[K]>, [...Depth, 0]>}` }[keyof D & string]
|
|
142
|
+
: never;
|
|
143
|
+
|
|
144
|
+
/** The value at a dotted path into data. */
|
|
145
|
+
export type ScriptDataAt<D, P extends string> = D extends unknown
|
|
146
|
+
? P extends keyof D
|
|
147
|
+
? D[P]
|
|
148
|
+
: P extends `${infer Head}.${infer Rest}`
|
|
149
|
+
? Head extends keyof D
|
|
150
|
+
? ScriptDataAt<NonNullable<D[Head]>, Rest>
|
|
151
|
+
: never
|
|
152
|
+
: never
|
|
153
|
+
: never;
|
|
154
|
+
|
|
155
|
+
/** The filter of a wait or a read of a referenced type: values for fields of its data, by field name or dotted path. */
|
|
156
|
+
export type ScriptFilter<D> = unknown extends D ? Record<string, unknown> : { [P in ScriptDataPath<D>]?: ScriptDataAt<D, P> };
|
|
157
|
+
|
|
158
|
+
/** A query of one referenced type and a filter on its data, as a plugin's query builder gives it (`taskDone(task)`). */
|
|
159
|
+
export interface ScriptTypeQuery<R> {
|
|
160
|
+
readonly types: readonly [R];
|
|
161
|
+
readonly filter?: ScriptFilter<ScriptRecordData<R>>;
|
|
162
|
+
readonly from?: number;
|
|
163
|
+
/** A wait looks at every stream: a query that names one is for a read, not a wait. */
|
|
164
|
+
readonly stream?: undefined;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Which records a script reads or waits for: the types as exact names, families written `prefix.*`
|
|
169
|
+
* or references, equality on paths of the data, a stream, and the position to look after.
|
|
170
|
+
*/
|
|
171
|
+
export interface ScriptRecordQuery {
|
|
172
|
+
from?: number;
|
|
173
|
+
types?: ReadonlyArray<string | ScriptRecordRef<any>>;
|
|
174
|
+
filter?: Record<string, unknown>;
|
|
175
|
+
stream?: string;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** Where a read starts, what stream it reads, and how much. */
|
|
179
|
+
export interface ScriptReadOptions {
|
|
180
|
+
from?: number;
|
|
181
|
+
stream?: string;
|
|
182
|
+
limit?: number;
|
|
183
|
+
tail?: number;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** A record a read answers with: as the journal keeps it, with its data. */
|
|
187
|
+
export interface ScriptStoredRecord<D = any> {
|
|
188
|
+
id: string;
|
|
189
|
+
seq: number;
|
|
190
|
+
stream: string;
|
|
191
|
+
type: string;
|
|
192
|
+
schema: number;
|
|
193
|
+
data: D;
|
|
194
|
+
cause: string | null;
|
|
195
|
+
root: string;
|
|
196
|
+
at: number;
|
|
197
|
+
actor: { kind: string };
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* Whether a list of record types is known to name only referenced types: a tuple of at least one reference. A list that
|
|
202
|
+
* may be empty (a record type list built at run time) selects every type when it is, and one that holds a name
|
|
203
|
+
* written as text has no data type to give.
|
|
204
|
+
*/
|
|
205
|
+
export type ScriptRefsOnly<T extends readonly unknown[]> = T extends readonly [] ? false : number extends T["length"] ? false : T[number] extends ScriptRecordRef<any> ? true : false;
|
|
206
|
+
|
|
207
|
+
/** The filter of a read of a list of record types: by the data of the references when every one is, else by any field. */
|
|
208
|
+
export type ScriptTypesFilter<T extends readonly unknown[]> = ScriptRefsOnly<T> extends true ? ScriptFilter<ScriptRecordData<T[number]>> : Record<string, unknown>;
|
|
209
|
+
|
|
210
|
+
/** A record of one referenced type, with its data typed by it; spread over a union of references, one record type each. */
|
|
211
|
+
export type ScriptRecordOf<R> = R extends unknown ? ScriptStoredRecord<ScriptRecordData<R>> : never;
|
|
212
|
+
|
|
213
|
+
/** The records a read of a list of record types answers with: typed by the references when every type is one, else of data of unknown shape. */
|
|
214
|
+
export type ScriptTypesRecords<T extends readonly unknown[]> = ScriptRefsOnly<T> extends true ? ScriptRecordOf<T[number]> : ScriptStoredRecord<unknown>;
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* What a script is given. The globals are declared in a script with
|
|
218
|
+
* `declare const wait: ScriptApi["wait"]` and so on: a declaration for the whole project would
|
|
219
|
+
* put names like `sleep` and `log` in front of every module. The answers are `any`: they are
|
|
220
|
+
* typed by `workflow.guide`, which generates the declarations of the actions from `describe()`.
|
|
221
|
+
*/
|
|
222
|
+
export interface ScriptApi {
|
|
223
|
+
/** zod, a global of the script: `z.object({ ... })` for `input`, `output` and the schema of `agent`. */
|
|
224
|
+
z: typeof import("zod").z;
|
|
225
|
+
/**
|
|
226
|
+
* The script: `export default workflow({ description, input, output, uses }, async (input) => { ... })`. The function
|
|
227
|
+
* is given `input` parsed (a script with no `input` is given nothing) and returns what `output` says (a script with
|
|
228
|
+
* no `output` returns nothing).
|
|
229
|
+
*/
|
|
230
|
+
workflow<I extends import("zod").z.ZodObject = never, O extends import("zod").z.ZodType = never>(
|
|
231
|
+
declaration: WorkflowDeclaration & { input?: I; output?: O; on?: undefined },
|
|
232
|
+
run: (...input: [I] extends [never] ? [] : [import("zod").z.output<I>]) => Promise<WorkflowResult<O>>,
|
|
233
|
+
): WorkflowScript;
|
|
234
|
+
/** A script that niwa starts on records: `on` lists them, and the function is given the record, of the type the script writes. */
|
|
235
|
+
workflow<Trigger, O extends import("zod").z.ZodType = never>(
|
|
236
|
+
declaration: WorkflowDeclaration & { on: Array<string | { type: string; filter?: Record<string, unknown> }>; input?: undefined; output?: O },
|
|
237
|
+
run: (trigger: Trigger) => Promise<WorkflowResult<O>>,
|
|
238
|
+
): WorkflowScript;
|
|
239
|
+
/** Call any action by name. A finished call is not repeated on a replay. */
|
|
240
|
+
call(name: string, input: unknown, opts?: CallOptions): Promise<any>;
|
|
241
|
+
/** `niwa.task.create(input, { label })` is `call("task.create", input, { label })`; the wrappers are generated. */
|
|
242
|
+
niwa: ActionGroup;
|
|
243
|
+
session(options: SessionOptions): Pick<ScriptSession, "ask" | "end"> & PromiseLike<ScriptSession>;
|
|
244
|
+
agent(name: string): { tell(text: string, options?: CallOptions): Promise<{ message: string }> };
|
|
245
|
+
/**
|
|
246
|
+
* The first record of a type whose data holds every field of `filter`, written after `from` — a
|
|
247
|
+
* position an earlier wait or read answered — or after the wait began: its data and its position.
|
|
248
|
+
* Without a `timeout` it waits for ever; the wait survives a restart of the host.
|
|
249
|
+
*/
|
|
250
|
+
wait<R extends ScriptRecordRef<any>>(
|
|
251
|
+
type: R,
|
|
252
|
+
opts?: { filter?: ScriptFilter<ScriptRecordData<R>>; from?: number; label?: string; timeout?: undefined },
|
|
253
|
+
): Promise<ScriptWaited<ScriptRecordData<R>>>;
|
|
254
|
+
/** The same, or `{ timedOut: true }` at the end of the timeout: options that may hold a `timeout` give both. */
|
|
255
|
+
wait<R extends ScriptRecordRef<any>>(
|
|
256
|
+
type: R,
|
|
257
|
+
opts: { filter?: ScriptFilter<ScriptRecordData<R>>; from?: number; label?: string; timeout?: Duration },
|
|
258
|
+
): Promise<ScriptWaited<ScriptRecordData<R>> | TimedOut>;
|
|
259
|
+
/** The first record that answers a query of one referenced type, as a plugin's query builder gives it: after `from` (the option, else the query's). */
|
|
260
|
+
wait<R extends ScriptRecordRef<any>>(query: ScriptTypeQuery<R>, opts?: { from?: number; label?: string; timeout?: undefined }): Promise<ScriptWaited<ScriptRecordData<R>>>;
|
|
261
|
+
wait<R extends ScriptRecordRef<any>>(query: ScriptTypeQuery<R>, opts: { from?: number; label?: string; timeout?: Duration }): Promise<ScriptWaited<ScriptRecordData<R>> | TimedOut>;
|
|
262
|
+
/** A type named as text: the data is of any shape. */
|
|
263
|
+
wait(type: string, opts?: { filter?: Record<string, unknown>; from?: number; label?: string; timeout?: undefined }): Promise<ScriptWaited>;
|
|
264
|
+
wait(type: string, opts: { filter?: Record<string, unknown>; from?: number; label?: string; timeout?: Duration }): Promise<ScriptWaited | TimedOut>;
|
|
265
|
+
/** Sleep. The wake-up moment is recorded on the first pass: a replay does not sleep from the start. */
|
|
266
|
+
sleep(duration: Duration, opts?: CallOptions): Promise<void>;
|
|
267
|
+
/**
|
|
268
|
+
* Ask a model with ask(options, prompt), or the owner with a named method. Each owner question gives a typed value: `choice` the id picked, `multi` the ids, `confirm` a boolean,
|
|
269
|
+
* `text` a string, `form` what the zod schema parses. A cancel, or no answer within the timeout, throws
|
|
270
|
+
* `AskCancelled` or `AskExpired`, which the script may catch.
|
|
271
|
+
*/
|
|
272
|
+
ask: {
|
|
273
|
+
<S extends import("zod").z.ZodObject | import("zod").z.ZodRecord>(options: SessionOptions & { schema: S; worktree: NonNullable<SessionOptions["worktree"]> }, prompt: SessionPrompt): Promise<import("zod").z.output<S> & { worktree?: AskWorktree }>;
|
|
274
|
+
(options: SessionOptions & { schema?: undefined; worktree: NonNullable<SessionOptions["worktree"]> }, prompt: SessionPrompt): Promise<{ answer: string; worktree?: AskWorktree }>;
|
|
275
|
+
<S extends import("zod").z.ZodType>(options: SessionOptions & { schema: S; worktree?: undefined }, prompt: SessionPrompt): Promise<import("zod").z.output<S>>;
|
|
276
|
+
(options: SessionOptions & { schema?: undefined; worktree?: undefined }, prompt: SessionPrompt): Promise<{ answer: string }>;
|
|
277
|
+
choice<const O extends readonly AskOption[]>(text: string, options: O, opts?: AskCallOptions): Promise<AskOptionId<O[number]>>;
|
|
278
|
+
multi<const O extends readonly AskOption[]>(text: string, options: O, opts?: AskCallOptions): Promise<AskOptionId<O[number]>[]>;
|
|
279
|
+
confirm(text: string, opts?: AskCallOptions): Promise<boolean>;
|
|
280
|
+
text(text: string, opts?: AskCallOptions): Promise<string>;
|
|
281
|
+
form<S extends import("zod").z.ZodType>(text: string, schema: S, opts?: AskCallOptions): Promise<import("zod").z.output<S>>;
|
|
282
|
+
};
|
|
283
|
+
/** Declare a record the script writes: its name, under the script's own `wf.<name>.`, and the zod schema of its data. */
|
|
284
|
+
record<S extends import("zod").z.ZodType>(name: string, schema: S): RecordDeclaration<S>;
|
|
285
|
+
/** Write a record the script lists in `workflow({ emits })`: the data is held to the record's schema. */
|
|
286
|
+
emit<S extends import("zod").z.ZodType>(record: RecordDeclaration<S>, data: import("zod").z.input<S>, opts?: CallOptions): Promise<void>;
|
|
287
|
+
read: {
|
|
288
|
+
/** The state of a plugin, as it was when the script read it. */
|
|
289
|
+
state(plugin: string, opts?: CallOptions): Promise<any>;
|
|
290
|
+
/**
|
|
291
|
+
* The records of a referenced type that answer a query, and the position to read on from:
|
|
292
|
+
* `{ records, next }`. A wait from `next` misses nothing written after the read.
|
|
293
|
+
*/
|
|
294
|
+
records<R extends ScriptRecordRef<any>>(
|
|
295
|
+
type: R,
|
|
296
|
+
query?: ScriptReadOptions & { filter?: ScriptFilter<ScriptRecordData<R>> },
|
|
297
|
+
opts?: CallOptions,
|
|
298
|
+
): Promise<{ records: Array<ScriptStoredRecord<ScriptRecordData<R>>>; next: number }>;
|
|
299
|
+
/**
|
|
300
|
+
* The records of a list of types: names as text, families written `prefix.*` or references. A list of references written
|
|
301
|
+
* out (`[Ping, Pong]`, or the list a plugin's query builder gives) types the filter and the data of each record by its
|
|
302
|
+
* type; any other list, one that may be empty or has a name as text, takes a filter on any field and gives data of unknown shape.
|
|
303
|
+
*/
|
|
304
|
+
records<const T extends ReadonlyArray<string | ScriptRecordRef<any>> = readonly []>(
|
|
305
|
+
query?: ScriptReadOptions & { types?: T; filter?: ScriptTypesFilter<T> },
|
|
306
|
+
opts?: CallOptions,
|
|
307
|
+
): Promise<{ records: Array<ScriptTypesRecords<T>>; next: number }>;
|
|
308
|
+
};
|
|
309
|
+
/** Open a scope: a group of branches that never outlive it. */
|
|
310
|
+
scope<T>(name: string, opts: (ScopeOptions & { deadline?: undefined }) | undefined, fn: (s: Scope) => Promise<T>): Promise<T>;
|
|
311
|
+
/** With a deadline that fails, the scope gives its value or throws `DeadlineExceeded`. */
|
|
312
|
+
scope<T>(name: string, opts: ScopeOptions & { deadline: Duration; onDeadline: "fail" }, fn: (s: Scope) => Promise<T>): Promise<T>;
|
|
313
|
+
/** With a deadline that may skip (the default), the scope past it gives undefined. */
|
|
314
|
+
scope<T>(name: string, opts: ScopeOptions | undefined, fn: (s: Scope) => Promise<T>): Promise<T | undefined>;
|
|
315
|
+
scope<T>(name: string, fn: (s: Scope) => Promise<T>): Promise<T>;
|
|
316
|
+
/** Branches at once, by the index of a list or the keys of an object; a branch that fails cancels the others. */
|
|
317
|
+
parallel<T>(branches: Array<() => T | Promise<T>>, opts?: { concurrency?: number }): Promise<Awaited<T>[]>;
|
|
318
|
+
parallel<B extends Record<string, () => unknown>>(branches: B, opts?: { concurrency?: number }): Promise<{ [K in keyof B]: Awaited<ReturnType<B[K]>> }>;
|
|
319
|
+
stream<K extends string, T>(name: string, branches: Record<K, () => T | Promise<T>>, opts?: { concurrency?: number }): Stream<K, Awaited<T>>;
|
|
320
|
+
/** The first branch to succeed, with its key; the others are cancelled. */
|
|
321
|
+
race<K extends string, T>(name: string, branches: Record<K, () => T | Promise<T>>): Promise<{ key: K; value: Awaited<T> }>;
|
|
322
|
+
/** The block for at most the duration: past it, undefined. */
|
|
323
|
+
moveOnAfter<T>(name: string, duration: Duration, fn: () => Promise<T>): Promise<T | undefined>;
|
|
324
|
+
/** The block for at most the duration: past it, `DeadlineExceeded` is thrown. */
|
|
325
|
+
failAfter<T>(name: string, duration: Duration, fn: () => Promise<T>): Promise<T>;
|
|
326
|
+
/** Stages one after another; each is given what the one before gave, awaited, and the call gives all of them. From two to four stages. */
|
|
327
|
+
pipeline<A, B>(stages: [() => A, (previous: Awaited<A>) => B]): Promise<[Awaited<A>, Awaited<B>]>;
|
|
328
|
+
pipeline<A, B, C>(stages: [() => A, (previous: Awaited<A>) => B, (previous: Awaited<B>) => C]): Promise<[Awaited<A>, Awaited<B>, Awaited<C>]>;
|
|
329
|
+
pipeline<A, B, C, D>(
|
|
330
|
+
stages: [() => A, (previous: Awaited<A>) => B, (previous: Awaited<B>) => C, (previous: Awaited<C>) => D],
|
|
331
|
+
): Promise<[Awaited<A>, Awaited<B>, Awaited<C>, Awaited<D>]>;
|
|
332
|
+
/** Enter a phase the script declares in `workflow({ phases })`: the steps after it belong to it. */
|
|
333
|
+
phase(title: string): void;
|
|
334
|
+
/** A line of the run's output. */
|
|
335
|
+
log(text: string): void;
|
|
336
|
+
/** The clock of the host, recorded: a replay reads the same moment. */
|
|
337
|
+
now(opts?: CallOptions): Promise<number>;
|
|
338
|
+
/** A random number, recorded: a replay reads the same one. */
|
|
339
|
+
random(opts?: CallOptions): Promise<number>;
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/** How a branch ended: its value, or its error by name and message. A cancelled branch is named `Cancelled`. */
|
|
343
|
+
export type Settled<T> = { ok: true; value: T } | { ok: false; error: { name: string; message: string } };
|
|
344
|
+
|
|
345
|
+
/** A branch of a scope: its key, its outcome, and its value, which throws what the branch threw. */
|
|
346
|
+
export interface ScopeBranch<R> {
|
|
347
|
+
readonly key: string;
|
|
348
|
+
settled(): Promise<Settled<R>>;
|
|
349
|
+
value(): Promise<R>;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/** What a scope takes: how many branches run at once, what leaving it does, its deadline, and whether it is a shield. */
|
|
353
|
+
export interface ScopeOptions {
|
|
354
|
+
concurrency?: number;
|
|
355
|
+
/** Leaving the block normally waits for the branches left (the default) or cancels them. A block that throws cancels them. */
|
|
356
|
+
onExit?: "wait" | "cancel";
|
|
357
|
+
/** Past it the scope is cancelled; `onDeadline` says whether the call gives undefined or throws `DeadlineExceeded`. */
|
|
358
|
+
deadline?: Duration;
|
|
359
|
+
onDeadline?: "skip" | "fail";
|
|
360
|
+
/** An outer cancel waits for the block to end; the owner can still stop it by force. */
|
|
361
|
+
shield?: boolean;
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
/**
|
|
365
|
+
* A group of branches of structured concurrency. Nothing started in it outlives it; the host keeps
|
|
366
|
+
* its branches, their outcomes and the order they were committed in, so a replay reads them in the
|
|
367
|
+
* order the script read them.
|
|
368
|
+
*/
|
|
369
|
+
export interface Scope {
|
|
370
|
+
readonly path: string[];
|
|
371
|
+
start<R>(key: string, fn: () => R | Promise<R>): ScopeBranch<Awaited<R>>;
|
|
372
|
+
/** A branch that is a run of a registered workflow, a child of this run. */
|
|
373
|
+
run<R = unknown>(key: string, child: { id: string; version?: string; args?: unknown }): ScopeBranch<R>;
|
|
374
|
+
/** The next outcome after the ones read, or null when every branch ended and was read. */
|
|
375
|
+
next(): Promise<{ key: string; result: Settled<unknown> } | null>;
|
|
376
|
+
ready(): Promise<Array<{ key: string; result: Settled<unknown> }>>;
|
|
377
|
+
rest(): Promise<Record<string, Settled<unknown>>>;
|
|
378
|
+
pending(): Promise<string[]>;
|
|
379
|
+
cancel(reason?: string, keys?: string[]): Promise<void>;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
/** A stream of branches: their outcomes one at a time, in the order the host committed them. Closing it cancels the rest. */
|
|
383
|
+
export interface Stream<K extends string, T> extends AsyncIterable<{ key: K; result: Settled<T> }> {
|
|
384
|
+
next(): Promise<{ key: K; result: Settled<T> } | null>;
|
|
385
|
+
ready(): Promise<Array<{ key: K; result: Settled<T> }>>;
|
|
386
|
+
rest(): Promise<Record<K, Settled<T>>>;
|
|
387
|
+
pending(): Promise<K[]>;
|
|
388
|
+
cancel(keys?: K[]): Promise<void>;
|
|
389
|
+
close(): Promise<void>;
|
|
390
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/** What `record(name, schema)` gives: a record a script lists in `workflow({ emits })` and writes with `emit`. */
|
|
394
|
+
export interface RecordDeclaration<S extends import("zod").z.ZodType = import("zod").z.ZodType> {
|
|
395
|
+
readonly niwaRecord: true;
|
|
396
|
+
readonly name: string;
|
|
397
|
+
readonly schema: S;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
/** `niwa.task` is a group, `niwa.task.create` an action: any depth, the name is the path. */
|
|
401
|
+
export interface ActionGroup {
|
|
402
|
+
(input?: unknown, opts?: CallOptions): Promise<any>;
|
|
403
|
+
[name: string]: any;
|
|
404
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// The script package takes nothing from niwa: its types import nothing, and its header reader only zod and typescript.
|
|
2
|
+
|
|
3
|
+
import { readFileSync, readdirSync } from "node:fs";
|
|
4
|
+
import { join, relative } from "node:path";
|
|
5
|
+
|
|
6
|
+
import { expect, test } from "bun:test";
|
|
7
|
+
|
|
8
|
+
const SRC = join(import.meta.dir, "../src");
|
|
9
|
+
|
|
10
|
+
const STATEMENT = /^(?:import|export)(?:\s+type)?\b[^;]*?\bfrom\s*"([^"]+)"/gm;
|
|
11
|
+
|
|
12
|
+
/** Every module specifier a file names in an import or re-export statement. */
|
|
13
|
+
function specifiersOf(file: string): string[] {
|
|
14
|
+
return [...readFileSync(file, "utf8").matchAll(STATEMENT)].map((match) => match[1] as string);
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
test("the script API file imports nothing", () => {
|
|
18
|
+
expect(specifiersOf(join(SRC, "script-api.ts"))).toEqual([]);
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
test("the files of the package name only zod, typescript and each other", () => {
|
|
22
|
+
for (const name of readdirSync(SRC).filter((entry) => entry.endsWith(".ts"))) {
|
|
23
|
+
const file = join(SRC, name);
|
|
24
|
+
for (const specifier of specifiersOf(file)) {
|
|
25
|
+
const ok = specifier === "zod" || specifier === "typescript" || /^\.\/[a-z-]+\.ts$/.test(specifier);
|
|
26
|
+
expect({ file: relative(SRC, file), specifier, ok }).toEqual({ file: relative(SRC, file), specifier, ok: true });
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
});
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
// The types of the script API as a script meets them: snippets are type-checked against `src/script-api.ts`, and a call
|
|
2
|
+
// that the host would answer differently from what its type says is an error, not a value the script may misuse.
|
|
3
|
+
|
|
4
|
+
import { join } from "node:path";
|
|
5
|
+
|
|
6
|
+
import { expect, test } from "bun:test";
|
|
7
|
+
import ts from "typescript";
|
|
8
|
+
|
|
9
|
+
const FILE = join(import.meta.dir, "snippet.ts");
|
|
10
|
+
|
|
11
|
+
const PREFACE = [
|
|
12
|
+
'import type { ScriptApi, ScriptRecordRef, ScriptTypeQuery } from "../src/script-api.ts";',
|
|
13
|
+
'import { z } from "zod";',
|
|
14
|
+
"declare const api: ScriptApi;",
|
|
15
|
+
"declare const Ping: ScriptRecordRef<{ count: number; id: string }>;",
|
|
16
|
+
"declare const Pong: ScriptRecordRef<{ ok: boolean }>;",
|
|
17
|
+
];
|
|
18
|
+
|
|
19
|
+
/** The type errors of a snippet of a script, by the text of the first line of each. */
|
|
20
|
+
function errorsOf(lines: readonly string[]): string[] {
|
|
21
|
+
// A `declare const` of a snippet is a name given to the script: it stands outside the function.
|
|
22
|
+
const given = lines.filter((line) => line.startsWith(" declare const ")).map((line) => line.trim());
|
|
23
|
+
const body = lines.filter((line) => !line.startsWith(" declare const "));
|
|
24
|
+
const text = [...PREFACE, ...given, "export async function main() {", ...body, "}"].join("\n");
|
|
25
|
+
const before = PREFACE.length + given.length + 1;
|
|
26
|
+
const options: ts.CompilerOptions = {
|
|
27
|
+
target: ts.ScriptTarget.ESNext,
|
|
28
|
+
module: ts.ModuleKind.ESNext,
|
|
29
|
+
moduleResolution: ts.ModuleResolutionKind.Bundler,
|
|
30
|
+
lib: ["lib.esnext.d.ts"],
|
|
31
|
+
strict: true,
|
|
32
|
+
noEmit: true,
|
|
33
|
+
skipLibCheck: true,
|
|
34
|
+
types: [],
|
|
35
|
+
allowImportingTsExtensions: true,
|
|
36
|
+
};
|
|
37
|
+
const host = ts.createCompilerHost(options);
|
|
38
|
+
const read = host.readFile.bind(host);
|
|
39
|
+
const exists = host.fileExists.bind(host);
|
|
40
|
+
const source = host.getSourceFile.bind(host);
|
|
41
|
+
host.readFile = (name) => (name === FILE ? text : read(name));
|
|
42
|
+
host.fileExists = (name) => name === FILE || exists(name);
|
|
43
|
+
host.getSourceFile = (name, language, ...rest) => (name === FILE ? ts.createSourceFile(name, text, language, true) : source(name, language, ...rest));
|
|
44
|
+
const program = ts.createProgram([FILE], options, host);
|
|
45
|
+
return ts
|
|
46
|
+
.getPreEmitDiagnostics(program, program.getSourceFile(FILE))
|
|
47
|
+
.map((diagnostic) => `${String(ts.getLineAndCharacterOfPosition(diagnostic.file as ts.SourceFile, diagnostic.start as number).line + 1 - before)}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, " ").slice(0, 120)}`);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
test("a wait whose options may hold a timeout may answer that it timed out", () => {
|
|
51
|
+
expect(errorsOf([" const opts = { from: 1, timeout: 10 };", " const got = await api.wait(Ping, opts);", " const count: number = got.data.count;"]).length).toBeGreaterThan(0);
|
|
52
|
+
expect(errorsOf([" declare const opts: { timeout?: string };", " const got = await api.wait(Ping, opts);", " const at: number = got.at;"]).length).toBeGreaterThan(0);
|
|
53
|
+
expect(errorsOf([" declare const opts: { timeout: number };", ' const got = await api.wait("a.b", opts);', " const at: number = got.at;"]).length).toBeGreaterThan(0);
|
|
54
|
+
expect(errorsOf([" declare const opts: { timeout: number };", " declare const query: ScriptTypeQuery<typeof Ping>;", " const got = await api.wait(query, opts);", " const at: number = got.at;"]).length).toBeGreaterThan(0);
|
|
55
|
+
expect(
|
|
56
|
+
errorsOf([" declare const opts: { from: number; timeout: number };", " const got = await api.wait(Ping, opts);", ' if ("timedOut" in got) return;', " const count: number = got.data.count;"]),
|
|
57
|
+
).toEqual([]);
|
|
58
|
+
// Options with no timeout, written out or in a variable, answer the record.
|
|
59
|
+
expect(errorsOf([" declare const opts: { from: number };", " const got = await api.wait(Ping, opts);", " const count: number = got.data.count;", " const again = await api.wait(Ping, { filter: { id: 'x' } });", " const id: string = again.data.id;"])).toEqual([]);
|
|
60
|
+
expect(errorsOf([" const got = await api.wait(Ping, { timeout: '1m' });", ' if ("timedOut" in got) return;', " const count: number = got.data.count;"])).toEqual([]);
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
test("a wait takes a query of one type that names no stream, as a read does", () => {
|
|
64
|
+
expect(errorsOf([" const query = { types: [Ping] as const, stream: 's' };", " await api.wait(query);"]).length).toBeGreaterThan(0);
|
|
65
|
+
expect(errorsOf([" const query = { types: [Ping] as const, from: 3 };", " await api.wait(query);"])).toEqual([]);
|
|
66
|
+
expect(errorsOf([" const query = { types: [Ping] as const, stream: 's' };", " await api.read.records(query);"])).toEqual([]);
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
test("a scope with a deadline gives undefined past it unless it is told to throw", () => {
|
|
70
|
+
const number = (opts: string) => errorsOf([` const n: number = await api.scope("a", ${opts}, async () => 1);`]);
|
|
71
|
+
expect(number("{ deadline: 1 }").length).toBeGreaterThan(0);
|
|
72
|
+
expect(number('{ deadline: 1, onDeadline: "skip" }').length).toBeGreaterThan(0);
|
|
73
|
+
expect(number("{ concurrency: 2, deadline: 1 }").length).toBeGreaterThan(0);
|
|
74
|
+
expect(errorsOf([' declare const opts: import("../src/script-api.ts").ScopeOptions;', ' const n: number = await api.scope("a", opts, async () => 1);']).length).toBeGreaterThan(0);
|
|
75
|
+
expect(number('{ deadline: 1, onDeadline: "fail" }')).toEqual([]);
|
|
76
|
+
expect(number("{ concurrency: 2 }")).toEqual([]);
|
|
77
|
+
expect(number("undefined")).toEqual([]);
|
|
78
|
+
expect(errorsOf([' const n: number = await api.scope("a", async () => 1);'])).toEqual([]);
|
|
79
|
+
expect(errorsOf([' const n: number | undefined = await api.scope("a", { deadline: 1 }, async () => 1);'])).toEqual([]);
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
test("a read of a list that may be empty gives data of unknown shape, and one of references written out gives theirs", () => {
|
|
83
|
+
expect(errorsOf([" declare const refs: (typeof Ping)[];", " const { records } = await api.read.records({ types: refs });", " const count: number = records[0]!.data.count;"]).length).toBeGreaterThan(0);
|
|
84
|
+
expect(errorsOf([" const { records } = await api.read.records({ types: [] });", " const count: number = records[0]!.data.count;"]).length).toBeGreaterThan(0);
|
|
85
|
+
expect(errorsOf([' const { records } = await api.read.records({ types: [Ping, "other.*"] });', " const count: number = records[0]!.data.count;"]).length).toBeGreaterThan(0);
|
|
86
|
+
expect(errorsOf([" const { records } = await api.read.records({ types: [Ping] });", " const count: number = records[0]!.data.count;"])).toEqual([]);
|
|
87
|
+
expect(errorsOf([" const { records } = await api.read.records({ types: [Ping, Pong] });", ' for (const row of records) if ("count" in row.data) { const n: number = row.data.count; }'])).toEqual([]);
|
|
88
|
+
expect(errorsOf([" declare const refs: (typeof Ping)[];", " await api.read.records({ types: refs, filter: { anything: 1 } });", ' await api.read.records({ types: ["a.*"], filter: { anything: 1 } });', " await api.read.records();"])).toEqual([]);
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
test("a filter of a read of references is held to their data, and is not let through by another overload", () => {
|
|
92
|
+
expect(errorsOf([' await api.read.records({ types: [Ping], filter: { count: "no" } });']).length).toBeGreaterThan(0);
|
|
93
|
+
expect(errorsOf([" await api.read.records({ types: [Ping], filter: { nothing: 1 } });"]).length).toBeGreaterThan(0);
|
|
94
|
+
expect(errorsOf([' await api.read.records(Ping, { filter: { count: "no" } });']).length).toBeGreaterThan(0);
|
|
95
|
+
expect(errorsOf([" await api.read.records({ types: [Ping], filter: { count: 1 } });", ' await api.read.records({ types: [Ping, Pong], filter: { id: "a" } });'])).toEqual([]);
|
|
96
|
+
});
|
|
97
|
+
|
|
98
|
+
test("an agent call with a worktree answers an object, so the worktree can ride along", () => {
|
|
99
|
+
expect(errorsOf([" await api.ask({ worktree: true, schema: z.string() }, 'go');"]).length).toBeGreaterThan(0);
|
|
100
|
+
expect(errorsOf([" declare const opts: { worktree: true; schema: z.ZodString };", " await api.ask(opts, 'go');"]).length).toBeGreaterThan(0);
|
|
101
|
+
expect(
|
|
102
|
+
errorsOf([
|
|
103
|
+
" const done = await api.ask({ worktree: true, schema: z.object({ ok: z.boolean() }) }, 'go');",
|
|
104
|
+
" const ok: boolean = done.ok;",
|
|
105
|
+
" const path: string | undefined = done.worktree?.path;",
|
|
106
|
+
" const text = await api.ask({ schema: z.string() }, 'go');",
|
|
107
|
+
" const s: string = text;",
|
|
108
|
+
" const answer = await api.ask({ worktree: { base: 'main' } }, 'go');",
|
|
109
|
+
" const a: string = answer.answer;",
|
|
110
|
+
]),
|
|
111
|
+
).toEqual([]);
|
|
112
|
+
});
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// The header of a script, read from its text: `on` is what starts it, and where the text does not say, the
|
|
2
|
+
// reader says so instead of naming a trigger the script may not have.
|
|
3
|
+
|
|
4
|
+
import { expect, test } from "bun:test";
|
|
5
|
+
|
|
6
|
+
import { declarationField, scriptOn } from "../src/index.ts";
|
|
7
|
+
|
|
8
|
+
const read = (declaration: string, preface = "") =>
|
|
9
|
+
scriptOn({ file: "script.ts", text: `${preface}\nexport default workflow(${declaration}, async () => {});` });
|
|
10
|
+
|
|
11
|
+
test("on written in the declaration is read as it is, the last key of that name winning", async () => {
|
|
12
|
+
expect(await read('{ on: ["a.b"] }')).toMatchObject({ subscriptions: [{ type: "a.b" }] });
|
|
13
|
+
expect(await read('{ on: ["a.b"], on: ["c.d"] }')).toMatchObject({ subscriptions: [{ type: "c.d" }] });
|
|
14
|
+
expect(await read('{ ...base, on: ["a.b"] }', "const base = {};")).toMatchObject({ subscriptions: [{ type: "a.b" }] });
|
|
15
|
+
expect(await read('{ description: "none" }')).toBeUndefined();
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
test("on that a spread may replace, or that is only a name, is reported as unreadable, not as a trigger", async () => {
|
|
19
|
+
for (const declaration of [
|
|
20
|
+
'{ on: ["a.b"], ...other }',
|
|
21
|
+
'{ on: ["a.b"], ...{ on: ["c.d"] } }',
|
|
22
|
+
'{ on: ["a.b"], [key]: 1 }',
|
|
23
|
+
"{ on }",
|
|
24
|
+
'{ on: ["a.b"], on }',
|
|
25
|
+
"{ ...other }",
|
|
26
|
+
]) {
|
|
27
|
+
const parsed = await read(declaration, "const other = {}, key = 'on', on = ['c.d'];");
|
|
28
|
+
expect({ declaration, parsed }).toMatchObject({ parsed: { bad: { message: expect.stringContaining("on ") } } });
|
|
29
|
+
}
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
test("an empty record type is refused whether it is written bare or in an object", async () => {
|
|
33
|
+
expect(await read("{ on: [''] }")).toHaveProperty("bad");
|
|
34
|
+
expect(await read("{ on: [{ type: '' }] }")).toHaveProperty("bad");
|
|
35
|
+
expect(await read("{ on: ['a', ''] }")).toHaveProperty("bad");
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
test("on that a getter, a setter or a method may decide is unreadable, and a later plain key settles it again", async () => {
|
|
39
|
+
const preface = "const key = 'on';";
|
|
40
|
+
for (const declaration of [
|
|
41
|
+
'get on() { return ["c.d"]; }',
|
|
42
|
+
'on: ["a.b"], get on() { return ["c.d"]; }',
|
|
43
|
+
'on: ["a.b"], set on(value) {}',
|
|
44
|
+
'on: ["a.b"], on() { return 1; }',
|
|
45
|
+
'on: ["a.b"], get [key]() { return ["c.d"]; }',
|
|
46
|
+
'on: ["a.b"], [key]() { return 1; }',
|
|
47
|
+
"__proto__: other",
|
|
48
|
+
]) {
|
|
49
|
+
const parsed = await read(`{ ${declaration} }`, `${preface} const other = { on: ["c.d"] };`);
|
|
50
|
+
expect({ declaration, parsed }).toMatchObject({ parsed: { bad: { message: expect.stringContaining("on ") } } });
|
|
51
|
+
}
|
|
52
|
+
expect(await read('{ get on() { return ["c.d"]; }, on: ["a.b"] }')).toMatchObject({ subscriptions: [{ type: "a.b" }] });
|
|
53
|
+
// An accessor under another name decides nothing about `on`, and an own key before `__proto__` wins over it.
|
|
54
|
+
expect(await read('{ on: ["a.b"], get name() { return "x"; }, run() {} }')).toMatchObject({ subscriptions: [{ type: "a.b" }] });
|
|
55
|
+
expect(await read('{ on: ["a.b"], __proto__: {} }')).toMatchObject({ subscriptions: [{ type: "a.b" }] });
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
test("a key of the declaration reads as absent, a value or unsettled, and what may replace it is never its value", async () => {
|
|
59
|
+
const ts = (await import("typescript")).default;
|
|
60
|
+
const field = (declaration: string, name: string) =>
|
|
61
|
+
declarationField(ts, ts.createSourceFile("s.ts", `const base = {};\nexport default workflow(${declaration}, async () => {});`, ts.ScriptTarget.ESNext, true), name);
|
|
62
|
+
expect(field("{ description: 'x' }", "uses")).toBeUndefined();
|
|
63
|
+
expect(field("{ uses: ['a'] }", "uses")).toHaveProperty("value");
|
|
64
|
+
expect(field("{ ...base }", "uses")).toHaveProperty("unsettled");
|
|
65
|
+
expect(field("{ uses: ['a'], ...base }", "uses")).toHaveProperty("unsettled");
|
|
66
|
+
// A spread of a literal list is not the list the script wrote.
|
|
67
|
+
expect(field("{ ...['x'] }", "uses")).toHaveProperty("unsettled");
|
|
68
|
+
expect(field("{ ...base, uses: ['a'] }", "uses")).toHaveProperty("value");
|
|
69
|
+
expect(field("{ get uses() { return []; } }", "uses")).toHaveProperty("unsettled");
|
|
70
|
+
});
|