@revenexx/integrations-node-devkit 0.8.0 → 0.8.2
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/README.md +2 -1
- package/dist/cli-args.d.ts +33 -0
- package/dist/cli.cjs.map +1 -1
- package/dist/env.d.ts +70 -0
- package/dist/errors.d.ts +21 -0
- package/dist/http.d.ts +23 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +8 -474
- package/dist/loader.d.ts +57 -0
- package/dist/persistence.d.ts +60 -0
- package/dist/ports.d.ts +24 -0
- package/dist/preview/child-env.d.ts +32 -0
- package/dist/preview/host.d.ts +147 -0
- package/dist/preview/pid.d.ts +14 -0
- package/dist/preview/registry.d.ts +40 -0
- package/dist/projections.d.ts +29 -0
- package/dist/resolve.d.ts +125 -0
- package/dist/server.d.ts +13 -0
- package/dist/state-rules.d.ts +32 -0
- package/dist/store.d.ts +184 -0
- package/dist/testing/author.d.ts +33 -0
- package/dist/testing/context.d.ts +96 -0
- package/dist/testing/credentials.d.ts +66 -0
- package/dist/testing/fetch.d.ts +57 -0
- package/dist/testing/index.cjs.map +1 -1
- package/dist/testing/index.d.ts +5 -253
- package/dist/testing/index.js.map +1 -1
- package/dist/testing/mock.d.ts +12 -0
- package/package.json +7 -6
- package/preview-host/package.json +3 -3
- package/dist/index.d.cts +0 -482
- package/dist/testing/index.d.cts +0 -253
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
import { type IsAlive } from './pid.js';
|
|
2
|
+
export interface HostDirOptions {
|
|
3
|
+
/** Devkit version; keys the cache directory. */
|
|
4
|
+
version: string;
|
|
5
|
+
/** Overrides the whole cache location (mainly for tests). */
|
|
6
|
+
cacheRoot?: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Cache location for the managed host: `<cache>/revenexx/devkit-preview/<version>`.
|
|
10
|
+
* Honours `XDG_CACHE_HOME`, falling back to `~/.cache`.
|
|
11
|
+
*/
|
|
12
|
+
export declare function resolveHostDir(options: HostDirOptions): string;
|
|
13
|
+
/**
|
|
14
|
+
* Absolute path of the `preview-host/` directory shipped inside this package.
|
|
15
|
+
*
|
|
16
|
+
* Walks up from this module rather than assuming a fixed depth, because the
|
|
17
|
+
* module sits at `dist/cli.js` in the published package but at
|
|
18
|
+
* `src/preview/host.ts` when running from source (tsx, vitest).
|
|
19
|
+
*/
|
|
20
|
+
export declare function shippedHostDir(): string;
|
|
21
|
+
export interface MaterializeHostOptions {
|
|
22
|
+
/** Where to put the host. */
|
|
23
|
+
targetDir: string;
|
|
24
|
+
/** Overrides the shipped host to copy from (mainly for tests). */
|
|
25
|
+
sourceDir?: string;
|
|
26
|
+
/** Mock API base URL written into the generated `.env`. */
|
|
27
|
+
integrationsApiUrl: string;
|
|
28
|
+
/** Dev token/tenant written into the generated `.env`. */
|
|
29
|
+
devToken?: string;
|
|
30
|
+
devTenant?: string;
|
|
31
|
+
/** Re-copy even when the target already looks complete. */
|
|
32
|
+
force?: boolean;
|
|
33
|
+
/**
|
|
34
|
+
* Name of the generated dotenv file. Defaults to `.env`; `preview` passes a
|
|
35
|
+
* per-repo name for the managed cache (see {@link hostDotenvName}).
|
|
36
|
+
*/
|
|
37
|
+
dotenvName?: string;
|
|
38
|
+
/**
|
|
39
|
+
* True for the version-keyed cache directory devkit owns, false for a `--dir`
|
|
40
|
+
* copy that belongs to the user. Decides two things: whether an incomplete copy
|
|
41
|
+
* may be redone (safe when devkit owns the directory, destructive when the user
|
|
42
|
+
* does), and whether the generated `.env` / `.gitignore` are rewritten on every
|
|
43
|
+
* run or left alone once they exist.
|
|
44
|
+
*/
|
|
45
|
+
managed?: boolean;
|
|
46
|
+
log?: (msg: string) => void;
|
|
47
|
+
}
|
|
48
|
+
export interface MaterializeHostResult {
|
|
49
|
+
dir: string;
|
|
50
|
+
/** True when files were (re-)copied; false when an intact copy was reused. */
|
|
51
|
+
copied: boolean;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Copies the shipped host into `targetDir` and writes the generated files.
|
|
55
|
+
*
|
|
56
|
+
* The copy is wholesale rather than per-file. For the managed cache that is free —
|
|
57
|
+
* nothing in it is worth preserving — so an incomplete copy is simply redone. A
|
|
58
|
+
* `--dir` copy belongs to the user, so there "the defining files are present" has
|
|
59
|
+
* to be enough: re-copying over someone's edits to repair a hypothetical
|
|
60
|
+
* interrupted copy would cost more than it saves.
|
|
61
|
+
*
|
|
62
|
+
* `node_modules/` and the install marker survive a re-copy so an unchanged
|
|
63
|
+
* dependency set is not reinstalled for nothing — `hostNeedsInstall` compares the
|
|
64
|
+
* manifest, so changed pins still reinstall.
|
|
65
|
+
*/
|
|
66
|
+
export declare function materializeHost(options: MaterializeHostOptions): MaterializeHostResult;
|
|
67
|
+
/**
|
|
68
|
+
* Per-consumer Nuxt build directory inside the shared host.
|
|
69
|
+
*
|
|
70
|
+
* The dependency tree is worth sharing; the compiled app is not. Two repos running
|
|
71
|
+
* `preview` concurrently would otherwise build into the same `.nuxt/` and serve
|
|
72
|
+
* each other's app. Keyed by a hash of the consumer's directory so it is stable
|
|
73
|
+
* across runs — the build cache still pays off — and distinct per repo.
|
|
74
|
+
*
|
|
75
|
+
* Necessary but **not sufficient** on its own, and for a while it was worse than
|
|
76
|
+
* that: see {@link hostViteCacheDir}.
|
|
77
|
+
*/
|
|
78
|
+
export declare function hostBuildDir(hostDir: string, consumerDir: string): string;
|
|
79
|
+
/**
|
|
80
|
+
* Per-consumer Vite dependency cache inside the shared host.
|
|
81
|
+
*
|
|
82
|
+
* Vite anchors its `cacheDir` on `rootDir`, not on the build dir, so every repo
|
|
83
|
+
* previewing out of this directory shared one `node_modules/.cache/vite`. That
|
|
84
|
+
* would have been merely wasteful were it not for how Vite invalidates it: the
|
|
85
|
+
* `configHash` covers `resolve.alias`, which contains Nuxt's `#build` alias, which
|
|
86
|
+
* is the per-repo build dir. Two repos therefore each computed a different hash,
|
|
87
|
+
* each judged the other's cache stale, and each ran `rm -rf` on the dependency
|
|
88
|
+
* directory the other was actively serving from — every time, in both directions,
|
|
89
|
+
* until one of them was killed.
|
|
90
|
+
*
|
|
91
|
+
* Overriding `cacheDir` per repo is what actually isolates them. It also pays off
|
|
92
|
+
* sequentially: switching between repos no longer re-optimizes from scratch.
|
|
93
|
+
*/
|
|
94
|
+
export declare function hostViteCacheDir(hostDir: string, consumerDir: string): string;
|
|
95
|
+
/**
|
|
96
|
+
* Per-consumer dotenv filename inside the shared host.
|
|
97
|
+
*
|
|
98
|
+
* Nuxt watches its dotenv file and treats a change as a reason to respawn, so one
|
|
99
|
+
* shared `.env` — rewritten on every run, because it carries the mock's port —
|
|
100
|
+
* restarted every other preview using this directory.
|
|
101
|
+
*/
|
|
102
|
+
export declare function hostDotenvName(consumerDir: string): string;
|
|
103
|
+
/** True when `dir` holds something that looks like a host (its two defining files). */
|
|
104
|
+
export declare function hostExists(dir: string): boolean;
|
|
105
|
+
/**
|
|
106
|
+
* True when `dir` holds a host this devkit finished copying. Stricter than
|
|
107
|
+
* {@link hostExists}, which cannot tell a complete host from the first two files
|
|
108
|
+
* of an interrupted one.
|
|
109
|
+
*/
|
|
110
|
+
export declare function hostIsComplete(dir: string): boolean;
|
|
111
|
+
/**
|
|
112
|
+
* True when dependencies must be installed.
|
|
113
|
+
*
|
|
114
|
+
* Deliberately not just `existsSync(node_modules)`: that was the root of a real
|
|
115
|
+
* bug — `--force` rewrote `package.json` with new pins, the `node_modules/` check
|
|
116
|
+
* then reported "installed", `npm install` was skipped, and Nuxt booted against
|
|
117
|
+
* the old dependency tree. The marker records the manifest the install actually
|
|
118
|
+
* succeeded for, so changed pins and interrupted installs both reinstall.
|
|
119
|
+
*/
|
|
120
|
+
export declare function hostNeedsInstall(dir: string): boolean;
|
|
121
|
+
/** Records a successful install for the host's current manifest. */
|
|
122
|
+
export declare function markHostInstalled(dir: string): void;
|
|
123
|
+
/** Clears the install marker so the next run reinstalls. */
|
|
124
|
+
export declare function clearHostInstallMarker(dir: string): void;
|
|
125
|
+
/**
|
|
126
|
+
* Runs `install` with an exclusive lock on the host directory.
|
|
127
|
+
*
|
|
128
|
+
* `npm install` in a directory another npm is installing into is a good way to end
|
|
129
|
+
* up with a half-written dependency tree, and the shared cache makes that a normal
|
|
130
|
+
* occurrence rather than an exotic one: two repos previewing for the first time
|
|
131
|
+
* after a devkit upgrade both decide they need to install.
|
|
132
|
+
*
|
|
133
|
+
* The lock is a file created with `wx` — the exclusivity comes from the filesystem,
|
|
134
|
+
* not from a check-then-write. It records a pid so a lock left behind by a killed
|
|
135
|
+
* process can be identified and taken over, which matters because the alternative
|
|
136
|
+
* is a cache directory that refuses to install ever again.
|
|
137
|
+
*
|
|
138
|
+
* `needsInstall` is re-checked while holding the lock: after waiting behind another
|
|
139
|
+
* process, the install we were queuing for has usually already done the work.
|
|
140
|
+
*/
|
|
141
|
+
export declare function withInstallLock<T>(dir: string, install: () => Promise<T>, options?: {
|
|
142
|
+
needsInstall?: () => boolean;
|
|
143
|
+
isAlive?: IsAlive;
|
|
144
|
+
log?: (msg: string) => void;
|
|
145
|
+
timeoutMs?: number;
|
|
146
|
+
pollMs?: number;
|
|
147
|
+
}): Promise<T | null>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether a process is still around.
|
|
3
|
+
*
|
|
4
|
+
* `kill(pid, 0)` sends no signal — it only asks the kernel whether the process
|
|
5
|
+
* exists and whether we may signal it. `EPERM` therefore means "alive, but not
|
|
6
|
+
* yours", which counts as alive: a preview started under another user still holds
|
|
7
|
+
* the port.
|
|
8
|
+
*
|
|
9
|
+
* Both the preview registry and the install lock record a pid, and both need the
|
|
10
|
+
* same answer, so this lives on its own rather than in either of them.
|
|
11
|
+
*/
|
|
12
|
+
export declare function pidIsAlive(pid: number): boolean;
|
|
13
|
+
/** Injectable liveness check, so tests need no real processes. */
|
|
14
|
+
export type IsAlive = (pid: number) => boolean;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { type IsAlive } from './pid.js';
|
|
2
|
+
export interface PreviewEntry {
|
|
3
|
+
pid: number;
|
|
4
|
+
/** The node package being previewed — what the user needs in order to recognise it. */
|
|
5
|
+
cwd: string;
|
|
6
|
+
mockPort: number;
|
|
7
|
+
/**
|
|
8
|
+
* The port the Nuxt child was told to use. Nuxt relocates on its own if it lost
|
|
9
|
+
* the race for it, so this is the intended port, not a guaranteed one.
|
|
10
|
+
*/
|
|
11
|
+
uiPort: number;
|
|
12
|
+
startedAt: string;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Live entries, with dead ones deleted as a side effect.
|
|
16
|
+
*
|
|
17
|
+
* Cleaning up on read is deliberate: a preview killed with SIGKILL never gets to
|
|
18
|
+
* deregister, and a registry that only grows would refuse every future preview.
|
|
19
|
+
*/
|
|
20
|
+
export declare function readLivePreviews(hostDir: string, isAlive?: IsAlive): PreviewEntry[];
|
|
21
|
+
export declare function registerPreview(hostDir: string, entry: PreviewEntry): void;
|
|
22
|
+
export declare function unregisterPreview(hostDir: string, pid?: number): void;
|
|
23
|
+
/** One line per running preview, for the refusal message and the startup banner. */
|
|
24
|
+
export declare function describePreview(entry: PreviewEntry): string;
|
|
25
|
+
export interface ConflictOptions {
|
|
26
|
+
/** The repo about to be previewed. */
|
|
27
|
+
cwd: string;
|
|
28
|
+
/** Whether `--parallel` was given. */
|
|
29
|
+
parallel: boolean;
|
|
30
|
+
/** Whether this run would reinstall the shared dependency tree. */
|
|
31
|
+
force?: boolean;
|
|
32
|
+
hostDir: string;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Why this preview must not start, or null if it may.
|
|
36
|
+
*
|
|
37
|
+
* A pure function so the decision is testable — `preview` itself only turns the
|
|
38
|
+
* message into a {@link CliError}. Three cases, in order of severity:
|
|
39
|
+
*/
|
|
40
|
+
export declare function previewConflict(running: PreviewEntry[], options: ConflictOptions): string | null;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { ICredentialDescription, INodeDescription, ITemplateDescription } from '@revenexx/integrations-node-sdk';
|
|
2
|
+
import type { PackageInfo } from './loader.js';
|
|
3
|
+
import type { CredentialRecord, SecretRecord, TriggerRecord, WorkflowRecord } from './store.js';
|
|
4
|
+
/**
|
|
5
|
+
* Maps internal records + manifest descriptions to the exact JSON shapes the
|
|
6
|
+
* production Laravel `/api/v1` surface returns, so the Cockpit UI consumes the
|
|
7
|
+
* mock API without any awareness that it is mocked.
|
|
8
|
+
*/
|
|
9
|
+
export declare function hasDynamicOptions(desc: INodeDescription): boolean;
|
|
10
|
+
export declare function hasDynamicSchema(desc: INodeDescription): boolean;
|
|
11
|
+
export declare function hasDynamicOutputs(desc: INodeDescription): boolean;
|
|
12
|
+
export interface NodeApiContext {
|
|
13
|
+
packageInfo: PackageInfo;
|
|
14
|
+
loadedAt: string;
|
|
15
|
+
}
|
|
16
|
+
export declare function nodeToApi(desc: INodeDescription, ctx?: NodeApiContext): Record<string, unknown>;
|
|
17
|
+
export declare function credentialTypeToApi(desc: ICredentialDescription): Record<string, unknown>;
|
|
18
|
+
/** Projects a credential instance to its masked public API shape (no secrets). */
|
|
19
|
+
export declare function credentialInstanceToApi(record: CredentialRecord, type: ICredentialDescription | undefined): Record<string, unknown>;
|
|
20
|
+
export declare function secretToApi(record: SecretRecord): Record<string, unknown>;
|
|
21
|
+
/**
|
|
22
|
+
* NOTE the asymmetry, which is the contract's and not a mistake here: a WORKFLOW
|
|
23
|
+
* carries its graph as `blob` + `blob_definition_version`, while a TEMPLATE
|
|
24
|
+
* carries its graph as `definition` + `blob_version`.
|
|
25
|
+
*/
|
|
26
|
+
export declare function workflowToApi(record: WorkflowRecord): Record<string, unknown>;
|
|
27
|
+
export declare function triggerToApi(record: TriggerRecord): Record<string, unknown>;
|
|
28
|
+
export declare function templateSummaryToApi(t: ITemplateDescription): Record<string, unknown>;
|
|
29
|
+
export declare function templateFullToApi(t: ITemplateDescription): Record<string, unknown>;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { type IConfigField, type IConfigOption, type ICredential, type ICredentialDescription, type ICredentialResolveResult, type ICredentialTestResult, type INode, type INodeDescription, type IOutputPort } from '@revenexx/integrations-node-sdk';
|
|
2
|
+
import type { LoadedPackage } from './loader.js';
|
|
3
|
+
import type { DevStore } from './store.js';
|
|
4
|
+
export declare function nodeVersions(loaded: LoadedPackage, slug: string): string[];
|
|
5
|
+
/**
|
|
6
|
+
* The order `GET /nodes` lists a package's nodes in: every version of a slug
|
|
7
|
+
* together, newest first, with the slugs themselves in the order the package
|
|
8
|
+
* exports them.
|
|
9
|
+
*
|
|
10
|
+
* Export order alone is not enough any more. The registry answers each slug's
|
|
11
|
+
* versions semver-descending, and the studio's catalogue takes that order as
|
|
12
|
+
* given rather than parsing a semver of its own — since
|
|
13
|
+
* `@revenexx/studio-integrations` 1.3.0 `newerExecutableVersions()` reads "newer
|
|
14
|
+
* than the pinned one" as "earlier in this array". A package that exports 1.0.0
|
|
15
|
+
* before 2.0.0 — the order a human writes them in — would therefore have the
|
|
16
|
+
* inspector announce the OLDER version as the upgrade, and say nothing about the
|
|
17
|
+
* real one. `GET /nodes/{slug}/versions` has always sorted; this is the same
|
|
18
|
+
* order on the listing the catalogue is actually built from.
|
|
19
|
+
*/
|
|
20
|
+
export declare function listNodesNewestFirst(nodes: readonly INodeDescription[]): INodeDescription[];
|
|
21
|
+
export declare function findNode(loaded: LoadedPackage, slug: string, version?: string): INode;
|
|
22
|
+
export declare function findCredential(loaded: LoadedPackage, slug: string): ICredential;
|
|
23
|
+
export declare function findCredentialType(loaded: LoadedPackage, slug: string): ICredentialDescription;
|
|
24
|
+
/** Resolves a credential instance's access data by running its real `resolve`. */
|
|
25
|
+
export declare function resolveCredentialInstance(loaded: LoadedPackage, store: DevStore, credentialId: string): Promise<ICredentialResolveResult>;
|
|
26
|
+
export interface ResolveNodeConfigInput {
|
|
27
|
+
slug: string;
|
|
28
|
+
version?: string;
|
|
29
|
+
/** `"*"` (all), `"outputs"`, or a specific config field key. */
|
|
30
|
+
target: string;
|
|
31
|
+
config: Record<string, unknown>;
|
|
32
|
+
locale?: string;
|
|
33
|
+
}
|
|
34
|
+
export interface ResolveNodeConfigResult {
|
|
35
|
+
options?: IConfigOption[];
|
|
36
|
+
fields?: IConfigField[];
|
|
37
|
+
outputs?: IOutputPort[];
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Runs a node's author-time resolvers for the requested `target`, mirroring
|
|
41
|
+
* the server's `config:resolve` semantics.
|
|
42
|
+
*/
|
|
43
|
+
export declare function resolveNodeConfig(loaded: LoadedPackage, store: DevStore, input: ResolveNodeConfigInput): Promise<ResolveNodeConfigResult>;
|
|
44
|
+
export interface ValidateNodeConfigInput {
|
|
45
|
+
slug: string;
|
|
46
|
+
version?: string;
|
|
47
|
+
config: Record<string, unknown>;
|
|
48
|
+
locale?: string;
|
|
49
|
+
}
|
|
50
|
+
export interface ValidateNodeConfigResult {
|
|
51
|
+
valid: boolean;
|
|
52
|
+
/** Config field key → human-readable messages. Empty object when valid. */
|
|
53
|
+
errors: Record<string, string[]>;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Validates a submitted node `config` against the field rules in its manifest
|
|
57
|
+
* (`required`, `IConfigValidation`, types, static options). For `dynamic-schema`
|
|
58
|
+
* fields the resolved child schema is fetched and its rules applied to the
|
|
59
|
+
* flattened keys. Deep cross-field validation is intentionally out of scope
|
|
60
|
+
* (the production service does that on save); this mirrors the mock's
|
|
61
|
+
* "light, schema-based" fidelity. Unknown extra keys are ignored.
|
|
62
|
+
*
|
|
63
|
+
* A field whose `showIf` does not hold (SDK 1.0.0, PO-410) is skipped whole —
|
|
64
|
+
* not demanded when required, and not type-checked either. The editor does not
|
|
65
|
+
* draw it, so whatever is left under its key is a leftover from a choice the
|
|
66
|
+
* author has since changed, and refusing to save because of it would leave them
|
|
67
|
+
* with an error against a field they cannot see. `settingApplies` comes from the
|
|
68
|
+
* SDK rather than being re-implemented here: the editor drawing the field and
|
|
69
|
+
* this validator deciding whether to demand it have to agree word for word.
|
|
70
|
+
*/
|
|
71
|
+
export declare function validateNodeConfig(loaded: LoadedPackage, store: DevStore, input: ValidateNodeConfigInput): Promise<ValidateNodeConfigResult>;
|
|
72
|
+
export interface ExecuteNodeTestInput {
|
|
73
|
+
slug: string;
|
|
74
|
+
version?: string;
|
|
75
|
+
/** The node's config values to run with. */
|
|
76
|
+
config: Record<string, unknown>;
|
|
77
|
+
/** Simulated input payloads, merged OVER the config (the contract's wording). */
|
|
78
|
+
inputs: Record<string, unknown>;
|
|
79
|
+
/** Wall-clock limit; clamped to >= 1000 ms like the real runtime. */
|
|
80
|
+
timeoutMs?: number;
|
|
81
|
+
}
|
|
82
|
+
export interface ExecuteNodeTestResult {
|
|
83
|
+
outputs: Record<string, unknown>;
|
|
84
|
+
branch: string | null;
|
|
85
|
+
logs: Array<{
|
|
86
|
+
level: string;
|
|
87
|
+
message: string;
|
|
88
|
+
meta?: Record<string, unknown>;
|
|
89
|
+
}>;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Runs a node's real `execute` in-process — the closest the mock gets to the
|
|
93
|
+
* production sandbox, and the endpoint node authors care about most.
|
|
94
|
+
*
|
|
95
|
+
* `execute(ctx, inputs)` takes a single merged object, so `config` and `inputs`
|
|
96
|
+
* are merged here with `inputs` winning, matching how the service describes it.
|
|
97
|
+
* Logger calls are collected and returned as `logs` instead of being dropped.
|
|
98
|
+
*
|
|
99
|
+
* The timeout is enforced by racing, not just by aborting `ctx.signal`. A node
|
|
100
|
+
* that never looks at the signal — an accidental infinite loop's `await`, a
|
|
101
|
+
* third-party client that takes no `AbortSignal` — would otherwise hang the
|
|
102
|
+
* request until Node's own 300 s `requestTimeout`, which is the opposite of what
|
|
103
|
+
* "honours timeout_ms" should mean for someone debugging their own node. The
|
|
104
|
+
* signal is still aborted first, so a well-behaved node fails fast and its own
|
|
105
|
+
* error wins the race.
|
|
106
|
+
*/
|
|
107
|
+
export declare function executeNodeTest(loaded: LoadedPackage, store: DevStore, input: ExecuteNodeTestInput): Promise<ExecuteNodeTestResult>;
|
|
108
|
+
/** Runs a credential type's `test` against inline (unsaved) config. */
|
|
109
|
+
export declare function testCredentialConfig(loaded: LoadedPackage, store: DevStore, typeSlug: string, config: Record<string, unknown>): Promise<ICredentialTestResult>;
|
|
110
|
+
/** Runs `test` against a saved credential instance's stored config. */
|
|
111
|
+
export declare function testCredentialInstance(loaded: LoadedPackage, store: DevStore, credentialId: string): Promise<ICredentialTestResult>;
|
|
112
|
+
export declare function buildOAuthAuthorizeUrl(loaded: LoadedPackage, store: DevStore, credentialId: string, params: {
|
|
113
|
+
redirectUri: string;
|
|
114
|
+
state: string;
|
|
115
|
+
}): Promise<{
|
|
116
|
+
authorizeUrl: string;
|
|
117
|
+
codeVerifier?: string;
|
|
118
|
+
}>;
|
|
119
|
+
export declare function exchangeOAuthCode(loaded: LoadedPackage, store: DevStore, credentialId: string, params: {
|
|
120
|
+
code: string;
|
|
121
|
+
redirectUri: string;
|
|
122
|
+
codeVerifier?: string;
|
|
123
|
+
}): Promise<{
|
|
124
|
+
durableCreds: Record<string, unknown>;
|
|
125
|
+
}>;
|
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import http from 'node:http';
|
|
2
|
+
import type { LoadedPackage } from './loader.js';
|
|
3
|
+
import { type DevStore } from './store.js';
|
|
4
|
+
export interface DevServerDeps {
|
|
5
|
+
/** Returns the currently-loaded package; a function so hot-reload can swap it. */
|
|
6
|
+
getPackage(): LoadedPackage;
|
|
7
|
+
store: DevStore;
|
|
8
|
+
/** JSON schemas served at `/schemas/{domain}[/{version}]`, keyed by `domain` and `domain/version`. */
|
|
9
|
+
schemas?: Record<string, unknown>;
|
|
10
|
+
}
|
|
11
|
+
/** Builds the `(req, res)` request listener implementing the mock `/api/v1` surface. */
|
|
12
|
+
export declare function createRequestListener(deps: DevServerDeps): http.RequestListener;
|
|
13
|
+
export declare function createDevServer(deps: DevServerDeps): http.Server;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The two rules the tenant state store keeps that neither the mock context nor
|
|
3
|
+
* the local preview would otherwise have any reason to keep — and both of which
|
|
4
|
+
* a node author only finds out about in production if we do not.
|
|
5
|
+
*
|
|
6
|
+
* They live here rather than in either caller because the testing harness and
|
|
7
|
+
* the preview must refuse the same things: a node that passes its unit tests and
|
|
8
|
+
* then trips the store on its first preview run has learnt nothing from either.
|
|
9
|
+
* The rest of what the store promises — that a granted claim really excludes a
|
|
10
|
+
* parallel run, that an undeclared namespace is refused — is the engine's, and
|
|
11
|
+
* `specs/workflow-state.md` in the SDK records it as such.
|
|
12
|
+
*/
|
|
13
|
+
/** Mirrors the engine's default claim lifetime (7 days). */
|
|
14
|
+
export declare const DEFAULT_CLAIM_TTL_SECONDS = 604800;
|
|
15
|
+
/** The window the store accepts: one second to one year. */
|
|
16
|
+
export declare const MIN_CLAIM_TTL_SECONDS = 1;
|
|
17
|
+
export declare const MAX_CLAIM_TTL_SECONDS = 31536000;
|
|
18
|
+
/**
|
|
19
|
+
* A `ttlSeconds` outside the accepted window is refused rather than clamped: the
|
|
20
|
+
* figure is the duplicate-suppression window *and* the retry window, so a node
|
|
21
|
+
* quietly given a different one than it asked for would suppress deliveries for
|
|
22
|
+
* a stretch its author never chose.
|
|
23
|
+
*/
|
|
24
|
+
export declare function assertTtlInRange(ttlSeconds: number | undefined): void;
|
|
25
|
+
/**
|
|
26
|
+
* Re-pointing one side of an existing pair is refused, in both directions: an id
|
|
27
|
+
* correlated two ways is always a bug, and no later sync can untangle it —
|
|
28
|
+
* whichever of the two answers a lookup happens to give, half the records it
|
|
29
|
+
* touches are the wrong ones. Writing the same pair again is not a re-point and
|
|
30
|
+
* is allowed, so a node that puts unconditionally on every run stays green.
|
|
31
|
+
*/
|
|
32
|
+
export declare function assertNotRepointed(namespace: string, pairs: Iterable<[string, string]>, left: string, right: string): void;
|
package/dist/store.d.ts
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* In-memory data store backing the mock Integrations API. Holds the tenant-
|
|
3
|
+
* scoped resources a developer creates in the preview (credentials, secrets,
|
|
4
|
+
* workflows, triggers). Serializable so a session can be persisted to and
|
|
5
|
+
* rehydrated from `.revenexx-dev/state.json`.
|
|
6
|
+
*/
|
|
7
|
+
export declare const DEV_TENANT_ID = "dev-tenant";
|
|
8
|
+
export interface CredentialRecord {
|
|
9
|
+
id: string;
|
|
10
|
+
tenantId: string;
|
|
11
|
+
credentialTypeSlug: string;
|
|
12
|
+
name: string;
|
|
13
|
+
status: string;
|
|
14
|
+
/** Full user-entered config, including secret fields (never sent to the UI verbatim). */
|
|
15
|
+
config: Record<string, unknown>;
|
|
16
|
+
/** System-managed long-lived secrets (e.g. an OAuth refresh token). */
|
|
17
|
+
durableCreds: Record<string, unknown> | null;
|
|
18
|
+
/** Outcome of the last `POST /credentials/{id}/test`, which the contract reports. */
|
|
19
|
+
lastTestAt: string | null;
|
|
20
|
+
lastTestOk: boolean | null;
|
|
21
|
+
lastTestMessage: string | null;
|
|
22
|
+
createdAt: string;
|
|
23
|
+
updatedAt: string;
|
|
24
|
+
}
|
|
25
|
+
export interface SecretRecord {
|
|
26
|
+
key: string;
|
|
27
|
+
value: string;
|
|
28
|
+
createdAt: string;
|
|
29
|
+
updatedAt: string;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Field names follow the service's contract: the graph is `blob`, tagged with the
|
|
33
|
+
* `blob_definition_version` it was written against. The mock used to call it
|
|
34
|
+
* `definition`, which meant a workflow saved from the real UI silently lost its
|
|
35
|
+
* graph — the UI sends `blob`, so `body.definition` was always undefined.
|
|
36
|
+
*/
|
|
37
|
+
export interface WorkflowRecord {
|
|
38
|
+
id: number;
|
|
39
|
+
name: string;
|
|
40
|
+
description: string | null;
|
|
41
|
+
blob: Record<string, unknown>;
|
|
42
|
+
blobDefinitionVersion: string;
|
|
43
|
+
active: boolean;
|
|
44
|
+
executionMode: string;
|
|
45
|
+
/** Bumped on every update, like the service's revision counter. */
|
|
46
|
+
revision: number;
|
|
47
|
+
buildStatus: string;
|
|
48
|
+
createdAt: string;
|
|
49
|
+
updatedAt: string;
|
|
50
|
+
}
|
|
51
|
+
/** The only `blob_definition_version` the contract currently allows. */
|
|
52
|
+
export declare const BLOB_DEFINITION_VERSION = "v0-draft";
|
|
53
|
+
/** `execution_mode` values the contract allows; the first is the default. */
|
|
54
|
+
export declare const EXECUTION_MODES: readonly ['async_only', 'sync_only', 'caller_decides'];
|
|
55
|
+
export interface TriggerRecord {
|
|
56
|
+
id: string;
|
|
57
|
+
workflowId: number;
|
|
58
|
+
type: string;
|
|
59
|
+
name: string | null;
|
|
60
|
+
config: Record<string, unknown>;
|
|
61
|
+
active: boolean;
|
|
62
|
+
createdAt: string;
|
|
63
|
+
updatedAt: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* One entry of the tenant state store (PO-374), flattened across the four
|
|
67
|
+
* roles: `key` is the mapping's left id, the cursor's partition key, the
|
|
68
|
+
* claimed key or the digest's entity key, and `value` the partner id, the
|
|
69
|
+
* watermark, the expiry or the hash.
|
|
70
|
+
*
|
|
71
|
+
* The mock keeps them in one list rather than four tables because nothing here
|
|
72
|
+
* enforces integrity — the real store's constraints are the product, this is a
|
|
73
|
+
* scratchpad that makes a node's second run behave like a second run.
|
|
74
|
+
*/
|
|
75
|
+
export interface StateEntryRecord {
|
|
76
|
+
namespace: string;
|
|
77
|
+
role: 'mapping' | 'cursor' | 'dedupe' | 'digest';
|
|
78
|
+
key: string;
|
|
79
|
+
value: unknown;
|
|
80
|
+
updatedAt: string;
|
|
81
|
+
}
|
|
82
|
+
export interface DevStoreSnapshot {
|
|
83
|
+
schemaVersion: number;
|
|
84
|
+
credentials: CredentialRecord[];
|
|
85
|
+
secrets: SecretRecord[];
|
|
86
|
+
workflows: WorkflowRecord[];
|
|
87
|
+
triggers: TriggerRecord[];
|
|
88
|
+
stateEntries?: StateEntryRecord[];
|
|
89
|
+
nextWorkflowId: number;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Bumped to 2 when workflows moved from `definition` to the contract's `blob` /
|
|
93
|
+
* `blob_definition_version` / `active` / `execution_mode`, and to 3 when the
|
|
94
|
+
* state store (PO-374) arrived. `loadState` discards an overlay whose version
|
|
95
|
+
* does not match, which is the migration: seeds are the source of truth, the
|
|
96
|
+
* overlay is disposable session state.
|
|
97
|
+
*/
|
|
98
|
+
export declare const STORE_SCHEMA_VERSION = 3;
|
|
99
|
+
export declare class DevStore {
|
|
100
|
+
private onChange?;
|
|
101
|
+
private credentials;
|
|
102
|
+
private secrets;
|
|
103
|
+
private workflows;
|
|
104
|
+
private triggers;
|
|
105
|
+
/** Keyed by `${role}\u0000${namespace}\u0000${key}` — a NUL occurs in no part. */
|
|
106
|
+
private stateEntries;
|
|
107
|
+
private nextWorkflowId;
|
|
108
|
+
/**
|
|
109
|
+
* @param onChange fired after any mutation so a caller (the CLI) can persist
|
|
110
|
+
* the session to `.revenexx-dev/state.json`.
|
|
111
|
+
*/
|
|
112
|
+
constructor(onChange?: (() => void) | undefined);
|
|
113
|
+
/** (Re)wire the post-mutation callback — e.g. attach it only after seeding. */
|
|
114
|
+
setOnMutation(onChange: (() => void) | undefined): void;
|
|
115
|
+
private touch;
|
|
116
|
+
listCredentials(typeSlug?: string): CredentialRecord[];
|
|
117
|
+
getCredential(id: string): CredentialRecord | undefined;
|
|
118
|
+
createCredential(input: {
|
|
119
|
+
credentialTypeSlug: string;
|
|
120
|
+
name: string;
|
|
121
|
+
config: Record<string, unknown>;
|
|
122
|
+
status?: string;
|
|
123
|
+
/** Stable id — pass to keep a seeded credential's id fixed across restarts. */
|
|
124
|
+
id?: string;
|
|
125
|
+
durableCreds?: Record<string, unknown> | null;
|
|
126
|
+
}): CredentialRecord;
|
|
127
|
+
updateCredential(id: string, patch: Partial<Pick<CredentialRecord, 'name' | 'config' | 'status' | 'durableCreds'>>): CredentialRecord | undefined;
|
|
128
|
+
/**
|
|
129
|
+
* Records the outcome of a credential test. The service persists this on the
|
|
130
|
+
* record and reports it back from `POST /credentials/{id}/test`.
|
|
131
|
+
*/
|
|
132
|
+
recordCredentialTest(id: string, result: {
|
|
133
|
+
ok: boolean;
|
|
134
|
+
message?: string | null;
|
|
135
|
+
}): CredentialRecord | undefined;
|
|
136
|
+
deleteCredential(id: string): boolean;
|
|
137
|
+
listSecrets(): SecretRecord[];
|
|
138
|
+
getSecret(key: string): SecretRecord | undefined;
|
|
139
|
+
setSecret(key: string, value: string): SecretRecord;
|
|
140
|
+
deleteSecret(key: string): boolean;
|
|
141
|
+
listWorkflows(): WorkflowRecord[];
|
|
142
|
+
getWorkflow(id: number): WorkflowRecord | undefined;
|
|
143
|
+
createWorkflow(input: {
|
|
144
|
+
name: string;
|
|
145
|
+
blob: Record<string, unknown>;
|
|
146
|
+
blobDefinitionVersion?: string;
|
|
147
|
+
description?: string | null;
|
|
148
|
+
active?: boolean;
|
|
149
|
+
executionMode?: string;
|
|
150
|
+
}): WorkflowRecord;
|
|
151
|
+
updateWorkflow(id: number, patch: Partial<Pick<WorkflowRecord, 'name' | 'description' | 'blob' | 'blobDefinitionVersion' | 'active' | 'executionMode' | 'buildStatus'>>): WorkflowRecord | undefined;
|
|
152
|
+
deleteWorkflow(id: number): boolean;
|
|
153
|
+
listTriggers(workflowId: number): TriggerRecord[];
|
|
154
|
+
getTrigger(id: string): TriggerRecord | undefined;
|
|
155
|
+
createTrigger(input: {
|
|
156
|
+
workflowId: number;
|
|
157
|
+
type: string;
|
|
158
|
+
name?: string | null;
|
|
159
|
+
config?: Record<string, unknown>;
|
|
160
|
+
active?: boolean;
|
|
161
|
+
id?: string;
|
|
162
|
+
}): TriggerRecord;
|
|
163
|
+
replaceTrigger(id: string, input: {
|
|
164
|
+
type: string;
|
|
165
|
+
name?: string | null;
|
|
166
|
+
config?: Record<string, unknown>;
|
|
167
|
+
active?: boolean;
|
|
168
|
+
}): TriggerRecord | undefined;
|
|
169
|
+
deleteTrigger(id: string): boolean;
|
|
170
|
+
/** The stored entry for a role/namespace/key, or undefined when unknown. */
|
|
171
|
+
getStateEntry(role: StateEntryRecord['role'], namespace: string, key: string): StateEntryRecord | undefined;
|
|
172
|
+
/** Every entry a namespace holds in one role — how a reverse mapping lookup is answered. */
|
|
173
|
+
listStateEntries(role: StateEntryRecord['role'], namespace: string): StateEntryRecord[];
|
|
174
|
+
putStateEntry(entry: Omit<StateEntryRecord, 'updatedAt'>): StateEntryRecord;
|
|
175
|
+
toSnapshot(): DevStoreSnapshot;
|
|
176
|
+
loadSnapshot(snapshot: DevStoreSnapshot): void;
|
|
177
|
+
/**
|
|
178
|
+
* Overlays a snapshot on top of the current contents (upsert by id/key), used
|
|
179
|
+
* to layer the persisted `.revenexx-dev/state.json` session over the freshly
|
|
180
|
+
* applied committed seeds. State entries win over seed entries with the same
|
|
181
|
+
* id/key; seed-only entries are preserved.
|
|
182
|
+
*/
|
|
183
|
+
mergeSnapshot(snapshot: DevStoreSnapshot): void;
|
|
184
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { INodeAuthorContext } from '@revenexx/integrations-node-sdk';
|
|
2
|
+
import type { AnyMock } from './mock.js';
|
|
3
|
+
/**
|
|
4
|
+
* Builds an {@link INodeAuthorContext} for unit-testing a node's *author-time*
|
|
5
|
+
* resolvers (`loadOptions`, `resolveConfigSchema`, `resolveOutputs`). Until this
|
|
6
|
+
* package existed, this factory was reinvented inline in each repo's resolver
|
|
7
|
+
* tests. Mirrors {@link createMockContext}: `secrets.get` / `credentials.get`
|
|
8
|
+
* are `vi.fn<AnyFn>()`-backed and seedable.
|
|
9
|
+
*/
|
|
10
|
+
export type MockAuthorLogger = {
|
|
11
|
+
info: AnyMock;
|
|
12
|
+
warn: AnyMock;
|
|
13
|
+
error: AnyMock;
|
|
14
|
+
};
|
|
15
|
+
export type MockAuthorContext = INodeAuthorContext & {
|
|
16
|
+
logger: MockAuthorLogger;
|
|
17
|
+
secrets: {
|
|
18
|
+
get: AnyMock;
|
|
19
|
+
};
|
|
20
|
+
credentials: {
|
|
21
|
+
get: AnyMock;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
export interface CreateAuthorContextOptions {
|
|
25
|
+
signal?: AbortSignal;
|
|
26
|
+
/** Preferred locale for resolved labels. */
|
|
27
|
+
locale?: string;
|
|
28
|
+
secrets?: Record<string, string>;
|
|
29
|
+
secretsError?: Error;
|
|
30
|
+
credentials?: Record<string, Record<string, unknown>>;
|
|
31
|
+
credentialsError?: Error;
|
|
32
|
+
}
|
|
33
|
+
export declare function createAuthorContext(config?: Record<string, unknown>, options?: CreateAuthorContextOptions): MockAuthorContext;
|