@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.
Files changed (41) hide show
  1. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +51 -8
  2. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +25 -12
  3. package/ai-docs/instructions/service-code-format/14-reference-service.md +1 -1
  4. package/ai-docs/instructions/service-code-format/16-gotchas.md +1 -1
  5. package/ai-docs/instructions/service-code-format/README.md +2 -2
  6. package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +4 -4
  7. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
  8. package/ai-docs/providers/claude/main-orchestrator-segment.md +2 -2
  9. package/bin/flowrunner.js +3 -3
  10. package/bin/resolve-local.js +14 -6
  11. package/dist/cli.js +440 -249
  12. package/dist/cli.js.map +4 -4
  13. package/dist/index.js +433 -242
  14. package/dist/index.js.map +4 -4
  15. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
  16. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
  17. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
  18. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
  19. package/dist/types/packages/cli/src/constants/testing.d.ts +9 -4
  20. package/dist/types/shared/src/constants/knowledge-base.d.ts +1 -0
  21. package/dist/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
  22. package/dist/types/shared/src/scheme/crm/dto.d.ts +2 -2
  23. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
  24. package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
  25. package/dist/types/shared/src/scheme/workspace/dto.d.ts +1 -1
  26. package/package.json +3 -3
  27. package/project-files/sandbox/files-mock.js +1 -1
  28. package/project-files/sandbox/nock-mock.js +1 -1
  29. package/project-files/sandbox/service.js +1 -1
  30. package/runtime/index.js +39 -24
  31. package/runtime/index.js.map +2 -2
  32. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
  33. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
  34. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
  35. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
  36. package/runtime/types/shared/src/constants/knowledge-base.d.ts +1 -0
  37. package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
  38. package/runtime/types/shared/src/scheme/crm/dto.d.ts +2 -2
  39. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
  40. package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
  41. 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(config)` and compares it to the header in constant time.
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** (`flowrunner-cli/runtime/index.js`, its `.d.ts` tree, or the templates) to
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 `flowrunner-cli/runtime` module
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 `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` |
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-cli/runtime')
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-cli/runtime')` resolves relative to the
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?, query?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
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 `headers` are the only fields
104
- forwarded to `verifyRequest`; `query` is accepted but not forwarded, and `connectionId` is echoed back on the
105
- response. Unknown fields in `invocation` are ignored rather than rejected.
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-cli/runtime') // installs the Flowrunner global
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/flowrunner-cli/templates/`, or anything else inside the
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 `flowrunner-cli/runtime` settles most runtime questions
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 `flowrunner-cli` source, its bundled runtime, its type definitions or its
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-cli/runtime')` exports `buildServiceDefinition`, `getServiceConfigs`,
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/flowrunner-cli/ai-docs/instructions/service-code-format/`
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 `flowrunner-cli` — do not
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 `flowrunner-cli` package: not its source, not its bundled
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/flowrunner-cli/ai-docs/` is the only exception; everything else in that package is off
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/flowrunner-cli/ai-docs/instructions/service-code-format/` — it ships inside the installed
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/flowrunner-cli/ai-docs/instructions/service-code-format/`
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 `flowrunner-cli` — do not
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-cli@x` is the single thing deciding a project's version — and so that the
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 flowrunner-cli, but it is not installed.')
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 flowrunner-cli (${ resolution.bin }):`)
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
  }
@@ -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-cli@x` the one thing that decides which version a project uses.
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
- const PACKAGE_NAME = 'flowrunner-cli'
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 !!(manifest?.dependencies?.[PACKAGE_NAME] || manifest?.devDependencies?.[PACKAGE_NAME])
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 candidate = path.join(directory, 'node_modules', PACKAGE_NAME)
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, PACKAGE_NAME }
106
+ module.exports = { resolveLocalCli, PACKAGE_NAMES }