@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 CHANGED
@@ -1,3 +1,346 @@
1
- # Temporary Holding Version
1
+ # Collective Intelligence CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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).