@cyaxis/ulvia 1.0.8 → 1.0.18
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/INSTALLATION.md +140 -285
- package/README.md +157 -168
- package/SHARED-HOSTING.md +311 -0
- package/dist/definitions/services-tls.yml +0 -16
- package/dist/definitions/services.yml +30 -23
- package/dist/index.js +44452 -38769
- package/dist/stack-release.json +1 -0
- package/package.json +2 -1
- package/dist/definitions/edge-tls.yml +0 -5
- package/dist/definitions/edge.yml +0 -36
- package/dist/definitions/nginx/capability_cache.conf +0 -13
- package/dist/definitions/nginx/client_max_body.conf +0 -2
- package/dist/definitions/nginx/default_location +0 -8
- package/dist/definitions/nginx/query_safe_access_log.conf +0 -4
package/README.md
CHANGED
|
@@ -1,175 +1,138 @@
|
|
|
1
1
|
# Ulvia CLI
|
|
2
2
|
|
|
3
|
-
Ulvia installation and release CLI.
|
|
3
|
+
Ulvia installation and release CLI. The shared-hosting implementation requires
|
|
4
|
+
compatible Provider and Edge images labelled `io.ulvia.hosting-api=1`.
|
|
4
5
|
|
|
5
|
-
For the operator journey
|
|
6
|
-
|
|
6
|
+
For the operator journey, follow the
|
|
7
|
+
[installation guide](INSTALLATION.md). Architecture,
|
|
8
|
+
verification and deployment limits are documented in
|
|
9
|
+
[shared hosting](SHARED-HOSTING.md).
|
|
7
10
|
|
|
8
|
-
The workspace package
|
|
9
|
-
|
|
10
|
-
|
|
11
|
+
The workspace package is private source. Official distribution bundles workspace
|
|
12
|
+
dependencies into `@cyaxis/ulvia`; it does not publish this workspace package.
|
|
13
|
+
Workspace TypeScript declarations are emitted to `dist/types/`, separately from
|
|
14
|
+
the generated system snapshot in `dist/bootstrap/`. Regenerating that snapshot
|
|
15
|
+
must not remove compiler outputs or make incremental and clean builds differ.
|
|
16
|
+
Build one exact CLI release and its compatible default stack version with:
|
|
11
17
|
|
|
12
18
|
```bash
|
|
13
|
-
bun
|
|
14
|
-
ulvia --help
|
|
19
|
+
bun run build --version VERSION
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
Use the same exact distribution version for the CLI, Provider and Edge. This creates a checked
|
|
23
|
+
npm archive and one SHA-256 receipt below `artifacts/distributions/VERSION/cli/`. Publishing is a separate
|
|
24
|
+
explicit `bun run publish --version VERSION` operation. The versioned build seals
|
|
25
|
+
the CLI, images and official releases under `artifacts/distributions/VERSION/`;
|
|
26
|
+
publication selects that snapshot and verifies its bytes before any upload.
|
|
27
|
+
|
|
28
|
+
## Shared infrastructure
|
|
29
|
+
|
|
30
|
+
From workspace source, supply an exact initial image version:
|
|
18
31
|
|
|
19
32
|
```bash
|
|
20
|
-
bun run
|
|
21
|
-
bun run
|
|
33
|
+
bun run ulvia -- configure --domain control.localhost --edges 1
|
|
34
|
+
bun run ulvia -- apply --version STACK_VERSION
|
|
35
|
+
bun run ulvia -- status
|
|
36
|
+
bun run ulvia -- logs --filter component=provider
|
|
37
|
+
bun run ulvia -- logs --filter service=edge-1 --follow
|
|
38
|
+
bun run ulvia -- stop
|
|
39
|
+
bun run ulvia -- start
|
|
22
40
|
```
|
|
23
41
|
|
|
24
|
-
The
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
42
|
+
The CLI starts one Compose project with MongoDB, Provider, Caddy and a configured
|
|
43
|
+
pool of shared Edge processes. The Provider automatically creates empty Control.
|
|
44
|
+
The default public URL is `http://control.localhost:5100/.cms/setup`. Initial
|
|
45
|
+
administrator credentials are in the private file announced at startup, never
|
|
46
|
+
printed. Control uses native setup and can explicitly remain without collections
|
|
47
|
+
or Pages. Create other logical sites through its admitted `ulvia/cms.hosting`
|
|
48
|
+
HTTP/MCP capabilities; no CLI instance lifecycle commands remain.
|
|
49
|
+
|
|
50
|
+
`configure --edges 2` followed by `apply` scales the pool. Site creation
|
|
51
|
+
does not create containers. Reducing the configured count removes obsolete shared
|
|
52
|
+
Edge containers. Stopping infrastructure makes all its logical sites unavailable
|
|
53
|
+
while retaining their persistent data.
|
|
54
|
+
|
|
55
|
+
Persistent data lives below `$XDG_DATA_HOME/ulvia` or
|
|
56
|
+
`~/.local/share/ulvia`. `ULVIA_DATA_DIR` provides explicit installation isolation.
|
|
57
|
+
`services/installation.json` holds mandatory hosting and network configuration;
|
|
58
|
+
`services/stack.json` separates the last applied deployment from a resumable operation;
|
|
59
|
+
`services/deployments/<id>/` retains its exact private Compose/configuration snapshot;
|
|
60
|
+
`services/runtime.json` holds private infrastructure keys. MongoDB and CMS file
|
|
61
|
+
storage belong to the shared services. There is no per-site Edge runtime state.
|
|
62
|
+
The local release cache remains in `<data>/repository`.
|
|
63
|
+
|
|
64
|
+
The CLI reuses validated cached exact-version images and pulls missing ones.
|
|
65
|
+
It checks component, stack API, hosting API, version and repository digest. A
|
|
66
|
+
mismatched cached image refuses startup. Source builds require `--version` on
|
|
67
|
+
first apply; bundled releases carry an exact default. `start` only starts existing
|
|
68
|
+
containers using the applied snapshot. Explicit stack upgrades use:
|
|
30
69
|
|
|
31
70
|
```bash
|
|
32
|
-
|
|
33
|
-
bun run ulvia -- services start --version 0.0.1-beta
|
|
34
|
-
bun run ulvia -- services status
|
|
35
|
-
bun run ulvia -- instance create preview --label "Preview site"
|
|
36
|
-
bun run ulvia -- instance list
|
|
37
|
-
bun run ulvia -- instance credentials preview
|
|
38
|
-
bun run ulvia -- instance stop preview
|
|
39
|
-
bun run ulvia -- instance delete preview --yes
|
|
40
|
-
bun run ulvia -- services stop
|
|
41
|
-
bun run ulvia -- upgrade edge --version 0.0.1-beta
|
|
42
|
-
bun run ulvia -- upgrade provider --version 0.0.1-beta
|
|
43
|
-
bun run ulvia -- reset --yes
|
|
44
|
-
bun run ulvia -- release packages/official-repository/collections/mossa
|
|
45
|
-
bun run ulvia -- release /path/to/contract-directory
|
|
46
|
-
bun run ulvia -- release /path/to/provider-directory
|
|
47
|
-
bun run ulvia -- push contract ulvia/cms.installations@1.0.0 --repository https://repository.example
|
|
48
|
-
bun run ulvia -- pull collection ulvia/mossa@1.0.0 --repository https://repository.example
|
|
49
|
-
bun run ulvia -- yank collection ulvia/mossa@1.0.0 --repository https://repository.example --reason "Superseded"
|
|
50
|
-
bun run ulvia -- restore collection ulvia/mossa@1.0.0 --repository https://repository.example
|
|
51
|
-
bun run ulvia -- prune
|
|
71
|
+
ulvia upgrade --version STACK_VERSION
|
|
52
72
|
```
|
|
53
73
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
public
|
|
62
|
-
data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
|
|
63
|
-
`ULVIA_DATA_DIR` remains an explicit isolation override for tests and CI. The
|
|
64
|
-
CLI stores authored releases in `<data>/repository`. Shared Provider,
|
|
65
|
-
MongoDB, proxy, files, secrets and logs live below `<data>/services`; each
|
|
66
|
-
stateless Edge has independent state and logs below `<data>/instances/<name>`.
|
|
67
|
-
The CLI never starts application servers, supervises their PIDs, or builds
|
|
68
|
-
software images. It pulls only the canonical public images under
|
|
69
|
-
`docker.io/cyaxis`, validates their Ulvia component and stack-API labels, and
|
|
70
|
-
stores the immutable repository digest selected for each component.
|
|
71
|
-
|
|
72
|
-
The first lifecycle command creates a safe installation configuration bound to
|
|
73
|
-
`127.0.0.1:5100`. Configure public exposure before creating an instance:
|
|
74
|
+
Provider replacement checks retained execution support first. Failed activation
|
|
75
|
+
retains a resumable target while the applied release stays unchanged. `status`
|
|
76
|
+
shows observed container/image state. Resume with `upgrade`; no data rollback occurs.
|
|
77
|
+
Contract and collection upgrades remain explicit admitted operations.
|
|
78
|
+
|
|
79
|
+
## Domains and initial access
|
|
80
|
+
|
|
81
|
+
Configure public listeners before first launch:
|
|
74
82
|
|
|
75
83
|
```bash
|
|
76
|
-
ulvia configure
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
--tls acme \
|
|
80
|
-
--https-port 443 \
|
|
81
|
-
--acme-email ops@example.com
|
|
82
|
-
ulvia start
|
|
83
|
-
ulvia instance create website --domain example.com
|
|
84
|
+
ulvia configure --bind 0.0.0.0 --http-port 80 --tls acme --https-port 443 --acme-email ops@example.com
|
|
85
|
+
ulvia configure --domain control.example.com --public-addresses 203.0.113.10
|
|
86
|
+
ulvia apply
|
|
84
87
|
```
|
|
85
88
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
`
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
A Repository is an ordinary named CMS instance with an explicit application
|
|
114
|
-
profile:
|
|
89
|
+
Use the installation's real domain and addresses. Network settings and Control's
|
|
90
|
+
origin lock after the first launch. Hosting settings can change the shared Edge
|
|
91
|
+
count, operator-managed suffixes and public-address allowlist; apply them with
|
|
92
|
+
`apply`. Customer domain claims use Control's contracts and ownership validation.
|
|
93
|
+
Caddy uses the admitted TLS permission binding and persistent certificate storage.
|
|
94
|
+
DNS/TLS pending state is distinct from a provisioned instance and healthy backend.
|
|
95
|
+
The Provider operator listener remains on loopback.
|
|
96
|
+
|
|
97
|
+
Native setup offers a custom Repository, the official Repository, or creating a
|
|
98
|
+
Registry on that instance. Registry activation is explicit, through its exact
|
|
99
|
+
installed selection; it has no separate image, container, profile or service.
|
|
100
|
+
All sites begin without collections. Completing an empty site leaves `/` at 404.
|
|
101
|
+
|
|
102
|
+
Infrastructure mutations share a native process lock at the installation root.
|
|
103
|
+
Missing mandatory configuration or keys over existing state fail without repair;
|
|
104
|
+
startup never replaces an existing Control administrator. `reset --yes` deletes
|
|
105
|
+
Ulvia-owned installation data and the local release cache. Keep a complete matching
|
|
106
|
+
backup of database, files and credentials before destructive recovery.
|
|
107
|
+
|
|
108
|
+
## Repository account connections and releases
|
|
109
|
+
|
|
110
|
+
`repository login URL` saves a CMS PAT supplied by `--token-stdin` or
|
|
111
|
+
`ULVIA_REPOSITORY_TOKEN`, pinned to the origin and Repository identity. Ordinary
|
|
112
|
+
Repository accounts can claim namespaces and publish. Logout removes the local
|
|
113
|
+
connection without revoking the remote token. Client configuration uses
|
|
114
|
+
`$XDG_CONFIG_HOME/ulvia`, `~/.config/ulvia` or explicit `ULVIA_CONFIG_DIR`;
|
|
115
|
+
`ULVIA_DATA_DIR` alone isolates it under `<data>/config`. Files are private.
|
|
115
116
|
|
|
116
117
|
```bash
|
|
117
|
-
ulvia
|
|
118
|
-
ulvia
|
|
119
|
-
ulvia
|
|
118
|
+
ulvia repository login https://repository.example.com --token-stdin
|
|
119
|
+
ulvia namespace claim example
|
|
120
|
+
ulvia release /path/to/resources --recursive
|
|
121
|
+
ulvia push all
|
|
122
|
+
ulvia repository logout
|
|
120
123
|
```
|
|
121
124
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
shared Provider image with retention checks and rollback on activation failure.
|
|
128
|
-
The Repository has no separate image, port, service, or deployment lifecycle.
|
|
129
|
-
|
|
130
|
-
`repository login URL` verifies the Repository identity and saves a shared CMS
|
|
131
|
-
PAT supplied through `ULVIA_REPOSITORY_TOKEN` or `--token-stdin`. Ordinary
|
|
132
|
-
Repository accounts can claim namespaces and publish without CMS administrator
|
|
133
|
-
privileges. Login pins both the origin and Repository identity; writes refuse
|
|
134
|
-
redirects and identity changes. Logout deletes the connection and saved PAT
|
|
135
|
-
without revoking the remote token.
|
|
136
|
-
|
|
137
|
-
Client configuration lives in `$XDG_CONFIG_HOME/ulvia/config.json` or
|
|
138
|
-
`~/.config/ulvia/config.json`. Files use mode 0600, directories 0700.
|
|
139
|
-
`ULVIA_CONFIG_DIR` overrides that location; `ULVIA_DATA_DIR` alone isolates
|
|
140
|
-
client configuration under `<data>/config`. Namespaces, accounts, uploads and
|
|
141
|
-
releases belong to their CMS instance's Provider storage. Startup never claims
|
|
142
|
-
or reassigns a namespace. See the
|
|
143
|
-
[installation guide](../../../docs/installation/README.md#9-repository-cms-instance)
|
|
144
|
-
and [Repository architecture](../../../docs/architecture/community-repository.md).
|
|
145
|
-
|
|
146
|
-
| Command | Provider tenant | Edge container |
|
|
147
|
-
| --- | --- | --- |
|
|
148
|
-
| `services start` | Does not create one | Does not start one |
|
|
149
|
-
| `instance create <name>` | Provisions one durable tenant | Creates and starts its Edge |
|
|
150
|
-
| `instance start <name>` | Reuses the existing tenant | Starts only that Edge |
|
|
151
|
-
| `start` | Never provisions | Starts every existing Edge after shared services |
|
|
152
|
-
|
|
153
|
-
`instance credentials <name>` prints only that administrator's email and
|
|
154
|
-
password. Provider operator and instance bearer tokens remain in
|
|
155
|
-
private runtime files. Shared services and every instance have independent
|
|
156
|
-
`stop`, `status`, and `logs` boundaries. Software upgrades are explicit and
|
|
157
|
-
component-scoped through `upgrade <component> --version <exact-version>`.
|
|
158
|
-
Normal starts always reuse the installed digest and never follow a newer tag.
|
|
159
|
-
First startup validates cached exact-version images and downloads only missing
|
|
160
|
-
images. Explicit upgrades still pull their requested tag.
|
|
161
|
-
`reset --yes`
|
|
162
|
-
removes shared Compose projects, instances, shared state and local repository
|
|
163
|
-
releases, including accounts hosted by this local Provider. Independently deployed
|
|
164
|
-
Repositories and the CLI's saved Repository connection are preserved. It does not
|
|
165
|
-
inspect or modify the current working directory.
|
|
166
|
-
`release <resource-directory>` reads `definition.json` and routes by `kind`:
|
|
125
|
+
Client connections and authored release caches are independent of site Repository
|
|
126
|
+
settings. Publication never installs resources into a site automatically.
|
|
127
|
+
|
|
128
|
+
`release <resource-directory>` accepts a trusted local `ulvia.release.ts` entry
|
|
129
|
+
or reads `definition.json` and routes by `kind`:
|
|
167
130
|
`collection`, `contract`, or `provider-manifest`. It validates and stores one
|
|
168
131
|
immutable release. A provider manifest must reference exact contract releases
|
|
169
132
|
already in the local repository. Release does not connect to or test a provider.
|
|
170
133
|
`release <directory> --recursive` discovers authored resource roots below a
|
|
171
134
|
folder, stopping before nested Bloc definitions. It orders contracts by
|
|
172
|
-
inheritance
|
|
135
|
+
inheritance, then prepares Provider manifests and collection dependencies.
|
|
173
136
|
Existing local dependencies are reused. Source admission happens
|
|
174
137
|
before any resource is stored; each resource is committed separately, so a
|
|
175
138
|
storage or publication conflict can leave a partial batch. Retrying identical
|
|
@@ -179,10 +142,18 @@ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
|
|
|
179
142
|
explicit separate command.
|
|
180
143
|
|
|
181
144
|
```bash
|
|
182
|
-
|
|
183
|
-
|
|
145
|
+
# Official distribution, without changing the personal release cache:
|
|
146
|
+
bun run build --version VERSION
|
|
147
|
+
bun run publish --version VERSION
|
|
148
|
+
# Generic manual preparation still writes to the personal release cache:
|
|
149
|
+
ulvia release infra/releases
|
|
184
150
|
```
|
|
185
151
|
|
|
152
|
+
The official build and the trusted local `ulvia.release.ts` entry share the same
|
|
153
|
+
SDK inventory and compiler for feature contracts, manifest claims and bootstrap. See the
|
|
154
|
+
[SDK workflow](https://github.com/matthias-bernouy/CMS/blob/e5bd135c8e692867eb6fc298ff6c36be0c4ad6cc/docs/development/sdk-releases.md) for explicit versions,
|
|
155
|
+
source-module rules and generated runtime attachment.
|
|
156
|
+
|
|
186
157
|
Contract fixture assets declared in `definition.json` are read from
|
|
187
158
|
`fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
|
|
188
159
|
different content fails. Local release storage is a private CLI cache, not an
|
|
@@ -198,7 +169,8 @@ object. Optional `mocks/**/*.json` fragments contain one mock plus its explicit
|
|
|
198
169
|
`capabilityId`; mocks embedded in capability fragments reject. The compiler
|
|
199
170
|
sorts capabilities and mocks by their declared IDs, so paths never affect the
|
|
200
171
|
immutable digest. `definition.json` cannot contain an inline `capabilities`
|
|
201
|
-
array
|
|
172
|
+
array in this JSON source format. SDK features instead use `defineFeature` and
|
|
173
|
+
explicit capabilities/mocks, producing the same admitted release format.
|
|
202
174
|
|
|
203
175
|
`push <publisher/id@version>` infers the kind from local cached releases. If the
|
|
204
176
|
same coordinate exists in several catalogues, specify `push contract`,
|
|
@@ -206,7 +178,7 @@ same coordinate exists in several catalogues, specify `push contract`,
|
|
|
206
178
|
an explicit kind and downloads and re-admits one exact coordinate locally.
|
|
207
179
|
|
|
208
180
|
`push all` publishes every non-yanked release in the local cache, independently
|
|
209
|
-
of the working directory. It orders contract inheritance
|
|
181
|
+
of the working directory. It orders contract inheritance,
|
|
210
182
|
then providers and known local collection dependencies. All artifacts and every
|
|
211
183
|
namespace's account ownership are checked before the first upload. No namespace
|
|
212
184
|
is implicitly claimed and releases without usable account credentials are not silently skipped.
|
|
@@ -230,7 +202,7 @@ lengths and SHA-256 digests, and makes the artifact visible last. Exact retries
|
|
|
230
202
|
are idempotent; different bytes at an existing coordinate reject.
|
|
231
203
|
|
|
232
204
|
The protocol and exact-coordinate client live in
|
|
233
|
-
`@bernouy/
|
|
205
|
+
`@bernouy/repository/repository/publication`. The CLI and CMS authoring
|
|
234
206
|
implementation share those clients. The official Provider composes the domain
|
|
235
207
|
service and persistence for explicitly enabled Repository instances; Edge
|
|
236
208
|
exposes the selected admitted contract. The Repository uses ordinary CMS capabilities and account PATs.
|
|
@@ -280,32 +252,28 @@ ID, and discovery stops there so `settings/definition.json` is never mistaken
|
|
|
280
252
|
for a nested Bloc. Intermediate grouping directories contain only directories
|
|
281
253
|
and do not affect release identity.
|
|
282
254
|
|
|
283
|
-
The Provider image bundles admitted contracts,
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
from the
|
|
255
|
+
The production Provider image bundles admitted system contracts, documentation
|
|
256
|
+
and the Provider manifest, without authored collections or starter assets. An
|
|
257
|
+
incomplete snapshot fails explicitly; bootstrap does not fall back to the network.
|
|
258
|
+
Restart preserves existing accounts, namespace ownership and edited Pages and
|
|
259
|
+
reopens ready instances from their persisted execution. Generate the API-only
|
|
260
|
+
snapshot from the SDK feature inventory with:
|
|
289
261
|
|
|
290
262
|
```bash
|
|
291
|
-
bun run
|
|
263
|
+
bun run build
|
|
292
264
|
```
|
|
293
265
|
|
|
294
266
|
That command neither publishes to a running repository nor upgrades an existing
|
|
295
|
-
instance.
|
|
296
|
-
|
|
297
|
-
|
|
267
|
+
instance. Collections are built and published only from explicitly supplied
|
|
268
|
+
sources; no starter collection is included in this command.
|
|
269
|
+
For individual manual releases, use `release` in dependency order:
|
|
270
|
+
exact parent contracts before specializations, then Provider manifests and collection dependencies.
|
|
271
|
+
Publication, system installation transitions, collection upgrades and container
|
|
298
272
|
image replacement remain separate actions.
|
|
299
273
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
The current baseline uses fresh `1.0.0` official releases and `v1` local state.
|
|
305
|
-
Each named instance uses `<name>.localhost` unless an explicit domain is supplied;
|
|
306
|
-
`default` is an ordinary name. Repository hosting uses a CMS instance with the
|
|
307
|
-
`repository@1.0.0` profile. Client PAT connections and local release caches
|
|
308
|
-
are separate from the shared services and instance lifecycle.
|
|
274
|
+
Official releases evolve independently. Each feature owns its contract version;
|
|
275
|
+
the Provider manifest owns its version, and local state formats remain `v1`. This is source metadata, not evidence that a matching image
|
|
276
|
+
has been published. Collections are supplied and versioned by their authors.
|
|
309
277
|
|
|
310
278
|
## Collection examples
|
|
311
279
|
|
|
@@ -314,4 +282,25 @@ exports collection example frames, generated PNGs, an interactive local explorer
|
|
|
314
282
|
provenance manifest. Screenshots require the Playwright Chromium browser
|
|
315
283
|
(`bunx playwright@1.64.1 install chromium`). Dependencies and required contracts are
|
|
316
284
|
resolved explicitly from local sources/cache; preview never publishes. See
|
|
317
|
-
[collection examples](
|
|
285
|
+
[collection examples](https://github.com/matthias-bernouy/CMS/blob/e5bd135c8e692867eb6fc298ff6c36be0c4ad6cc/docs/blocs/examples.md) for source and release formats.
|
|
286
|
+
|
|
287
|
+
### Editable collection publication
|
|
288
|
+
|
|
289
|
+
Collection `release` captures a bounded immutable source snapshot before building
|
|
290
|
+
it in the local Repository cache. It retains sources alongside the admitted
|
|
291
|
+
release before making it visible locally. This uses the same source build engine
|
|
292
|
+
as the remote Repository and works offline with the local contract catalogue;
|
|
293
|
+
it starts no additional Repository server.
|
|
294
|
+
|
|
295
|
+
Collection `push` uploads the retained source snapshot and its exact binary
|
|
296
|
+
assets, then follows the remote Repository's durable build operation. Editing the
|
|
297
|
+
working directory after `release` does not alter the pushed version. The server
|
|
298
|
+
must reproduce the reviewed release digest before publication; a compiler or
|
|
299
|
+
contract-catalogue difference refuses publication rather than silently changing
|
|
300
|
+
the release. Collection release modules must also supply `sourceJson`.
|
|
301
|
+
|
|
302
|
+
Pulled or older compiled-only cache entries remain readable, but can only be
|
|
303
|
+
replayed to a Repository already containing that exact release. Publishing one
|
|
304
|
+
to a new Repository requires its original editable sources and an explicit
|
|
305
|
+
release. No source reconstruction runs. Contract and Provider manifest flows
|
|
306
|
+
are unchanged.
|