@cyaxis/ulvia 1.0.12 → 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,130 @@
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 ./my-collection
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.3.0 --repository https://repository.example
48
- bun run ulvia -- pull collection example/ui@1.0.0 --repository https://repository.example
49
- bun run ulvia -- yank collection example/ui@1.0.0 --repository https://repository.example --reason "Superseded"
50
- bun run ulvia -- restore collection example/ui@1.0.0 --repository https://repository.example
51
- bun run ulvia -- prune
71
+ ulvia upgrade --version STACK_VERSION
52
72
  ```
53
73
 
54
- `example/ui` is a hypothetical collection to be authored and published explicitly;
55
- no official starter collection is bundled.
56
-
57
- The stack version above is an example of an exact published image tag. Workspace
58
- source has no embedded initial stack version: its first `services start`
59
- requires `--version`. Packaged releases embed that default at build time. Later
60
- starts reuse installed digests. Building workspace source does not replace
61
- running images or upgrade installed collections.
62
-
63
- The lifecycle commands manage the same Docker Compose projects for loopback and
64
- public installations from any directory. Persistent
65
- data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
66
- `ULVIA_DATA_DIR` remains an explicit isolation override for tests and CI. The
67
- CLI stores authored releases in `<data>/repository`. Shared Provider,
68
- MongoDB, proxy, files, secrets and logs live below `<data>/services`; each
69
- stateless Edge has independent state and logs below `<data>/instances/<name>`.
70
- The CLI never starts application servers, supervises their PIDs, or builds
71
- software images. It pulls only the canonical public images under
72
- `docker.io/cyaxis`, validates their Ulvia component and stack-API labels, and
73
- stores the immutable repository digest selected for each component.
74
-
75
- The first lifecycle command creates a safe installation configuration bound to
76
- `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:
77
82
 
78
83
  ```bash
79
- ulvia configure network \
80
- --bind 0.0.0.0 \
81
- --http-port 80 \
82
- --tls acme \
83
- --https-port 443 \
84
- --acme-email ops@example.com
85
- ulvia start
86
- 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
87
87
  ```
88
88
 
89
- The configuration is persisted under `<data>/services/installation.json` and
90
- is not a per-start mode. ACME requires `0.0.0.0` and every instance in an ACME
91
- installation requires an explicit DNS domain. Network configuration is locked
92
- after the first instance because its canonical Edge URL is part of Provider
93
- provisioning. The Provider operator port remains loopback-only; a Repository instance is
94
- exposed through its own Edge and the shared proxy.
95
-
96
- `services start` starts only the shared proxy, MongoDB and Provider.
97
- On first initialization it uses the exact version embedded by `cli:build`, or
98
- an explicit `services start --version <version>` override. Later starts reuse
99
- the persisted digests and reject a conflicting `--version`; component changes
100
- must go through `upgrade`.
101
- `instance create` provisions one isolated Provider tenant and immediately starts
102
- its dedicated Edge. `instance start` restarts only an already-provisioned
103
- instance's Edge. All Edges use the shared proxy port: an instance named
104
- `default` is available at `http://default.localhost:5100`, while an instance such
105
- as `preview` uses `http://preview.localhost:5100`.
106
- `ULVIA_HTTP_PORT` and `ULVIA_PROVIDER_PORT` provide
107
- initial isolation defaults for tests and CI. Interactive configuration belongs
108
- to `ulvia configure network`. The Provider still listens on its canonical port
109
- 5103 inside the private Docker network; only its operator port on the host
110
- changes.
111
- `start` is the idempotent convenience command for shared services plus every
112
- previously created local instance; it never creates an implicit instance.
113
-
114
- The lifecycle boundary is deliberate:
115
-
116
- A Repository is an ordinary named CMS instance:
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.
117
116
 
118
117
  ```bash
119
- ulvia services start
120
- ulvia instance create registry
121
- ulvia instance status registry
122
- ulvia instance credentials 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
123
123
  ```
124
124
 
125
- Open its `/.cms/setup`, sign in and choose **A new Repository**. The other
126
- buttons accept a Repository address or select `https://repo.ulvia.fr`.
127
- Creation installs system APIs and the administrator, with zero collections and
128
- Pages. Repository settings belong to this instance; there is no `--profile`,
129
- `upgrade-profile`, or shared Repository environment setting. Changing sources
130
- preserves installed pins. An empty site can finish setup offline.
131
-
132
- `upgrade provider --version VERSION` replaces the shared image with retention
133
- checks and rollback on activation failure. Installed resources and credentials
134
- remain in Provider storage; explicit contract/collection upgrades use their
135
- admitted workflows. Registry needs no separate image, service or port.
136
-
137
- `repository login URL` verifies the Repository identity and saves a shared CMS
138
- PAT supplied through `ULVIA_REPOSITORY_TOKEN` or `--token-stdin`. Ordinary
139
- Repository accounts can claim namespaces and publish without CMS administrator
140
- privileges. Login pins both the origin and Repository identity; writes refuse
141
- redirects and identity changes. Logout deletes the connection and saved PAT
142
- without revoking the remote token.
143
-
144
- Client configuration lives in `$XDG_CONFIG_HOME/ulvia/config.json` or
145
- `~/.config/ulvia/config.json`. Files use mode 0600, directories 0700.
146
- `ULVIA_CONFIG_DIR` overrides that location; `ULVIA_DATA_DIR` alone isolates
147
- client configuration under `<data>/config`. Namespaces, accounts, uploads and
148
- releases belong to their CMS instance's Provider storage. Startup never claims
149
- or reassigns a namespace. See the
150
- [installation guide](../../../docs/installation/README.md#9-repository-cms-instance)
151
- and [Repository architecture](../../../docs/architecture/community-repository.md).
152
-
153
- | Command | Provider tenant | Edge container |
154
- | --- | --- | --- |
155
- | `services start` | Does not create one | Does not start one |
156
- | `instance create <name>` | Provisions one durable tenant | Creates and starts its Edge |
157
- | `instance start <name>` | Reuses the existing tenant | Starts only that Edge |
158
- | `start` | Never provisions | Starts every existing Edge after shared services |
159
-
160
- `instance credentials <name>` prints only that administrator's email and
161
- password. Provider operator and instance bearer tokens remain in
162
- private runtime files. Shared services and every instance have independent
163
- `stop`, `status`, and `logs` boundaries. Software upgrades are explicit and
164
- component-scoped through `upgrade <component> --version <exact-version>`.
165
- Normal starts always reuse the installed digest and never follow a newer tag.
166
- First startup validates cached exact-version images and downloads only missing
167
- images. Explicit upgrades still pull their requested tag.
168
- `reset --yes`
169
- removes shared Compose projects, instances, shared state and local repository
170
- releases, including accounts hosted by this local Provider. Independently deployed
171
- Repositories and the CLI's saved Repository connection are preserved. It does not
172
- inspect or modify the current working directory.
125
+ Client connections and authored release caches are independent of site Repository
126
+ settings. Publication never installs resources into a site automatically.
127
+
173
128
  `release <resource-directory>` accepts a trusted local `ulvia.release.ts` entry
174
129
  or reads `definition.json` and routes by `kind`:
175
130
  `collection`, `contract`, or `provider-manifest`. It validates and stores one
@@ -187,15 +142,16 @@ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
187
142
  explicit separate command.
188
143
 
189
144
  ```bash
190
- ulvia release infra/releases
191
- bun run release:official
192
- # Equivalent SDK source entry:
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:
193
149
  ulvia release infra/releases
194
150
  ```
195
151
 
196
- The official build uses a trusted local `ulvia.release.ts` entry so all SDK
197
- features, manifest claims and the bootstrap share the same inventory and compiler. See the
198
- [SDK workflow](../../../docs/development/sdk-releases.md) for explicit versions,
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,
199
155
  source-module rules and generated runtime attachment.
200
156
 
201
157
  Contract fixture assets declared in `definition.json` are read from
@@ -304,7 +260,7 @@ reopens ready instances from their persisted execution. Generate the API-only
304
260
  snapshot from the SDK feature inventory with:
305
261
 
306
262
  ```bash
307
- bun run generate:official-bootstrap
263
+ bun run build
308
264
  ```
309
265
 
310
266
  That command neither publishes to a running repository nor upgrades an existing
@@ -315,17 +271,9 @@ exact parent contracts before specializations, then Provider manifests and colle
315
271
  Publication, system installation transitions, collection upgrades and container
316
272
  image replacement remain separate actions.
317
273
 
318
- `instance create` provisions the named instance through the Provider operator
319
- API, then starts its Edge. Connection review validates the runtime report and
320
- exact manifest claims. Provider behavior is covered by implementation-owned tests.
321
-
322
- Official releases evolve independently: the current installations contract and
323
- Provider manifest use `1.3.0`; local formats remain `v1`. Collections are supplied
324
- and versioned by their authors.
325
- Each named instance uses `<name>.localhost` unless an explicit domain is supplied;
326
- `default` is an ordinary name. Repository hosting uses a CMS instance with the
327
- explicit Registry installation. Client PAT connections and local release caches
328
- 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.
329
277
 
330
278
  ## Collection examples
331
279
 
@@ -334,4 +282,25 @@ exports collection example frames, generated PNGs, an interactive local explorer
334
282
  provenance manifest. Screenshots require the Playwright Chromium browser
335
283
  (`bunx playwright@1.64.1 install chromium`). Dependencies and required contracts are
336
284
  resolved explicitly from local sources/cache; preview never publishes. See
337
- [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.