@flowrunner/cli 0.1.0 → 0.1.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/ai-docs/instructions/service-code-format/09-realtime-triggers.md +51 -8
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +25 -12
- package/ai-docs/instructions/service-code-format/14-reference-service.md +1 -1
- package/ai-docs/instructions/service-code-format/16-gotchas.md +1 -1
- package/ai-docs/instructions/service-code-format/README.md +2 -2
- package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +4 -4
- package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
- package/ai-docs/providers/claude/main-orchestrator-segment.md +2 -2
- package/bin/flowrunner.js +3 -3
- package/bin/resolve-local.js +14 -6
- package/dist/cli.js +440 -249
- package/dist/cli.js.map +4 -4
- package/dist/index.js +433 -242
- package/dist/index.js.map +4 -4
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
- package/dist/types/packages/cli/src/constants/testing.d.ts +9 -4
- package/dist/types/shared/src/constants/knowledge-base.d.ts +1 -0
- package/dist/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
- package/dist/types/shared/src/scheme/crm/dto.d.ts +2 -2
- package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
- package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
- package/dist/types/shared/src/scheme/workspace/dto.d.ts +1 -1
- package/package.json +3 -3
- package/project-files/sandbox/files-mock.js +1 -1
- package/project-files/sandbox/nock-mock.js +1 -1
- package/project-files/sandbox/service.js +1 -1
- package/runtime/index.js +39 -24
- package/runtime/index.js.map +2 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
- package/runtime/types/shared/src/constants/knowledge-base.d.ts +1 -0
- package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
- package/runtime/types/shared/src/scheme/crm/dto.d.ts +2 -2
- package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
- package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
- package/runtime/types/shared/src/scheme/workspace/dto.d.ts +1 -1
|
@@ -74,12 +74,12 @@ does its own lowercased retry; that behaviour does not extend to `verifyRequest`
|
|
|
74
74
|
| `subscribe` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` (null first), `connectionId` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
|
|
75
75
|
| `unsubscribe` | `callbackUrl`, `webhookData`, `connectionId` | `{ webhookData? }` |
|
|
76
76
|
| `refresh` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` | `{ webhookData?, refreshIntervalInSeconds }` |
|
|
77
|
-
| `handshake` | `{ requestBody, headers, rawBody }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
|
|
78
|
-
| `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
|
|
77
|
+
| `handshake` | `{ requestBody, headers, rawBody, webhookData }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
|
|
78
|
+
| `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `webhookData`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
|
|
79
79
|
|
|
80
80
|
Both also still accept the **deprecated** `responseToExternalService` / `responseHeaders` — see
|
|
81
81
|
[below](#responsetoexternalservice--deprecated).
|
|
82
|
-
| `verifyRequest` | `{ rawBody, headers }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
|
|
82
|
+
| `verifyRequest` | `{ rawBody, headers, webhookData }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
|
|
83
83
|
|
|
84
84
|
**The `triggers` bag holds one entry per (trigger × `providerEventName`)**, so a trigger declaring several
|
|
85
85
|
names appears several times. A trigger that declares **no** `providerEventName` — what you write when
|
|
@@ -89,6 +89,49 @@ reconcile it. Guard the field rather than assuming it (`if (t.providerEventName)
|
|
|
89
89
|
on it unconditionally. Nothing is left out of the bag: a name resolving to no trigger **rejects the whole
|
|
90
90
|
call** — see [Unknown trigger names](#unknown-trigger-names) below.
|
|
91
91
|
|
|
92
|
+
### `webhookData` on the inbound path — read-only
|
|
93
|
+
|
|
94
|
+
Every inbound seam receives the **stored webhook document**: whatever `subscribe` (or `refresh`) last returned
|
|
95
|
+
as `webhookData`, persisted by the platform and looked up for this delivery.
|
|
96
|
+
|
|
97
|
+
| Seam | Runs | Reads `webhookData` |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| `handshake`, `verify`/`verifyRequest`, `resolveEvents` | once per delivery | ✓ |
|
|
100
|
+
| `match` (predicate form), `extendResult` | per instance / once per event | ✓ |
|
|
101
|
+
| `extendEventData` | per trigger, pure | — |
|
|
102
|
+
|
|
103
|
+
It is the only channel from registration to delivery, and the case it exists for is the **signing secret a
|
|
104
|
+
provider mints when the webhook is created**: it comes back from the registration call, `subscribe` stores it,
|
|
105
|
+
and the delivery it signs can then be verified against it. The same applies to an external webhook id or
|
|
106
|
+
tenant id a delivery has to be recognised or filtered by.
|
|
107
|
+
|
|
108
|
+
⚠️ **Reading is all these seams do.** None of them can update the document — their result types have no
|
|
109
|
+
`webhookData` field, and one returned anyway is dropped. Only `subscribe`, `refresh` and `unsubscribe`
|
|
110
|
+
persist it, so anything an inbound delivery would like to record has to wait for the next one of those.
|
|
111
|
+
Do not design around writing it back from a delivery.
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
verify: {
|
|
115
|
+
header : 'x-provider-signature',
|
|
116
|
+
algo : 'sha256',
|
|
117
|
+
encoding: 'hex',
|
|
118
|
+
// The per-webhook secret the provider issued at registration; the app-level config key is the fallback
|
|
119
|
+
// for a webhook registered before the service started storing it.
|
|
120
|
+
secret : (config, { webhookData }) => webhookData?.signingSecret ?? config.signingSecret,
|
|
121
|
+
},
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
⚠️ **`webhookData` is `null` whenever there is no document to read**, and that is a normal delivery, not a
|
|
125
|
+
broken one:
|
|
126
|
+
|
|
127
|
+
- nothing has been stored for this webhook yet, or
|
|
128
|
+
- the delivery arrived on the **general callback of a service that is not app-hosted** — the document is
|
|
129
|
+
stored per workspace, so there is no workspace to look one up for.
|
|
130
|
+
|
|
131
|
+
So read it defensively (`webhookData?.field`), and never let an absent document *reject* a delivery on its
|
|
132
|
+
own: "no id to compare against" is not "the ids differ". Anything mandatory for verification still belongs in
|
|
133
|
+
`config`, with the stored value as the refinement over it.
|
|
134
|
+
|
|
92
135
|
### `responseToWebhook` — answering the provider
|
|
93
136
|
|
|
94
137
|
Some providers do not accept a generic `200`. Xero's *Intent to Receive* validation sends two deliveries and
|
|
@@ -163,14 +206,14 @@ than the missing input it is — and sends you hunting for a wrong secret.
|
|
|
163
206
|
|
|
164
207
|
### `verify` fields
|
|
165
208
|
|
|
166
|
-
HMACs the **raw body alone** with `secret
|
|
209
|
+
HMACs the **raw body alone** with the key `secret` returns and compares it to the header in constant time.
|
|
167
210
|
|
|
168
211
|
| Field | Req | Description |
|
|
169
212
|
|---|---|---|
|
|
170
213
|
| `header` | ✓ | Signature header. Read as declared, then retried lowercased. Absent header → fail. |
|
|
171
214
|
| `algo` | ✓ | Hash algorithm, e.g. `'sha256'`. |
|
|
172
215
|
| `encoding` | ✓ | `'hex' \| 'base64'` — the digest encoding the provider sends. |
|
|
173
|
-
| `secret` | ✓ | `(config) => key`. |
|
|
216
|
+
| `secret` | ✓ | `(config, { webhookData }) => key`. The second argument is the stored webhook document — `null` when there is none — for a provider that mints the secret at registration time. |
|
|
174
217
|
| `timestampHeader` | – | Header carrying the request timestamp. **Required for `freshness` to run.** |
|
|
175
218
|
| `freshness` | – | Max age in seconds. **Only checked when `timestampHeader` is also declared** — on its own it is silently inert. A declared-but-absent timestamp header passes. |
|
|
176
219
|
|
|
@@ -236,8 +279,8 @@ Use `params` for **filters** — which chat, which board, which status — never
|
|
|
236
279
|
|---|---|---|
|
|
237
280
|
| `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
|
|
238
281
|
| `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
|
|
239
|
-
| `match` (fn) | `{ params, providerEventData }` | `boolean` — for ranges/contains/derived logic |
|
|
240
|
-
| `extendResult` | `{ providerEventData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
|
|
282
|
+
| `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` — for ranges/contains/derived logic |
|
|
283
|
+
| `extendResult` | `{ providerEventData, webhookData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
|
|
241
284
|
|
|
242
285
|
**Inbound runtime flow:** `handshake?` → `verify`/`verifyRequest` → read `extractProviderEventName` → for
|
|
243
286
|
each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
|
|
@@ -254,7 +297,7 @@ costs no provider call.
|
|
|
254
297
|
|---|---|
|
|
255
298
|
| subscribe (flow start) | `null → webhookData` (create webhook / resolve `eventScopeId`) |
|
|
256
299
|
| subscribe (set changed) | `webhookData → webhookData'` (recreate: delete prior + create; or diff) |
|
|
257
|
-
| inbound event | unchanged \| emits matched instances |
|
|
300
|
+
| inbound event | unchanged — **read-only** for every inbound seam (`handshake`, `verify`/`verifyRequest`, `resolveEvents`, `match`, `extendResult`) \| emits matched instances |
|
|
258
301
|
| refresh (opt) | `webhookData → webhookData'` (renew) |
|
|
259
302
|
| unsubscribe (flow stop) | `webhookData → {}` (tear down) |
|
|
260
303
|
|
|
@@ -3,20 +3,20 @@
|
|
|
3
3
|
The other documents describe what to declare. This one collects the handful of **runtime** facts that change
|
|
4
4
|
what you write and that are otherwise visible only by reading the CLI bundle.
|
|
5
5
|
|
|
6
|
-
> **Do not read the CLI bundle** (
|
|
6
|
+
> **Do not read the CLI bundle** (`@flowrunner/cli/runtime/index.js`, its `.d.ts` tree, or the templates) to
|
|
7
7
|
> answer a question about authoring, and do not reason from what the runtime "probably" does. This document
|
|
8
8
|
> is meant to be complete: if a fact you needed is missing, that is a defect here. Report it and proceed on
|
|
9
9
|
> what *is* documented, saying which part you could not confirm — do not go and read the source, and do not
|
|
10
10
|
> fill the gap with an assumption.
|
|
11
11
|
|
|
12
|
-
## The `Flowrunner` global vs the
|
|
12
|
+
## The `Flowrunner` global vs the `@flowrunner/cli/runtime` module
|
|
13
13
|
|
|
14
14
|
Two different surfaces, easily confused:
|
|
15
15
|
|
|
16
16
|
| Surface | How you get it | Contains |
|
|
17
17
|
|---|---|---|
|
|
18
|
-
| **`Flowrunner` global** | always present when the platform runs your service; a harness gets it as a side effect of importing
|
|
19
|
-
| **`require('flowrunner
|
|
18
|
+
| **`Flowrunner` global** | always present when the platform runs your service; a harness gets it as a side effect of importing `@flowrunner/cli/runtime` | `Request`, `z`, `crypto`, `createExtension`, `getExtension`, `ServerCode` |
|
|
19
|
+
| **`require('@flowrunner/cli/runtime')`** | explicit import — **harness-side only** | `buildServiceDefinition`, `getServiceConfigs`, `runServiceMethod`, `detectVersion`, `resetRegistry`, `parseJsDocToServiceJson` |
|
|
20
20
|
|
|
21
21
|
A service module uses only the global, and `require`s nothing. Note that importing the module is what
|
|
22
22
|
installs the global — there is no separate namespace export to pull in.
|
|
@@ -37,13 +37,13 @@ than a syntax error. Check it directly:
|
|
|
37
37
|
```js
|
|
38
38
|
// throwaway check — run it, read it, delete it
|
|
39
39
|
const path = require('path')
|
|
40
|
-
const { buildServiceDefinition } = require('flowrunner
|
|
40
|
+
const { buildServiceDefinition } = require('@flowrunner/cli/runtime')
|
|
41
41
|
|
|
42
42
|
const model = buildServiceDefinition('telegram', path.resolve('services/telegram/src/index.js'))
|
|
43
43
|
console.log(Object.keys(model.methodsMap))
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
**Put the script in the project root.** `require('flowrunner
|
|
46
|
+
**Put the script in the project root.** `require('@flowrunner/cli/runtime')` resolves relative to the
|
|
47
47
|
script's own location, so the same file fails with `MODULE_NOT_FOUND` from `/tmp` and works from the root.
|
|
48
48
|
If the project's `package.json` sets `"type": "module"`, name it `.cjs`.
|
|
49
49
|
|
|
@@ -96,13 +96,26 @@ buildServiceDefinition('telegram', ENTRY)
|
|
|
96
96
|
|---|---|---|
|
|
97
97
|
| `handleTriggerUpsertWebhook` | `{ invocation: { callbackUrl, triggers, webhookData?, connectionId? } }` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
|
|
98
98
|
| `handleTriggerDeleteWebhook` | `{ invocation: { callbackUrl, webhookData, connectionId? } }` | `{ webhookData? }` |
|
|
99
|
-
| `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers } }` | `{ ids, enrichedEventData }` |
|
|
100
|
-
| `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?,
|
|
99
|
+
| `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers, webhookData? } }` | `{ ids, enrichedEventData }` |
|
|
100
|
+
| `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?, queryParams?, webhookData?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
|
|
101
101
|
|
|
102
102
|
`handleTriggerResolveEvents` is the inbound-delivery seam. **`body` is required** — omitting it fails with
|
|
103
|
-
`body: Invalid input: expected nonoptional, received undefined`. `rawBody` and `
|
|
104
|
-
forwarded to `verifyRequest`; `
|
|
105
|
-
|
|
103
|
+
`body: Invalid input: expected nonoptional, received undefined`. `rawBody`, `headers` and `webhookData` are
|
|
104
|
+
the fields forwarded to `verifyRequest`; `connectionId` is echoed back on the response. Unknown fields in
|
|
105
|
+
`invocation` are ignored rather than rejected.
|
|
106
|
+
|
|
107
|
+
⚠️ **The query string is `queryParams` in the invocation and `query` in the handler bag.** Spelling it
|
|
108
|
+
`query` in `methodData` is one of those ignored unknown fields, so `resolveEvents` sees `query: {}` and a
|
|
109
|
+
spec asserting on a query-string branch silently drives the wrong path.
|
|
110
|
+
|
|
111
|
+
**`webhookData` is the webhook document the platform stored** — what `subscribe`/`refresh` last returned —
|
|
112
|
+
looked up for this delivery. It reaches `handshake`, `verify`/`verifyRequest` and `resolveEvents` here, and
|
|
113
|
+
`match`/`extendResult` on `handleTriggerSelectMatched`, and is `null` when none is stored or when the request
|
|
114
|
+
carries no workspace to look one up for (the general callback of a service that is not app-hosted). Both
|
|
115
|
+
methods only **read** it: neither response carries a `webhookData` field, so a document returned from one is
|
|
116
|
+
dropped — only upsert/refresh/delete persist. The harness never supplies it on its own: pass it in
|
|
117
|
+
`invocation` to drive a path that depends on it
|
|
118
|
+
([09-realtime-triggers.md](09-realtime-triggers.md#webhookdata-on-the-inbound-path--read-only)).
|
|
106
119
|
|
|
107
120
|
It answers `{ events: [] }` for a delivery no trigger claims, and `{ handshake: true, events: [] }` for an
|
|
108
121
|
empty body — the runtime acks those automatically, with no `handshake` declared
|
|
@@ -125,7 +138,7 @@ and conclusions drawn that way have been wrong.
|
|
|
125
138
|
Verify the parts you own by calling them directly instead — your `subscribe` body is an ordinary function:
|
|
126
139
|
|
|
127
140
|
```js
|
|
128
|
-
require('flowrunner
|
|
141
|
+
require('@flowrunner/cli/runtime') // installs the Flowrunner global
|
|
129
142
|
require(ENTRY) // registers the service
|
|
130
143
|
const ext = Flowrunner.getExtension('telegram') // note: on the global, not the module export
|
|
131
144
|
// → { props, actions, dictionaries, pollingTriggers, realtimeTriggers, loaders, realtime }
|
|
@@ -6,7 +6,7 @@ including the layout, the naming and the formatting, which are rules rather than
|
|
|
6
6
|
([01-service-structure.md](01-service-structure.md), [03-parameters.md](03-parameters.md)).
|
|
7
7
|
|
|
8
8
|
> **Read this instead of the CLI templates.** The templates that ship with the CLI are project scaffolding,
|
|
9
|
-
> not authoring reference. Do not open `node_modules/
|
|
9
|
+
> not authoring reference. Do not open `node_modules/@flowrunner/cli/templates/`, or anything else inside the
|
|
10
10
|
> package.
|
|
11
11
|
|
|
12
12
|
This file is verified against the runtime: it builds, and the model it produces is the one annotated at the
|
|
@@ -177,7 +177,7 @@ tempting move is defensive code that tries to work either way — feature-detect
|
|
|
177
177
|
shapes. **That hedge is how a silent bug gets written**: it looks careful, it type-checks, and it picks the
|
|
178
178
|
wrong branch without complaining.
|
|
179
179
|
|
|
180
|
-
Establish the fact instead. A scratch script against
|
|
180
|
+
Establish the fact instead. A scratch script against `@flowrunner/cli/runtime` settles most runtime questions
|
|
181
181
|
in a minute (see [13-runtime-contracts.md](13-runtime-contracts.md) for the pattern and the reload caveat),
|
|
182
182
|
and a local `http` server settles any question about what actually goes out on the wire. Then write the one
|
|
183
183
|
branch that is true — and add the fact to 13, which is the fix that stops the next service repeating it.
|
|
@@ -9,7 +9,7 @@ declare a service — use it both for new services and for changes to existing o
|
|
|
9
9
|
|
|
10
10
|
> **This reference is complete, and it is the only source.** Everything needed to build a service — the
|
|
11
11
|
> declaration surface, the runtime behaviour it depends on, and the naming and layout rules — is written
|
|
12
|
-
> down here. So: **never read the
|
|
12
|
+
> down here. So: **never read the `@flowrunner/cli` source, its bundled runtime, its type definitions or its
|
|
13
13
|
> templates**, and never infer a rule from a neighbouring service or from what an API "probably" does.
|
|
14
14
|
>
|
|
15
15
|
> If you cannot find something here, that is a defect in this reference, not an invitation to go and look.
|
|
@@ -113,7 +113,7 @@ the platform does with HTTP intercepted at the socket. It is a separate document
|
|
|
113
113
|
and testing one are separate jobs; do not read it while writing a service.
|
|
114
114
|
|
|
115
115
|
That is also separate from **checking that a service builds**, which needs no suite at all and is part of
|
|
116
|
-
writing one: `require('flowrunner
|
|
116
|
+
writing one: `require('@flowrunner/cli/runtime')` exports `buildServiceDefinition`, `getServiceConfigs`,
|
|
117
117
|
`runServiceMethod`, `detectVersion`, `resetRegistry` and `parseJsDocToServiceJson`, and importing it installs
|
|
118
118
|
the `Flowrunner` global (`Request`, `z`, `crypto`, `createExtension`, `getExtension`, `ServerCode`).
|
|
119
119
|
Signatures, a copy-paste snippet, and the boundary between a throwaway check and a suite are in
|
|
@@ -13,9 +13,9 @@ factory props and zod schemas (`Flowrunner.z`).
|
|
|
13
13
|
|
|
14
14
|
The canonical authoring reference ships inside the installed CLI, versioned with it:
|
|
15
15
|
|
|
16
|
-
`node_modules/
|
|
16
|
+
`node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/`
|
|
17
17
|
|
|
18
|
-
If that directory does not exist, stop and ask the developer to install or update
|
|
18
|
+
If that directory does not exist, stop and ask the developer to install or update `@flowrunner/cli` — do not
|
|
19
19
|
proceed from memory.
|
|
20
20
|
|
|
21
21
|
**Read `README.md` there before anything else, then the documents it routes you to.** It carries the
|
|
@@ -36,7 +36,7 @@ conflicts with those documents, the documents win** — this file describes *how
|
|
|
36
36
|
is correct*.
|
|
37
37
|
|
|
38
38
|
**The reference is complete, and it is the only source.** Those documents are the one thing you read out
|
|
39
|
-
of `node_modules/` — never the rest of the
|
|
39
|
+
of `node_modules/` — never the rest of the `@flowrunner/cli` package: not its source, not its bundled
|
|
40
40
|
runtime, not its type definitions, not its `templates/`. And never reason from what the runtime "probably"
|
|
41
41
|
does. If something you need is not documented, that is a defect in the reference: say so in your report,
|
|
42
42
|
proceed on what *is* documented, and mark plainly which part you could not confirm. A supposition that
|
|
@@ -106,7 +106,7 @@ test engineer can always rebuild the authoritative list itself.
|
|
|
106
106
|
item kinds. The reference states the full rule; treat every existing `id` as untouchable.
|
|
107
107
|
- All changes stay inside the one `services/{id}/` folder; service logic lives only in `src/index.js`.
|
|
108
108
|
- **Never read `node_modules/` as project source.** The authoring reference under
|
|
109
|
-
`node_modules/
|
|
109
|
+
`node_modules/@flowrunner/cli/ai-docs/` is the only exception; everything else in that package is off
|
|
110
110
|
limits, including the CLI's bundled runtime, its type definitions and its `templates/`. If a runtime fact
|
|
111
111
|
seems undocumented it belongs in `13-runtime-contracts.md`: report the gap rather than going to look.
|
|
112
112
|
- **Do not reverse-engineer an undocumented runtime contract by probing it.** Calling a SYSTEM method with
|
|
@@ -43,7 +43,7 @@ A suite lives at `services/{id}/tests/{id}.test.js` and runs with `npm test`. Ev
|
|
|
43
43
|
3. **Note the auth shape** from `configItems`: which values are config, and whether the service declares
|
|
44
44
|
OAuth2. Both change what you pass to `runServiceMethod`.
|
|
45
45
|
4. **Read the authoring reference for anything you are unsure about**, at
|
|
46
|
-
`node_modules/
|
|
46
|
+
`node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/` — it ships inside the installed
|
|
47
47
|
CLI. `15-unit-tests.md` is the testing document and the authority where this file is silent. Add
|
|
48
48
|
`18-test-recipes.md` **only for the kinds this service actually registers** (dictionaries, triggers,
|
|
49
49
|
files); an actions-only service does not need it. `04-http-requests.md`
|
|
@@ -26,12 +26,12 @@ here duplicates that cost without producing anything.
|
|
|
26
26
|
The reference ships inside the installed CLI, versioned with it, so it describes the format this project
|
|
27
27
|
actually deploys:
|
|
28
28
|
|
|
29
|
-
`node_modules/
|
|
29
|
+
`node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/`
|
|
30
30
|
|
|
31
31
|
Its `README.md` is the source of truth for service format — the reading order, the identity-and-naming
|
|
32
32
|
rules, and which document covers what. Where anything conflicts with it, it wins.
|
|
33
33
|
|
|
34
|
-
If that directory does not exist, stop and ask the developer to install or update
|
|
34
|
+
If that directory does not exist, stop and ask the developer to install or update `@flowrunner/cli` — do not
|
|
35
35
|
proceed from memory.
|
|
36
36
|
|
|
37
37
|
## Testing
|
package/bin/flowrunner.js
CHANGED
|
@@ -11,7 +11,7 @@ const srcEntry = path.resolve(cliRoot, 'src', 'cli', 'index.ts')
|
|
|
11
11
|
// ─── Hand over to the project's own copy, if there is one ────────────────────
|
|
12
12
|
//
|
|
13
13
|
// A global install exists to put `flowrunner` on PATH; the project's copy is what should actually run, so
|
|
14
|
-
// that `npm i -D flowrunner
|
|
14
|
+
// that `npm i -D @flowrunner/cli@x` is the single thing deciding a project's version — and so that the
|
|
15
15
|
// templates and ai-docs used are the ones that project pinned. See ./resolve-local.js.
|
|
16
16
|
//
|
|
17
17
|
// `FLOWRUNNER_DELEGATED` makes the hop one-way: the child must run itself whatever it finds, or a copy that
|
|
@@ -20,7 +20,7 @@ if (!process.env.FLOWRUNNER_DELEGATED) {
|
|
|
20
20
|
const resolution = resolveLocalCli(process.cwd(), cliRoot)
|
|
21
21
|
|
|
22
22
|
if (resolution.kind === 'not-installed') {
|
|
23
|
-
console.error('This project depends on
|
|
23
|
+
console.error('This project depends on the FlowRunner CLI, but it is not installed.')
|
|
24
24
|
console.error(' Run `npm install` first — running the globally installed CLI here would use its')
|
|
25
25
|
console.error(' templates and ai-docs instead of the versions this project pinned.')
|
|
26
26
|
process.exit(1)
|
|
@@ -35,7 +35,7 @@ if (!process.env.FLOWRUNNER_DELEGATED) {
|
|
|
35
35
|
})
|
|
36
36
|
|
|
37
37
|
if (result.error) {
|
|
38
|
-
console.error(`Could not run this project's
|
|
38
|
+
console.error(`Could not run this project's FlowRunner CLI (${ resolution.bin }):`)
|
|
39
39
|
console.error(` ${ result.error.message }`)
|
|
40
40
|
process.exit(1)
|
|
41
41
|
}
|
package/bin/resolve-local.js
CHANGED
|
@@ -7,14 +7,18 @@
|
|
|
7
7
|
// CLI reads from its own package — `templates/`, `ai-docs/`, `project-files/` — is resolved from the
|
|
8
8
|
// executing copy (see src/templates/package-root.ts), so running the global's code against a local project
|
|
9
9
|
// would scaffold from the wrong templates and deploy against the wrong runtime docs. Delegating is what
|
|
10
|
-
// keeps `npm i -D flowrunner
|
|
10
|
+
// keeps `npm i -D @flowrunner/cli@x` the one thing that decides which version a project uses.
|
|
11
11
|
//
|
|
12
12
|
// Plain CommonJS with no dependencies: `bin/flowrunner.js` runs before any build step or loader exists.
|
|
13
13
|
|
|
14
14
|
const fs = require('fs')
|
|
15
15
|
const path = require('path')
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
// The CLI moved to the `@flowrunner` npm org. The old name is still installed in every project scaffolded
|
|
18
|
+
// before the move, and those must keep working: a launcher that only looked for the new name would find no
|
|
19
|
+
// local copy in an old project and run its OWN templates and ai-docs there — the exact failure this module
|
|
20
|
+
// exists to prevent. Ordered by preference, so a project holding both resolves to the current one.
|
|
21
|
+
const PACKAGE_NAMES = ['@flowrunner/cli', 'flowrunner-cli']
|
|
18
22
|
const DEFAULT_BIN = path.join('bin', 'flowrunner.js')
|
|
19
23
|
|
|
20
24
|
function realpath(target) {
|
|
@@ -43,7 +47,7 @@ function binOf(packageDirectory) {
|
|
|
43
47
|
}
|
|
44
48
|
|
|
45
49
|
function declaresCli(manifest) {
|
|
46
|
-
return
|
|
50
|
+
return PACKAGE_NAMES.some(name => manifest?.dependencies?.[name] || manifest?.devDependencies?.[name])
|
|
47
51
|
}
|
|
48
52
|
|
|
49
53
|
/**
|
|
@@ -66,9 +70,13 @@ function resolveLocalCli(cwd, cliRoot) {
|
|
|
66
70
|
let directory = path.resolve(cwd)
|
|
67
71
|
|
|
68
72
|
for (;;) {
|
|
69
|
-
const
|
|
73
|
+
for (const name of PACKAGE_NAMES) {
|
|
74
|
+
const candidate = path.join(directory, 'node_modules', ...name.split('/'))
|
|
75
|
+
|
|
76
|
+
if (!fs.existsSync(candidate)) {
|
|
77
|
+
continue
|
|
78
|
+
}
|
|
70
79
|
|
|
71
|
-
if (fs.existsSync(candidate)) {
|
|
72
80
|
if (realpath(candidate) === self) {
|
|
73
81
|
return { kind: 'run-self', reason: 'self' }
|
|
74
82
|
}
|
|
@@ -95,4 +103,4 @@ function resolveLocalCli(cwd, cliRoot) {
|
|
|
95
103
|
return declared ? { kind: 'not-installed' } : { kind: 'run-self', reason: 'no-local-copy' }
|
|
96
104
|
}
|
|
97
105
|
|
|
98
|
-
module.exports = { resolveLocalCli,
|
|
106
|
+
module.exports = { resolveLocalCli, PACKAGE_NAMES }
|