@happyvertical/smrt-workflows 0.0.0-stage → 0.62.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/AGENTS.md +33 -0
- package/CLAUDE.md +1 -0
- package/LICENSE +7 -0
- package/README.md +119 -2
- package/agents/workflow-runs.md +125 -0
- package/dist/checkpoint-store.d.ts +61 -0
- package/dist/checkpoint-store.d.ts.map +1 -0
- package/dist/claim-fence.d.ts +25 -0
- package/dist/claim-fence.d.ts.map +1 -0
- package/dist/driver.d.ts +154 -0
- package/dist/driver.d.ts.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1136 -0
- package/dist/index.js.map +1 -0
- package/dist/jobs.d.ts +121 -0
- package/dist/jobs.d.ts.map +1 -0
- package/dist/manifest.json +15 -0
- package/dist/smrt-knowledge.json +88 -0
- package/dist/smrt-knowledge.okf.md +51 -0
- package/dist/types.d.ts +216 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +7 -0
- package/dist/types.js.map +1 -0
- package/package.json +60 -3
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
import type { AiRunBudget, AiRunContext, AiRunStatus, AiRunStopDetail, AiRunStopReason } from '@happyvertical/smrt-core';
|
|
2
|
+
/** The run type every workflow run carries (docs/content/ai-runs.md). */
|
|
3
|
+
export declare const WORKFLOW_RUN_TYPE = "workflow";
|
|
4
|
+
/** Version of {@link WorkflowCheckpointState}'s own shape. */
|
|
5
|
+
export declare const WORKFLOW_STATE_VERSION = 1;
|
|
6
|
+
/**
|
|
7
|
+
* What a workflow run keeps in its checkpoint (the run type owns this
|
|
8
|
+
* state; core wraps it in a versioned envelope): the step it is on, the
|
|
9
|
+
* repair count, and the accepted outputs of the completed steps. Totals,
|
|
10
|
+
* tokens and attempts are never here: the usage rows and events are the
|
|
11
|
+
* record.
|
|
12
|
+
*/
|
|
13
|
+
export interface WorkflowCheckpointState {
|
|
14
|
+
v: typeof WORKFLOW_STATE_VERSION;
|
|
15
|
+
/** Zero-based index of the step the run is on. */
|
|
16
|
+
stepIndex: number;
|
|
17
|
+
/** `call`: the step's model call is next; `check`: its accepted output awaits the host check. */
|
|
18
|
+
phase: 'call' | 'check';
|
|
19
|
+
/** Repairs used on the current step (attempt = repairs + 1). */
|
|
20
|
+
repairs: number;
|
|
21
|
+
/** Times the host check asked to run the current step again. */
|
|
22
|
+
repeats: number;
|
|
23
|
+
/** The run input, when small enough to keep inline. */
|
|
24
|
+
input: unknown;
|
|
25
|
+
/** A pointer at input the host stores (large input passes by reference). */
|
|
26
|
+
inputRef: string | null;
|
|
27
|
+
/** Accepted outputs of the completed steps, by step index. */
|
|
28
|
+
outputs: unknown[];
|
|
29
|
+
/** The current step's accepted output, awaiting its check. */
|
|
30
|
+
pending: {
|
|
31
|
+
output: unknown;
|
|
32
|
+
judgedEventId: string | null;
|
|
33
|
+
} | null;
|
|
34
|
+
/** The current step's last invalid output, for the repair attempt. */
|
|
35
|
+
invalid: {
|
|
36
|
+
output: unknown;
|
|
37
|
+
errors: string[];
|
|
38
|
+
} | null;
|
|
39
|
+
/** The approval (hold) requested for the pending output and not yet decided. */
|
|
40
|
+
approval: {
|
|
41
|
+
requestEventId: string;
|
|
42
|
+
} | null;
|
|
43
|
+
/**
|
|
44
|
+
* Holds of the current step a person approved so far. A step may hold
|
|
45
|
+
* more than once (one hold per gated action); it passes only when its
|
|
46
|
+
* check passes with no hold outstanding. Absent in older checkpoints: 0.
|
|
47
|
+
*/
|
|
48
|
+
approvals?: number;
|
|
49
|
+
}
|
|
50
|
+
/** Host-facing progress; names are the host's plain text. */
|
|
51
|
+
export interface RunProgress {
|
|
52
|
+
runId: string;
|
|
53
|
+
/** One-based step position and the step's name. */
|
|
54
|
+
step: {
|
|
55
|
+
index: number;
|
|
56
|
+
count: number;
|
|
57
|
+
name: string;
|
|
58
|
+
};
|
|
59
|
+
status: AiRunStatus;
|
|
60
|
+
stopReason: AiRunStopReason | null;
|
|
61
|
+
phase: WorkflowCheckpointState['phase'];
|
|
62
|
+
}
|
|
63
|
+
/** What a host check decides about a step's accepted output. */
|
|
64
|
+
export interface WorkflowStepCheck {
|
|
65
|
+
/** Facts for the next step: replaces the run input. */
|
|
66
|
+
input?: unknown;
|
|
67
|
+
/**
|
|
68
|
+
* The host finished the work at this step (it applied the accepted
|
|
69
|
+
* output); the run ends `done` here without running later steps.
|
|
70
|
+
*/
|
|
71
|
+
complete?: boolean;
|
|
72
|
+
/**
|
|
73
|
+
* A definitive rejection: the run ends `failed` with `check_failed`. A
|
|
74
|
+
* safe, host-authored explanation; never model output or error text.
|
|
75
|
+
*/
|
|
76
|
+
failure?: string;
|
|
77
|
+
/** Run this step again (a new step instance), up to `maxRepeats`. */
|
|
78
|
+
repeat?: boolean;
|
|
79
|
+
/**
|
|
80
|
+
* Pause for a person's decision (durable runs only). Every time a check
|
|
81
|
+
* returns it, a new hold is requested (an `approval` event): a check that
|
|
82
|
+
* holds again after an approval waits again, and the step passes only once
|
|
83
|
+
* its check returns without it.
|
|
84
|
+
*/
|
|
85
|
+
waitingApproval?: boolean;
|
|
86
|
+
/**
|
|
87
|
+
* What the hold points at in the host (`payload_ref` of the `approval`
|
|
88
|
+
* request, e.g. `approval:<id>`), for mapping a host decision to the run.
|
|
89
|
+
*/
|
|
90
|
+
holdRef?: string;
|
|
91
|
+
/** A short host note recorded on the check or approval event. */
|
|
92
|
+
note?: string;
|
|
93
|
+
}
|
|
94
|
+
/** What a step's call or check sees. */
|
|
95
|
+
export interface WorkflowStepContext {
|
|
96
|
+
runId: string;
|
|
97
|
+
step: {
|
|
98
|
+
index: number;
|
|
99
|
+
count: number;
|
|
100
|
+
name: string;
|
|
101
|
+
};
|
|
102
|
+
/** The run input (resolved from `inputRef` when passed by reference). */
|
|
103
|
+
input: unknown;
|
|
104
|
+
/** Accepted outputs of the completed steps. */
|
|
105
|
+
outputs: readonly unknown[];
|
|
106
|
+
/** 1 for the first try, 2 for the first repair, ... */
|
|
107
|
+
attempt: number;
|
|
108
|
+
/** The previous attempt's invalid output and its errors. */
|
|
109
|
+
repair: {
|
|
110
|
+
output: unknown;
|
|
111
|
+
errors: readonly string[];
|
|
112
|
+
} | null;
|
|
113
|
+
signal: AbortSignal;
|
|
114
|
+
}
|
|
115
|
+
/** What a step's check sees. */
|
|
116
|
+
export interface WorkflowCheckContext extends WorkflowStepContext {
|
|
117
|
+
/**
|
|
118
|
+
* `approved` when the check runs again after a person approved the step's
|
|
119
|
+
* latest hold; null otherwise. Asking for approval again requests a new
|
|
120
|
+
* hold: it is never taken as passed.
|
|
121
|
+
*/
|
|
122
|
+
approval: 'approved' | null;
|
|
123
|
+
/** Holds of this step a person approved so far. */
|
|
124
|
+
approvals: number;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* A step's own execution, replacing the default prompt call (a CLI engine,
|
|
128
|
+
* say). It must send every model call it makes with `runContext`, so each
|
|
129
|
+
* call is reserved, recorded and settled in this run, and return the step's
|
|
130
|
+
* output (an object, or JSON text).
|
|
131
|
+
*/
|
|
132
|
+
export type WorkflowStepExecute = (request: WorkflowStepContext & {
|
|
133
|
+
runContext: AiRunContext;
|
|
134
|
+
}) => Promise<unknown>;
|
|
135
|
+
/**
|
|
136
|
+
* One host-defined stage of a workflow. Model output cannot change it. By
|
|
137
|
+
* default its call resolves the registered prompt `promptKey` through
|
|
138
|
+
* `resolvePrompt` and sends it on the tracked client; the output must pass
|
|
139
|
+
* `schema` (the host's full validator) and then the host `check`.
|
|
140
|
+
*/
|
|
141
|
+
export interface WorkflowStep {
|
|
142
|
+
name: string;
|
|
143
|
+
/** The registered prompt this step's call uses. */
|
|
144
|
+
promptKey: string;
|
|
145
|
+
schema: Record<string, unknown>;
|
|
146
|
+
/**
|
|
147
|
+
* The prompt's variables. Default: `input`, `outputs`, `schema`,
|
|
148
|
+
* `repairOutput` and `repairErrors` as JSON or plain text.
|
|
149
|
+
*/
|
|
150
|
+
variables?: (context: WorkflowStepContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
|
|
151
|
+
/** Deterministic and safe to repeat: recovery may replay it. */
|
|
152
|
+
check?: (output: unknown, context: WorkflowCheckContext) => WorkflowStepCheck | Promise<WorkflowStepCheck>;
|
|
153
|
+
/** How many times the check may ask to repeat this step (default 0). */
|
|
154
|
+
maxRepeats?: number;
|
|
155
|
+
/** The output allowance a call of this step is reserved with. */
|
|
156
|
+
expectedOutputTokens?: number;
|
|
157
|
+
execute?: WorkflowStepExecute;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* A versioned list of steps (one workflow definition). A run resumes only
|
|
161
|
+
* under the version that saved its checkpoint, unless this version declares
|
|
162
|
+
* it accepts older checkpoints and validates or migrates them.
|
|
163
|
+
*/
|
|
164
|
+
export interface WorkflowDefinition {
|
|
165
|
+
key: string;
|
|
166
|
+
version: string;
|
|
167
|
+
steps: readonly WorkflowStep[];
|
|
168
|
+
olderCheckpoints?: {
|
|
169
|
+
/** Whether a checkpoint saved by `version` is accepted. */
|
|
170
|
+
accepts(version: string | null): boolean;
|
|
171
|
+
/**
|
|
172
|
+
* Validate an accepted older checkpoint's state and return it in this
|
|
173
|
+
* version's shape; throw to refuse it (the run then stops with
|
|
174
|
+
* `definition_changed`).
|
|
175
|
+
*/
|
|
176
|
+
migrate(state: WorkflowCheckpointState, version: string | null): WorkflowCheckpointState;
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
/** A workflow run as the host sees it. */
|
|
180
|
+
export interface WorkflowRunState {
|
|
181
|
+
id: string;
|
|
182
|
+
ownerId: string | null;
|
|
183
|
+
tenantId: string | null;
|
|
184
|
+
definitionKey: string | null;
|
|
185
|
+
definitionVersion: string | null;
|
|
186
|
+
status: AiRunStatus;
|
|
187
|
+
stopReason: AiRunStopReason | null;
|
|
188
|
+
stoppedByRunId: string | null;
|
|
189
|
+
stopDetail: AiRunStopDetail | null;
|
|
190
|
+
retryOfRunId: string | null;
|
|
191
|
+
budget: AiRunBudget;
|
|
192
|
+
/** The checkpoint revision this snapshot was read at. */
|
|
193
|
+
revision: number;
|
|
194
|
+
step: {
|
|
195
|
+
index: number;
|
|
196
|
+
count: number;
|
|
197
|
+
name: string;
|
|
198
|
+
};
|
|
199
|
+
phase: WorkflowCheckpointState['phase'];
|
|
200
|
+
input: unknown;
|
|
201
|
+
inputRef: string | null;
|
|
202
|
+
outputs: unknown[];
|
|
203
|
+
/** The current step's accepted output awaiting its check or approval. */
|
|
204
|
+
pending: unknown;
|
|
205
|
+
/** Spend so far, from the run row (own and inclusive of child runs). */
|
|
206
|
+
totals: {
|
|
207
|
+
tokens: number;
|
|
208
|
+
calls: number;
|
|
209
|
+
costUsed: number;
|
|
210
|
+
stepsUsed: number;
|
|
211
|
+
inclusiveTokens: number;
|
|
212
|
+
inclusiveCalls: number;
|
|
213
|
+
inclusiveCost: number;
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import type {\n AiRunBudget,\n AiRunContext,\n AiRunStatus,\n AiRunStopDetail,\n AiRunStopReason,\n} from '@happyvertical/smrt-core';\n\n/** The run type every workflow run carries (docs/content/ai-runs.md). */\nexport const WORKFLOW_RUN_TYPE = 'workflow';\n\n/** Version of {@link WorkflowCheckpointState}'s own shape. */\nexport const WORKFLOW_STATE_VERSION = 1;\n\n/**\n * What a workflow run keeps in its checkpoint (the run type owns this\n * state; core wraps it in a versioned envelope): the step it is on, the\n * repair count, and the accepted outputs of the completed steps. Totals,\n * tokens and attempts are never here: the usage rows and events are the\n * record.\n */\nexport interface WorkflowCheckpointState {\n v: typeof WORKFLOW_STATE_VERSION;\n /** Zero-based index of the step the run is on. */\n stepIndex: number;\n /** `call`: the step's model call is next; `check`: its accepted output awaits the host check. */\n phase: 'call' | 'check';\n /** Repairs used on the current step (attempt = repairs + 1). */\n repairs: number;\n /** Times the host check asked to run the current step again. */\n repeats: number;\n /** The run input, when small enough to keep inline. */\n input: unknown;\n /** A pointer at input the host stores (large input passes by reference). */\n inputRef: string | null;\n /** Accepted outputs of the completed steps, by step index. */\n outputs: unknown[];\n /** The current step's accepted output, awaiting its check. */\n pending: { output: unknown; judgedEventId: string | null } | null;\n /** The current step's last invalid output, for the repair attempt. */\n invalid: { output: unknown; errors: string[] } | null;\n /** The approval (hold) requested for the pending output and not yet decided. */\n approval: { requestEventId: string } | null;\n /**\n * Holds of the current step a person approved so far. A step may hold\n * more than once (one hold per gated action); it passes only when its\n * check passes with no hold outstanding. Absent in older checkpoints: 0.\n */\n approvals?: number;\n}\n\n/** Host-facing progress; names are the host's plain text. */\nexport interface RunProgress {\n runId: string;\n /** One-based step position and the step's name. */\n step: { index: number; count: number; name: string };\n status: AiRunStatus;\n stopReason: AiRunStopReason | null;\n phase: WorkflowCheckpointState['phase'];\n}\n\n/** What a host check decides about a step's accepted output. */\nexport interface WorkflowStepCheck {\n /** Facts for the next step: replaces the run input. */\n input?: unknown;\n /**\n * The host finished the work at this step (it applied the accepted\n * output); the run ends `done` here without running later steps.\n */\n complete?: boolean;\n /**\n * A definitive rejection: the run ends `failed` with `check_failed`. A\n * safe, host-authored explanation; never model output or error text.\n */\n failure?: string;\n /** Run this step again (a new step instance), up to `maxRepeats`. */\n repeat?: boolean;\n /**\n * Pause for a person's decision (durable runs only). Every time a check\n * returns it, a new hold is requested (an `approval` event): a check that\n * holds again after an approval waits again, and the step passes only once\n * its check returns without it.\n */\n waitingApproval?: boolean;\n /**\n * What the hold points at in the host (`payload_ref` of the `approval`\n * request, e.g. `approval:<id>`), for mapping a host decision to the run.\n */\n holdRef?: string;\n /** A short host note recorded on the check or approval event. */\n note?: string;\n}\n\n/** What a step's call or check sees. */\nexport interface WorkflowStepContext {\n runId: string;\n step: { index: number; count: number; name: string };\n /** The run input (resolved from `inputRef` when passed by reference). */\n input: unknown;\n /** Accepted outputs of the completed steps. */\n outputs: readonly unknown[];\n /** 1 for the first try, 2 for the first repair, ... */\n attempt: number;\n /** The previous attempt's invalid output and its errors. */\n repair: { output: unknown; errors: readonly string[] } | null;\n signal: AbortSignal;\n}\n\n/** What a step's check sees. */\nexport interface WorkflowCheckContext extends WorkflowStepContext {\n /**\n * `approved` when the check runs again after a person approved the step's\n * latest hold; null otherwise. Asking for approval again requests a new\n * hold: it is never taken as passed.\n */\n approval: 'approved' | null;\n /** Holds of this step a person approved so far. */\n approvals: number;\n}\n\n/**\n * A step's own execution, replacing the default prompt call (a CLI engine,\n * say). It must send every model call it makes with `runContext`, so each\n * call is reserved, recorded and settled in this run, and return the step's\n * output (an object, or JSON text).\n */\nexport type WorkflowStepExecute = (\n request: WorkflowStepContext & { runContext: AiRunContext },\n) => Promise<unknown>;\n\n/**\n * One host-defined stage of a workflow. Model output cannot change it. By\n * default its call resolves the registered prompt `promptKey` through\n * `resolvePrompt` and sends it on the tracked client; the output must pass\n * `schema` (the host's full validator) and then the host `check`.\n */\nexport interface WorkflowStep {\n name: string;\n /** The registered prompt this step's call uses. */\n promptKey: string;\n schema: Record<string, unknown>;\n /**\n * The prompt's variables. Default: `input`, `outputs`, `schema`,\n * `repairOutput` and `repairErrors` as JSON or plain text.\n */\n variables?: (\n context: WorkflowStepContext,\n ) => Record<string, unknown> | Promise<Record<string, unknown>>;\n /** Deterministic and safe to repeat: recovery may replay it. */\n check?: (\n output: unknown,\n context: WorkflowCheckContext,\n ) => WorkflowStepCheck | Promise<WorkflowStepCheck>;\n /** How many times the check may ask to repeat this step (default 0). */\n maxRepeats?: number;\n /** The output allowance a call of this step is reserved with. */\n expectedOutputTokens?: number;\n execute?: WorkflowStepExecute;\n}\n\n/**\n * A versioned list of steps (one workflow definition). A run resumes only\n * under the version that saved its checkpoint, unless this version declares\n * it accepts older checkpoints and validates or migrates them.\n */\nexport interface WorkflowDefinition {\n key: string;\n version: string;\n steps: readonly WorkflowStep[];\n olderCheckpoints?: {\n /** Whether a checkpoint saved by `version` is accepted. */\n accepts(version: string | null): boolean;\n /**\n * Validate an accepted older checkpoint's state and return it in this\n * version's shape; throw to refuse it (the run then stops with\n * `definition_changed`).\n */\n migrate(\n state: WorkflowCheckpointState,\n version: string | null,\n ): WorkflowCheckpointState;\n };\n}\n\n/** A workflow run as the host sees it. */\nexport interface WorkflowRunState {\n id: string;\n ownerId: string | null;\n tenantId: string | null;\n definitionKey: string | null;\n definitionVersion: string | null;\n status: AiRunStatus;\n stopReason: AiRunStopReason | null;\n stoppedByRunId: string | null;\n stopDetail: AiRunStopDetail | null;\n retryOfRunId: string | null;\n budget: AiRunBudget;\n /** The checkpoint revision this snapshot was read at. */\n revision: number;\n step: { index: number; count: number; name: string };\n phase: WorkflowCheckpointState['phase'];\n input: unknown;\n inputRef: string | null;\n outputs: unknown[];\n /** The current step's accepted output awaiting its check or approval. */\n pending: unknown;\n /** Spend so far, from the run row (own and inclusive of child runs). */\n totals: {\n tokens: number;\n calls: number;\n costUsed: number;\n stepsUsed: number;\n inclusiveTokens: number;\n inclusiveCalls: number;\n inclusiveCost: number;\n };\n}\n"],"mappings":";AASO,IAAM,oBAAoB;AAG1B,IAAM,yBAAyB"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,63 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@happyvertical/smrt-workflows",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.62.0",
|
|
4
|
+
"description": "Durable workflow runs for SMRT: ordered host steps over registered prompts, tracked calls, checkpoints, repair, approval and budgets",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"files": [
|
|
9
|
+
"dist",
|
|
10
|
+
"CLAUDE.md",
|
|
11
|
+
"AGENTS.md",
|
|
12
|
+
"agents"
|
|
13
|
+
],
|
|
14
|
+
"exports": {
|
|
15
|
+
".": {
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"import": "./dist/index.js"
|
|
18
|
+
}
|
|
19
|
+
},
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"@happyvertical/smrt-core": "0.62.0",
|
|
22
|
+
"@happyvertical/smrt-jobs": "0.62.0",
|
|
23
|
+
"@happyvertical/smrt-prompts": "0.62.0",
|
|
24
|
+
"@happyvertical/sql": "^0.113.0"
|
|
25
|
+
},
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"@happyvertical/smrt-vitest": "0.62.0",
|
|
28
|
+
"@types/node": "24.13.6",
|
|
29
|
+
"ajv": "8.20.0",
|
|
30
|
+
"typescript": "6.0.3",
|
|
31
|
+
"vite": "8.1.6",
|
|
32
|
+
"vitest": "4.1.10"
|
|
33
|
+
},
|
|
34
|
+
"keywords": [
|
|
35
|
+
"smrt",
|
|
36
|
+
"workflows",
|
|
37
|
+
"ai",
|
|
38
|
+
"runs",
|
|
39
|
+
"checkpoints"
|
|
40
|
+
],
|
|
41
|
+
"author": "HappyVertical",
|
|
42
|
+
"license": "MIT",
|
|
43
|
+
"publishConfig": {
|
|
44
|
+
"registry": "https://registry.npmjs.org",
|
|
45
|
+
"access": "public"
|
|
46
|
+
},
|
|
47
|
+
"repository": {
|
|
48
|
+
"type": "git",
|
|
49
|
+
"url": "https://github.com/happyvertical/smrt.git",
|
|
50
|
+
"directory": "packages/workflows"
|
|
51
|
+
},
|
|
52
|
+
"sideEffects": false,
|
|
53
|
+
"scripts": {
|
|
54
|
+
"build": "vite build --mode library",
|
|
55
|
+
"build:watch": "vite build --mode library --watch",
|
|
56
|
+
"clean": "rm -rf dist",
|
|
57
|
+
"test": "vitest run",
|
|
58
|
+
"test:postgres": "node ../../scripts/run-with-ci-postgres.mjs -- pnpm exec vitest run optional.test.ts",
|
|
59
|
+
"test:watch": "vitest",
|
|
60
|
+
"typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
|
|
61
|
+
"verify:pack": "node ../../scripts/verify-package-types-exports.js ."
|
|
62
|
+
}
|
|
6
63
|
}
|