@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/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 from a fresh Ubuntu host to a running local or public
6
- site, follow the [canonical installation guide](INSTALLATION.md).
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 contains private source code. Official releases are
9
- bundled without workspace dependencies and published publicly as
10
- `@cyaxis/ulvia`:
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 add --global @cyaxis/ulvia@latest
14
- ulvia --help
19
+ bun run build --version VERSION
15
20
  ```
16
21
 
17
- From the workspace, build and publish one exact release with:
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 cli:build --version 0.0.3 --stack-version 0.0.1-beta
21
- bun run cli:publish --version 0.0.3
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 build creates a checked npm archive and SHA-256 receipt below
25
- `artifacts/cli`. The CLI package version and its compatible initial Docker stack
26
- version are independent and both are sealed into that receipt. Publishing
27
- accepts only the exact pair, targets the public npm registry, and uses the
28
- `next` tag for prereleases or `latest` for stable versions. It requires npm
29
- credentials configured outside the repository.
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
- bun run ulvia -- configure network
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
- The stack version above is an example of an exact published image tag. Workspace
55
- source has no embedded initial stack version: its first `services start`
56
- requires `--version`. Packaged releases embed that default at build time. Later
57
- starts reuse installed digests. Building workspace source does not replace
58
- running images or upgrade installed collections.
59
-
60
- The lifecycle commands manage the same Docker Compose projects for loopback and
61
- public installations from any directory. Persistent
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 network \
77
- --bind 0.0.0.0 \
78
- --http-port 80 \
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
- The configuration is persisted under `<data>/services/installation.json` and
87
- is not a per-start mode. ACME requires `0.0.0.0` and every instance in an ACME
88
- installation requires an explicit DNS domain. Network configuration is locked
89
- after the first instance because its canonical Edge URL is part of Provider
90
- provisioning. The Provider operator port remains loopback-only; a Repository instance is
91
- exposed through its own Edge and the shared proxy.
92
-
93
- `services start` starts only the shared proxy, MongoDB and Provider.
94
- On first initialization it uses the exact version embedded by `cli:build`, or
95
- an explicit `services start --version <version>` override. Later starts reuse
96
- the persisted digests and reject a conflicting `--version`; component changes
97
- must go through `upgrade`.
98
- `instance create` provisions one isolated Provider tenant and immediately starts
99
- its dedicated Edge. `instance start` restarts only an already-provisioned
100
- instance's Edge. All Edges use the shared proxy port: an instance named
101
- `default` is available at `http://default.localhost:5100`, while an instance such
102
- as `preview` uses `http://preview.localhost:5100`.
103
- `ULVIA_HTTP_PORT` and `ULVIA_PROVIDER_PORT` provide
104
- initial isolation defaults for tests and CI. Interactive configuration belongs
105
- to `ulvia configure network`. The Provider still listens on its canonical port
106
- 5103 inside the private Docker network; only its operator port on the host
107
- changes.
108
- `start` is the idempotent convenience command for shared services plus every
109
- previously created local instance; it never creates an implicit instance.
110
-
111
- The lifecycle boundary is deliberate:
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 services start
118
- ulvia instance create registry --profile repository@1.0.0
119
- ulvia instance status registry
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
- The Provider advertises supported profiles through its protected operator API.
123
- The CLI persists the exact selected profile; restart reuses that selection and
124
- its instance credentials. `instance upgrade-profile registry ID@VERSION` requests
125
- an explicit supported transition within the same application ID and saves it
126
- only after acknowledgement. `upgrade provider --version VERSION` replaces the
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 and capability requirements, then prepares providers and collections.
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
- ulvia release packages/official-repository/contracts --recursive
183
- ulvia release packages/official-repository --recursive
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: the recursive source tree is the only authored contract format.
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 and requirements,
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/cms-repository/repository/publication`. The CLI and CMS authoring
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, manifests, collection assets and
284
- documentation required by its shipped profiles. The local snapshot feeds the
285
- same provisioning and admission flow as remote sources. An incomplete snapshot
286
- fails explicitly; bootstrap does not fall back to the network. Restart preserves
287
- existing accounts, namespace ownership and edited Pages. Generate the snapshot
288
- from the authoritative authored resources with:
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 generate:official-bootstrap
263
+ bun run build
292
264
  ```
293
265
 
294
266
  That command neither publishes to a running repository nor upgrades an existing
295
- instance. For individual manual releases, use `release` in dependency order:
296
- exact contract dependencies before dependent contracts and provider manifests.
297
- Publication, provider profile transitions, collection upgrades and container
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
- `instance create` provisions the named instance through the Provider operator
301
- API, then starts its Edge. Connection review validates the runtime report and
302
- exact manifest claims. Provider behavior is covered by implementation-owned tests.
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](../../../docs/blocs/examples.md) for source and release formats.
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.