@collective-intelligence/cli 0.0.0-stage → 0.1.1
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 +345 -2
- package/dist/cli.js +3233 -0
- package/dist/declarations/package-declaration.js +62 -0
- package/dist/declarations/workspace-source-condition.js +20 -0
- package/package.json +55 -4
package/README.md
CHANGED
|
@@ -1,3 +1,346 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Collective Intelligence CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The public `ci` binary manages Extension Package development and immutable
|
|
4
|
+
release operations. It talks to the Backend only through generated OpenAPI
|
|
5
|
+
operations; it does not import private Backend runtime code.
|
|
6
|
+
|
|
7
|
+
## Sign In and Enroll Your App
|
|
8
|
+
|
|
9
|
+
Interactive developers sign in once; pipelines keep using a token. Every
|
|
10
|
+
command accepts either credential.
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
# Device login: copy this command from the Dashboard (Organization →
|
|
14
|
+
# Developers → CLI), approve the code in the Dashboard, then the CLI stores a
|
|
15
|
+
# 30-day CLI Session in ~/.config/ci/profiles.json (mode 0600).
|
|
16
|
+
ci login <api-url> --organization <organization-id>
|
|
17
|
+
ci whoami
|
|
18
|
+
ci orgs list
|
|
19
|
+
ci orgs use <organization-id>
|
|
20
|
+
|
|
21
|
+
# Create or replace one Organization-scoped Public Application by FQN and
|
|
22
|
+
# write its connection values. Replace the placeholders with your app's FQN
|
|
23
|
+
# and sign-in callback URL.
|
|
24
|
+
ci apps enroll \
|
|
25
|
+
--fqn <your.app.fqn> \
|
|
26
|
+
--redirect-uri <your-app-callback-url> \
|
|
27
|
+
--scopes context:read \
|
|
28
|
+
--env-file .env.local
|
|
29
|
+
ci logout
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- `ci login <API URL>` resolves the API origin, issuer and JWKS URL from the
|
|
33
|
+
API host's `/.well-known/ci-configuration`. A Dashboard URL is rejected as
|
|
34
|
+
"not a CI API URL"; the Dashboard shows the exact command under Organization
|
|
35
|
+
→ Developers → CLI. `--organization <id>` selects the Current Organization;
|
|
36
|
+
without it, a re-login keeps the Profile's previous Organization for the same
|
|
37
|
+
API origin. `--no-browser` only prints the URL.
|
|
38
|
+
- Resolution order for the backend URL, credential and Organization: flag
|
|
39
|
+
(`--backend-url`, `--organization`), then environment (`CI_BACKEND_URL`,
|
|
40
|
+
`CI_MANAGEMENT_TOKEN`), then the Profile (`--profile` or `CI_PROFILE` selects
|
|
41
|
+
one). A Profile never supplies a session for a different origin.
|
|
42
|
+
- `CI_MANAGEMENT_TOKEN` can be an Organization API key with the
|
|
43
|
+
`public_applications_manage` scope. The key fixes its Organization.
|
|
44
|
+
- `ci apps enroll` requires `--fqn`, `--redirect-uri` (repeatable) and
|
|
45
|
+
`--scopes`. Defaults: `--type public`, name = FQN, allowed origins = redirect
|
|
46
|
+
URI origins, audience = first redirect URI origin. Loopback redirect URIs
|
|
47
|
+
(`http://localhost`, `http://127.0.0.1`, `http://[::1]`) need an explicit port.
|
|
48
|
+
- Output keys: `CI_ISSUER`, `CI_AUDIENCE`, `CI_APPLICATION_ID`, `CI_CLIENT_ID`,
|
|
49
|
+
`CI_ORGANIZATION_ID`, `CI_JWKS_URL`, `CI_SCOPES`, plus `CI_CLIENT_SECRET` for
|
|
50
|
+
`--type confidential`. `--env-file` updates only these keys; without it the
|
|
51
|
+
CLI prints dotenv; `--json` prints one object; `--prefix` replaces `CI_`.
|
|
52
|
+
- A re-run keeps the Application Id and Client Id. It keeps an existing
|
|
53
|
+
`CI_CLIENT_SECRET` only when the same file's `CI_CLIENT_ID` and `CI_ISSUER`
|
|
54
|
+
match the enrolled application; otherwise it fails and asks for
|
|
55
|
+
`--rotate-secret`. It never rotates without `--rotate-secret`. It refuses
|
|
56
|
+
package-owned applications and disabled applications (pass `--enable`).
|
|
57
|
+
- `ci doctor` checks discovery, the JWKS signing key, Organization access and
|
|
58
|
+
registered redirect URIs; `ci apps enroll` runs the same checks before it
|
|
59
|
+
writes output. Each discovery and JWKS request fails after 30 seconds
|
|
60
|
+
without a complete response.
|
|
61
|
+
- Each request of `ci login`, `logout`, `whoami`, `orgs`, `doctor` and
|
|
62
|
+
`apps` also fails after 30 seconds without a complete response; a login
|
|
63
|
+
token poll gets its own 30 seconds. Ctrl-C cancels the request in flight.
|
|
64
|
+
- `ci apps list|get|rotate-secret|disable` manage existing applications.
|
|
65
|
+
|
|
66
|
+
## Deploy an Exact Release
|
|
67
|
+
|
|
68
|
+
`ci deploy` builds and validates one declaration, resolves its exact immutable
|
|
69
|
+
release, publishes/promotes when needed, and installs or updates it for the
|
|
70
|
+
Organization. Use separate publisher and Organization management credentials:
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
export CI_PUBLISHER_TOKEN="publisher-credential"
|
|
74
|
+
export CI_MANAGEMENT_TOKEN="organization-management-credential"
|
|
75
|
+
|
|
76
|
+
ci deploy \
|
|
77
|
+
--backend-url https://ci.example.com \
|
|
78
|
+
--organization <organization-id> \
|
|
79
|
+
--declaration ./src/package.ts \
|
|
80
|
+
--gateway-url com.acme.gateways.one=https://one.example.com \
|
|
81
|
+
--gateway-url com.acme.gateways.two=https://two.example.com \
|
|
82
|
+
--non-interactive --json
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Repeat `--gateway-url <GatewayFQN>=<HTTPS-origin>` for each independently
|
|
86
|
+
addressed declared Gateway. Bindings are deployment inputs, outside the release
|
|
87
|
+
contents. Duplicate, unknown and missing bindings reject clearly. A rerun can
|
|
88
|
+
omit bindings already saved for the installation; supplying a changed origin
|
|
89
|
+
reconciles that binding while reusing the others. Unchanged completed work is
|
|
90
|
+
skipped. A new version updates the existing installation. Backend strict
|
|
91
|
+
publication/version policy rejects same-version changed bytes and silent
|
|
92
|
+
downgrades; targeted package and rollback commands remain available separately.
|
|
93
|
+
Use `--accept-breaking-changes` only to explicitly acknowledge a breaking change
|
|
94
|
+
under the Organization's authority.
|
|
95
|
+
|
|
96
|
+
JSON mode emits newline-delimited records with `kind: progress`, `result`, or
|
|
97
|
+
`error`. An accepted operation is progress, not success. The command follows
|
|
98
|
+
resumable durable operation streams and exits successfully only after every
|
|
99
|
+
required operation succeeds. Failed, blocked or awaiting-continuation outcomes
|
|
100
|
+
exit nonzero with the operation ID and Backend-authored guidance. The default
|
|
101
|
+
overall deadline is 300,000 ms; `--timeout-ms <positive-integer>` changes it.
|
|
102
|
+
Timeout errors preserve the operation ID and last observed event sequence;
|
|
103
|
+
rerun the same intent or use `ci package operation reconnect` to follow it.
|
|
104
|
+
Deterministic request keys include exact release, Organization, endpoint and
|
|
105
|
+
breaking-change acknowledgement and connector setup intent. Broad publisher/management credentials
|
|
106
|
+
are sent only to CI, never to a Gateway endpoint.
|
|
107
|
+
|
|
108
|
+
## Connector Setup
|
|
109
|
+
|
|
110
|
+
Pass `--setup-file <path>` to `ci deploy`, `ci package install`, or
|
|
111
|
+
`ci package update`. The JSON file stays separate from release bytes:
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"connections": {
|
|
116
|
+
"crm": { "connectionId": "2a4cb90a-0e00-4384-8a78-d5279fbb3a77" },
|
|
117
|
+
"warehouse": {
|
|
118
|
+
"newConnection": { "name": "Warehouse production", "fields": {} }
|
|
119
|
+
}
|
|
120
|
+
},
|
|
121
|
+
"adoptions": {
|
|
122
|
+
"com.acme.sales.instances.customers": {
|
|
123
|
+
"instanceId": "42e62b11-1297-4ad3-ae87-19e6cc5b458d"
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Replace the UUIDs with existing authorized Organization resources and supply
|
|
130
|
+
required native credential fields. Connection setup keys match the declaration's
|
|
131
|
+
`setupKey`; adoption keys are concrete declaration FQNs. The backend validates
|
|
132
|
+
Organization/template/ownership compatibility and keeps credentials in native
|
|
133
|
+
connection custody. Invalid input errors omit setup values.
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
ci deploy --backend-url https://ci.example.com --organization <organization-id> \
|
|
137
|
+
--declaration ./src/package.ts --setup-file ./setup.json --non-interactive --json
|
|
138
|
+
|
|
139
|
+
ci package install --backend-url https://ci.example.com --organization <organization-id> \
|
|
140
|
+
--package com.acme.sales --release <exact-release-id> --idempotency-key <request-key> \
|
|
141
|
+
--setup-file ./setup.json
|
|
142
|
+
|
|
143
|
+
ci package update --backend-url https://ci.example.com --organization <organization-id> \
|
|
144
|
+
--installation <installation-id> --release <exact-release-id> \
|
|
145
|
+
--idempotency-key <request-key> --setup-file ./setup.json
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
An explicit setup file submits installation/update even when the exact release
|
|
149
|
+
already serves. Deploy request keys include canonical setup contents: identical
|
|
150
|
+
retries reuse their intent; changed setup gets a different key. For package
|
|
151
|
+
install/update, reuse the explicit key only for identical intent; the backend
|
|
152
|
+
rejects conflicting replay. Setup flags apply only to install/update, not sync or
|
|
153
|
+
publication. A successful configuration operation does not mean records have
|
|
154
|
+
been imported; native schedules/manual actions run afterward.
|
|
155
|
+
|
|
156
|
+
## Immutable Release Builds
|
|
157
|
+
|
|
158
|
+
Build one package declaration into a deterministic, runtime-only release:
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
ci package build --declaration ./src/package.ts --out ./dist/release
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The output directory contains `release.tar`, the authoritative
|
|
165
|
+
`manifest.json`, and private maps under
|
|
166
|
+
`private-source-maps/<runtime-asset-digest>.map`. The archive contains only
|
|
167
|
+
the Backend, Dashboard, and Studio runtime assets declared and integrity
|
|
168
|
+
addressed by the manifest. Private source maps remain outside the runtime
|
|
169
|
+
archive and do not have a public path or URL.
|
|
170
|
+
|
|
171
|
+
Frontend builds keep host-provided modules external and convert CommonJS
|
|
172
|
+
`require` calls for those modules into ESM imports. A CommonJS dependency can
|
|
173
|
+
therefore use the host's React runtime without requiring a Node.js loader in the
|
|
174
|
+
browser. The ESM external-require plugin owns the host-module allowlist; do not
|
|
175
|
+
duplicate those modules in the top-level bundler `external` option, which would
|
|
176
|
+
bypass that conversion.
|
|
177
|
+
Dashboard extensions also share `@xyflow/react` with the host so their handles
|
|
178
|
+
use the same canvas provider as the Dashboard.
|
|
179
|
+
Dashboard and Studio extensions share `@tanstack/react-query` with the host so
|
|
180
|
+
their query hooks read the host's `QueryClient` instead of a bundled copy
|
|
181
|
+
without a provider.
|
|
182
|
+
|
|
183
|
+
Dashboard and Studio builds keep
|
|
184
|
+
`@collective-intelligence/extensions-sdk-frontend-react/workflow` as a
|
|
185
|
+
Host-provided import. The Host supplies its workflow rendering runtime;
|
|
186
|
+
the release archive does not bundle a fallback copy of that runtime.
|
|
187
|
+
|
|
188
|
+
Validate the complete materialized result before publication:
|
|
189
|
+
|
|
190
|
+
```sh
|
|
191
|
+
ci package validate \
|
|
192
|
+
--archive ./dist/release/release.tar \
|
|
193
|
+
--manifest ./dist/release/manifest.json \
|
|
194
|
+
--package-manifest ./dist/release/package-manifest.json
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Validation checks the canonical manifest, archive and asset digests and
|
|
198
|
+
sizes, private-map integrity, and every relative runtime import without
|
|
199
|
+
evaluating Extension code. Use `--private-maps <directory>` only when the
|
|
200
|
+
private maps were moved from their default directory next to the manifest.
|
|
201
|
+
|
|
202
|
+
## Development Sessions
|
|
203
|
+
|
|
204
|
+
Set an authenticated management token and name the Backend and every Host
|
|
205
|
+
origin that may load local assets:
|
|
206
|
+
|
|
207
|
+
```sh
|
|
208
|
+
export CI_MANAGEMENT_TOKEN="replace-with-an-ai-manage-token"
|
|
209
|
+
|
|
210
|
+
ci package dev \
|
|
211
|
+
--backend-url https://ci-api.localhost:1355 \
|
|
212
|
+
--declaration ./src/package.ts \
|
|
213
|
+
--host-origin https://ci-dashboard.localhost:1355 \
|
|
214
|
+
--host-origin https://ci-studio.localhost:1355 \
|
|
215
|
+
--host-origin http://localhost:5274 \
|
|
216
|
+
--host-origin tauri://localhost
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
`CI_BACKEND_URL` may replace `--backend-url` for `package dev` only.
|
|
220
|
+
`CI_MANAGEMENT_TOKEN` is always required and must authorize `ai:manage` on the
|
|
221
|
+
selected Backend. Origins are exact, explicit attachments: an omitted origin
|
|
222
|
+
cannot resolve or fetch the session's assets.
|
|
223
|
+
|
|
224
|
+
The foreground command creates one ephemeral Development Session per declared
|
|
225
|
+
package, publishes a Local Manifest, and serves Vite 8.2.1 modules and sanitized
|
|
226
|
+
source maps from an opaque loopback HTTP address. Each server issues an
|
|
227
|
+
unguessable capability in its module and source-map URLs so Backend and Bun
|
|
228
|
+
consumers without an `Origin` can fetch only the exact published URLs. Browser
|
|
229
|
+
requests with an `Origin` must still match an attached origin; a detached
|
|
230
|
+
origin is rejected even when it presents the capability URL. Responses are
|
|
231
|
+
`no-store`. The capability is a path prefix, so relative executable-chunk and
|
|
232
|
+
advertised source-map URLs retain authorization. Vite may emit a source-mapless
|
|
233
|
+
facade; the CLI omits that nonexistent map from the Local Manifest while its
|
|
234
|
+
imported executable chunk advertises a sanitized, fetchable map. Contributions
|
|
235
|
+
are kept distinct by Host and FQN. Source-only changes rebuild fresh content at
|
|
236
|
+
the already published URLs without incrementing the Local Manifest revision;
|
|
237
|
+
contribution identity or compatibility changes publish a new revision. The
|
|
238
|
+
local package root is watched, including imported sources and declaration
|
|
239
|
+
re-exports.
|
|
240
|
+
|
|
241
|
+
The command heartbeats every session every 5 seconds. The Backend gives a
|
|
242
|
+
package to one live command at a time: a second `package dev` for the same
|
|
243
|
+
package reports that another command owns it and retries until the owner stops
|
|
244
|
+
or misses heartbeats for about 15 seconds. When the Backend forgets a session,
|
|
245
|
+
for example after a restart, the command re-creates it and republishes the
|
|
246
|
+
current Local Manifest without developer action. Other heartbeat failures are
|
|
247
|
+
reported on stderr and retried on the next interval.
|
|
248
|
+
|
|
249
|
+
The session lives only for the command lifetime. On `SIGINT` or `SIGTERM`, the
|
|
250
|
+
CLI uses the same authenticated generated client to terminate every session
|
|
251
|
+
before closing its asset server. A failed initial publication also terminates
|
|
252
|
+
any session that was already created. Removing a package declaration terminates
|
|
253
|
+
its session immediately; shutdown terminates only the packages still declared.
|
|
254
|
+
|
|
255
|
+
The repository's built-in `@platform/extensions#dev` task uses
|
|
256
|
+
`CI_BACKEND_URL`, `CI_DASHBOARD_URL`, `CI_STUDIO_URL`, and `CI_STUDIO_PORT`. It
|
|
257
|
+
attaches the configured Dashboard and Studio URLs, the direct Studio WebView
|
|
258
|
+
origin at `http://localhost:${CI_STUDIO_PORT}`, and `tauri://localhost`, waits
|
|
259
|
+
for Backend `/health`, and requires the same `CI_MANAGEMENT_TOKEN`; missing
|
|
260
|
+
authentication fails visibly.
|
|
261
|
+
|
|
262
|
+
## Release commands
|
|
263
|
+
|
|
264
|
+
Frontend release entries require the named `loadFrontendCatalog` export. The
|
|
265
|
+
built module also preserves the authored entry's named exports and its default
|
|
266
|
+
export when present, so catalog renderer references using `import.meta.url`
|
|
267
|
+
remain executable after bundling for Dashboard and Studio. Frontend source is
|
|
268
|
+
inspected statically during the build; the CLI does not execute catalog loaders
|
|
269
|
+
or renderers to discover exports.
|
|
270
|
+
|
|
271
|
+
For exact-FQN claims and credential-first publication setup, see the
|
|
272
|
+
[Extension package CLI guide](../../../docs/reference/package-release-cli.md).
|
|
273
|
+
|
|
274
|
+
Publication and administration also require an explicit `--backend-url` and a
|
|
275
|
+
`CI_MANAGEMENT_TOKEN` carrying the permission for that operation:
|
|
276
|
+
|
|
277
|
+
```sh
|
|
278
|
+
ci package publish --backend-url https://ci.example.com \
|
|
279
|
+
--archive ./dist/release/release.tar \
|
|
280
|
+
--manifest ./dist/release/manifest.json \
|
|
281
|
+
--package-manifest ./dist/release/package-manifest.json \
|
|
282
|
+
--idempotency-key build-482-publish
|
|
283
|
+
|
|
284
|
+
# Only needed if private maps were moved from their default sibling directory:
|
|
285
|
+
ci package publish --backend-url https://ci.example.com \
|
|
286
|
+
--archive ./dist/release/release.tar \
|
|
287
|
+
--manifest ./dist/release/manifest.json \
|
|
288
|
+
--package-manifest ./dist/release/package-manifest.json \
|
|
289
|
+
--private-maps ./secure/private-source-maps \
|
|
290
|
+
--idempotency-key build-482-publish
|
|
291
|
+
|
|
292
|
+
ci package promote --backend-url https://ci.example.com \
|
|
293
|
+
--release release_123 --idempotency-key build-482-promote
|
|
294
|
+
|
|
295
|
+
ci package releases --backend-url https://ci.example.com \
|
|
296
|
+
--organization org_123 --package acme.analytics
|
|
297
|
+
|
|
298
|
+
ci package install --backend-url https://ci.example.com \
|
|
299
|
+
--organization org_123 --package acme.analytics \
|
|
300
|
+
--release release_123 --idempotency-key org-123-install-release-123
|
|
301
|
+
|
|
302
|
+
ci package update --backend-url https://ci.example.com \
|
|
303
|
+
--organization org_123 --installation installation_123 \
|
|
304
|
+
--release release_456 --idempotency-key org-123-update-release-456
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
`ci deploy` orchestrates an exact package release. The `package` command group
|
|
308
|
+
retains targeted build, publication, installation, and recovery commands. The
|
|
309
|
+
former schema-only and Workflow-only deploy commands were removed; schemas,
|
|
310
|
+
applications, and Workflows are delivered through package releases.
|
|
311
|
+
|
|
312
|
+
Targeted `ci package install` and `ci package update` use generated current package
|
|
313
|
+
contracts. Connection-map files are not accepted. Use `ci deploy` with declared
|
|
314
|
+
Gateway URL bindings for a package's first Gateway enrollment; subsequent exact
|
|
315
|
+
reruns reuse the saved URLs when omitted.
|
|
316
|
+
|
|
317
|
+
Management tokens are supplied through the environment and are never embedded
|
|
318
|
+
in asset URLs, Local Manifests, or command output. The asset URL capability is
|
|
319
|
+
ephemeral, scoped to one local server process, and is not a Backend credential.
|
|
320
|
+
|
|
321
|
+
## Dataset package instances
|
|
322
|
+
|
|
323
|
+
Managed and External Dataset declarations use the same `ci deploy`, `ci package
|
|
324
|
+
install` and `ci package update --setup-file` commands described above. Author the
|
|
325
|
+
required lifecycle and existing provider FQN with the [SDK Dataset examples](../extensions-sdk/README.md#concrete-managed-and-external-datasets).
|
|
326
|
+
Connection setup remains private input; the release references its `setupKey`.
|
|
327
|
+
Gateway-backed sources require existing manifest approval before admission.
|
|
328
|
+
|
|
329
|
+
For newly package-created Datasets, omitted `dataPolicy` grants no query access,
|
|
330
|
+
including to the deploying actor. Installation configures empty Managed backing
|
|
331
|
+
or a live External binding without importing rows or projection backfill.
|
|
332
|
+
Authorized Managed file/batch ingestion stays manual. Package-declared External
|
|
333
|
+
health/definition refresh schedules and subsequent explicit definition review use
|
|
334
|
+
native Dataset behavior; refresh does not approve or widen a policy implicitly.
|
|
335
|
+
|
|
336
|
+
## Client secrets for package-created applications
|
|
337
|
+
|
|
338
|
+
Install creates a declared confidential application without a client secret.
|
|
339
|
+
An administrator holding `public_applications:manage` (CLI Session, Dashboard
|
|
340
|
+
session token or API key) runs `ci apps rotate-secret <application-id>`, calls
|
|
341
|
+
`POST /admin/organization/public-applications/<application-id>/credential/rotate`
|
|
342
|
+
with the `x-organization-id` header, or chooses **Rotate secret** on the
|
|
343
|
+
application in the Dashboard External Apps page. The response shows
|
|
344
|
+
`clientSecret` once; store it server-side immediately, because CI keeps only its
|
|
345
|
+
hash. Each rotation invalidates the previous secret. See
|
|
346
|
+
[Provision a secret for a package-created application](../../../docs/reference/package-release-cli.md#provision-a-secret-for-a-package-created-application).
|