@cyaxis/ulvia 1.0.7 → 1.0.12

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 CHANGED
@@ -71,53 +71,24 @@ The site is available at `http://my-site.localhost:5100`. The credentials
71
71
  command prints the initial administrator email and password. It never prints
72
72
  the Provider, Repository, encryption, or instance service secrets.
73
73
 
74
- The Provider uses `https://repo.ulvia.fr` by default for resource discovery
75
- and connected-account publications. The shared stack contains the proxy, MongoDB and Provider. Repository hosting
76
- is selected explicitly on a named CMS instance.
77
-
78
- When initializing a node, select another Repository by setting
79
- `CMS_REPOSITORY_URL` on the first configuration or startup command. For an
80
- isolated local installation:
81
-
82
- ```bash
83
- CMS_REPOSITORY_URL=http://repository:3000 \
84
- CMS_REPOSITORY_ALLOW_INSECURE_HTTP=true ulvia services start
85
- ```
86
-
87
- Here `repository:3000` is a Repository CMS Edge address reachable from the
88
- Provider containers. Initial provisioning uses the bundled application profile
89
- before the remote catalogue is available.
90
-
91
- The selected connection is persisted as `repository.url` and
92
- `repository.allowInsecureHttp` in
93
- `~/.local/share/ulvia/services/installation.json`. Later environment changes
94
- do not replace an existing connection. To change it, update those fields and
95
- run `ulvia services start`. The Provider bundles admitted resources needed for initial provisioning; it
96
- does not need to contact this Repository to bootstrap its shipped profiles.
97
- Remote discovery and publication still require the configured Repository. An
98
- origin remains required in configuration even when it is unavailable at bootstrap.
99
- Creating a Repository instance neither changes that connection nor publishes the
100
- image-owned bootstrap artifacts into its public catalogue.
101
-
102
- Ulvia deliberately separates shared services from sites:
103
-
104
- | Command | Responsibility |
105
- | --- | --- |
106
- | `ulvia services start` | Starts the proxy, MongoDB and Provider. |
107
- | `ulvia instance create <name>` | Provisions one Provider tenant and starts its Edge. |
108
- | `ulvia instance start <name>` | Restarts an existing instance without provisioning it again. |
109
- | `ulvia start` | Starts shared services and every existing instance; it creates nothing. |
110
-
111
- List and inspect the installation at any time:
112
-
113
- ```bash
114
- ulvia services status
115
- ulvia instance list
116
- ulvia instance status my-site
117
- ```
118
-
119
- Persistent data lives below `$XDG_DATA_HOME/ulvia` or
120
- `~/.local/share/ulvia`. Commands can be run from any working directory.
74
+ Open `http://my-site.localhost:5100/.cms/setup` and use those credentials. Fresh
75
+ instances create zero collections and Pages. Choose an empty site or explicitly
76
+ review a recipe from a published collection; no starter or administration site
77
+ is bundled. Empty completion leaves `/` returning 404 until a Page is published.
78
+ See [first published Page](../product/first-published-page.md) for the current API flow.
79
+
80
+ Setup first offers **A Repository address**, **The official Repository**
81
+ (`https://repo.ulvia.fr`), or **A new Repository** on this instance. Then choose
82
+ an empty site or review a published collection recipe. The URL is stored per
83
+ instance; there is no global Repository environment variable or service setting.
84
+ The address must be reachable from the Provider. HTTP origins are an explicit
85
+ choice; credentials, queries and fragments are forbidden in settings URLs.
86
+
87
+ A new Repository installs Registry from the system resources already in the
88
+ image and selects this site’s public Edge origin. Its catalogue starts empty.
89
+ Self-origin calls use the known private Edge transport; no remote catalogue is
90
+ needed for creation or empty completion. Changing a Repository URL affects future
91
+ discovery/imports, preserving installed resources and Pages.
121
92
 
122
93
  ## 4. Daily Operations
123
94
 
@@ -162,8 +133,8 @@ and Edge images. A failed activation attempts
162
133
  to restart the previous image, but this does not restore changed database or
163
134
  file contents and is not an atomic rollback across all instances.
164
135
  Take a complete backup before an upgrade involving persisted data. Internal
165
- schema migrations and interrupted-upgrade/restore drills remain
166
- [open platform work](../TODO.md#internal-persistence-migrations).
136
+ schema migrations and interrupted-upgrade/restore drills require explicit
137
+ implementation and deployment-level verification.
167
138
 
168
139
  ## 6. Public Domain And HTTPS
169
140
 
@@ -204,7 +175,7 @@ The CLI has no general backup/restore command. Stop each Edge with
204
175
  `ulvia instance stop <name>`, then stop shared services before copying their
205
176
  data. Restore and verify a complete backup in an isolated installation before
206
177
  treating it as a recovery guarantee; do not rely on image fallback to recover
207
- data. See [operational recovery](../TODO.md#backup-and-operational-recovery).
178
+ data.
208
179
 
209
180
  `reset` permanently removes Ulvia-owned local state:
210
181
 
@@ -249,24 +220,24 @@ For a local installation:
249
220
 
250
221
  ```bash
251
222
  ulvia services start
252
- ulvia instance create registry --profile ulvia.repository@1.0.0
223
+ ulvia instance create registry
253
224
  ulvia instance status registry
254
225
  ulvia instance credentials registry
255
226
  ```
256
227
 
257
228
  The Registry API is available below
258
- `http://registry.localhost:5100/.cms/call/ulvia.repository`. Its public identity
229
+ `http://registry.localhost:5100/.cms/call/ulvia/repository`. Its public identity
259
230
  endpoint is `GET /v1/info` relative to that prefix. Ordinary CMS instances do not
260
- expose this contract. The profile creates ordinary CMS Pages for the public
261
- catalogue, search, resource details, registration/login and personal namespaces,
262
- publications and PAT management. These Pages use the `ulvia-repository` collection
263
- and shared `ulvia-official` resources.
231
+ expose this contract. Open `/.cms/setup`, sign in and choose **A new Repository**
232
+ to activate it. Creation starts with an administrator and system APIs,
233
+ without any collection or Page. Publish resources through the CLI/API and install
234
+ a website explicitly if needed.
264
235
 
265
236
  For public hosting, configure network exposure and ACME as described in section 6
266
237
  before creating instances, then create the application on its public domain:
267
238
 
268
239
  ```bash
269
- ulvia instance create registry --domain repository.example.com --profile ulvia.repository@1.0.0
240
+ ulvia instance create registry --domain repository.example.com
270
241
  ```
271
242
 
272
243
  Replace the example domain with a domain routed to this host. The same shared
@@ -275,7 +246,7 @@ proxy handles its HTTPS certificate. Provider management remains on loopback.
275
246
  ### Publisher Accounts And Credentials
276
247
 
277
248
  Registration, password login and PAT management use the normal Access bindings
278
- under `/.cms/call/ulvia.cms.access`. Registration follows the instance policy.
249
+ under `/.cms/call/ulvia/cms.access`. Registration follows the instance policy.
279
250
  An ordinary account can claim and publish; it does not need CMS administrator
280
251
  privileges. The protected publisher operations use a shared CMS PAT.
281
252
 
@@ -308,7 +279,7 @@ Publication never installs a collection on a site.
308
279
  Namespace claims are atomic and limited to 32 owned names per account. Transfer
309
280
  uses an explicit target account and expected revision. Suspension retains the
310
281
  name; account deletion is refused while it owns namespaces. Startup does not
311
- reserve or reclaim names, including `ulvia.official`.
282
+ reserve or reclaim names, including `ulvia`.
312
283
 
313
284
  ### Restart And Updates
314
285
 
@@ -326,11 +297,8 @@ digests, checks Provider retention before replacing it, and attempts to restore
326
297
  the previous image if activation fails. Accounts, ownership, releases, Pages and
327
298
  credentials remain in the normal CMS storage.
328
299
 
329
- A profile change is separate from an image replacement:
330
- `ulvia instance upgrade-profile registry ID@VERSION`. The target must be a
331
- supported explicit transition shipped by the Provider and retain the
332
- `ulvia.repository` application ID. The CLI saves the exact new reference only
333
- after the Provider acknowledges it. Restart never selects a different profile.
300
+ Installed contract and collection upgrades are separate from image replacement.
301
+ They use explicit admitted Installations workflows; restart never selects new pins.
334
302
 
335
303
  Back up the Provider database, file storage, matching encryption credentials and
336
304
  private instance configuration together, following section 7. The Repository is
package/README.md CHANGED
@@ -41,16 +41,19 @@ bun run ulvia -- services stop
41
41
  bun run ulvia -- upgrade edge --version 0.0.1-beta
42
42
  bun run ulvia -- upgrade provider --version 0.0.1-beta
43
43
  bun run ulvia -- reset --yes
44
- bun run ulvia -- release packages/official-repository/collections/ulvia-official
44
+ bun run ulvia -- release ./my-collection
45
45
  bun run ulvia -- release /path/to/contract-directory
46
46
  bun run ulvia -- release /path/to/provider-directory
47
- bun run ulvia -- push contract ulvia.official/ulvia.cms.installations@1.0.0 --repository https://repository.example
48
- bun run ulvia -- pull collection ulvia.official/ulvia-official@1.0.0 --repository https://repository.example
49
- bun run ulvia -- yank collection ulvia.official/ulvia-official@1.0.0 --repository https://repository.example --reason "Superseded"
50
- bun run ulvia -- restore collection ulvia.official/ulvia-official@1.0.0 --repository https://repository.example
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
51
  bun run ulvia -- prune
52
52
  ```
53
53
 
54
+ `example/ui` is a hypothetical collection to be authored and published explicitly;
55
+ no official starter collection is bundled.
56
+
54
57
  The stack version above is an example of an exact published image tag. Workspace
55
58
  source has no embedded initial stack version: its first `services start`
56
59
  requires `--version`. Packaged releases embed that default at build time. Later
@@ -110,22 +113,26 @@ previously created local instance; it never creates an implicit instance.
110
113
 
111
114
  The lifecycle boundary is deliberate:
112
115
 
113
- A Repository is an ordinary named CMS instance with an explicit application
114
- profile:
116
+ A Repository is an ordinary named CMS instance:
115
117
 
116
118
  ```bash
117
119
  ulvia services start
118
- ulvia instance create registry --profile ulvia.repository@1.0.0
120
+ ulvia instance create registry
119
121
  ulvia instance status registry
122
+ ulvia instance credentials registry
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.
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.
129
136
 
130
137
  `repository login URL` verifies the Repository identity and saves a shared CMS
131
138
  PAT supplied through `ULVIA_REPOSITORY_TOKEN` or `--token-stdin`. Ordinary
@@ -163,13 +170,14 @@ removes shared Compose projects, instances, shared state and local repository
163
170
  releases, including accounts hosted by this local Provider. Independently deployed
164
171
  Repositories and the CLI's saved Repository connection are preserved. It does not
165
172
  inspect or modify the current working directory.
166
- `release <resource-directory>` reads `definition.json` and routes by `kind`:
173
+ `release <resource-directory>` accepts a trusted local `ulvia.release.ts` entry
174
+ or reads `definition.json` and routes by `kind`:
167
175
  `collection`, `contract`, or `provider-manifest`. It validates and stores one
168
176
  immutable release. A provider manifest must reference exact contract releases
169
177
  already in the local repository. Release does not connect to or test a provider.
170
178
  `release <directory> --recursive` discovers authored resource roots below a
171
179
  folder, stopping before nested Bloc definitions. It orders contracts by
172
- inheritance and capability requirements, then prepares providers and collections.
180
+ inheritance, then prepares Provider manifests and collection dependencies.
173
181
  Existing local dependencies are reused. Source admission happens
174
182
  before any resource is stored; each resource is committed separately, so a
175
183
  storage or publication conflict can leave a partial batch. Retrying identical
@@ -179,16 +187,23 @@ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
179
187
  explicit separate command.
180
188
 
181
189
  ```bash
182
- ulvia release packages/official-repository/contracts --recursive
183
- ulvia release packages/official-repository --recursive
190
+ ulvia release infra/releases
191
+ bun run release:official
192
+ # Equivalent SDK source entry:
193
+ ulvia release infra/releases
184
194
  ```
185
195
 
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,
199
+ source-module rules and generated runtime attachment.
200
+
186
201
  Contract fixture assets declared in `definition.json` are read from
187
202
  `fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
188
203
  different content fails. Local release storage is a private CLI cache, not an
189
204
  HTTP server. `push` publishes it to the configured CMS Repository; its public
190
- catalogue and downloads use admitted `ulvia.repository` bindings under
191
- `/.cms/call/ulvia.repository`. CMS installation and Provider administration
205
+ catalogue and downloads use admitted `ulvia/repository` bindings under
206
+ `/.cms/call/ulvia/repository`. CMS installation and Provider administration
192
207
  consume those public sources. `prune` empties the local cache without deleting
193
208
  service or instance data.
194
209
 
@@ -198,7 +213,8 @@ object. Optional `mocks/**/*.json` fragments contain one mock plus its explicit
198
213
  `capabilityId`; mocks embedded in capability fragments reject. The compiler
199
214
  sorts capabilities and mocks by their declared IDs, so paths never affect the
200
215
  immutable digest. `definition.json` cannot contain an inline `capabilities`
201
- array: the recursive source tree is the only authored contract format.
216
+ array in this JSON source format. SDK features instead use `defineFeature` and
217
+ explicit capabilities/mocks, producing the same admitted release format.
202
218
 
203
219
  `push <publisher/id@version>` infers the kind from local cached releases. If the
204
220
  same coordinate exists in several catalogues, specify `push contract`,
@@ -206,7 +222,7 @@ same coordinate exists in several catalogues, specify `push contract`,
206
222
  an explicit kind and downloads and re-admits one exact coordinate locally.
207
223
 
208
224
  `push all` publishes every non-yanked release in the local cache, independently
209
- of the working directory. It orders contract inheritance and requirements,
225
+ of the working directory. It orders contract inheritance,
210
226
  then providers and known local collection dependencies. All artifacts and every
211
227
  namespace's account ownership are checked before the first upload. No namespace
212
228
  is implicitly claimed and releases without usable account credentials are not silently skipped.
@@ -217,7 +233,7 @@ availability and every immutable artifact. For single pushes, transfer required
217
233
  dependencies first.
218
234
 
219
235
  ```bash
220
- ulvia push ulvia.official/ulvia.cms.emailer@1.0.0
236
+ ulvia push ulvia/cms.emailer@1.0.0
221
237
  ulvia push all
222
238
  ```
223
239
 
@@ -230,7 +246,7 @@ lengths and SHA-256 digests, and makes the artifact visible last. Exact retries
230
246
  are idempotent; different bytes at an existing coordinate reject.
231
247
 
232
248
  The protocol and exact-coordinate client live in
233
- `@bernouy/cms-repository/repository/publication`. The CLI and CMS authoring
249
+ `@bernouy/repository/repository/publication`. The CLI and CMS authoring
234
250
  implementation share those clients. The official Provider composes the domain
235
251
  service and persistence for explicitly enabled Repository instances; Edge
236
252
  exposes the selected admitted contract. The Repository uses ordinary CMS capabilities and account PATs.
@@ -280,31 +296,35 @@ ID, and discovery stops there so `settings/definition.json` is never mistaken
280
296
  for a nested Bloc. Intermediate grouping directories contain only directories
281
297
  and do not affect release identity.
282
298
 
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:
299
+ The production Provider image bundles admitted system contracts, documentation
300
+ and the Provider manifest, without authored collections or starter assets. An
301
+ incomplete snapshot fails explicitly; bootstrap does not fall back to the network.
302
+ Restart preserves existing accounts, namespace ownership and edited Pages and
303
+ reopens ready instances from their persisted execution. Generate the API-only
304
+ snapshot from the SDK feature inventory with:
289
305
 
290
306
  ```bash
291
307
  bun run generate:official-bootstrap
292
308
  ```
293
309
 
294
310
  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
311
+ instance. Collections are built and published only from explicitly supplied
312
+ sources; no starter collection is included in this command.
313
+ For individual manual releases, use `release` in dependency order:
314
+ exact parent contracts before specializations, then Provider manifests and collection dependencies.
315
+ Publication, system installation transitions, collection upgrades and container
298
316
  image replacement remain separate actions.
299
317
 
300
318
  `instance create` provisions the named instance through the Provider operator
301
319
  API, then starts its Edge. Connection review validates the runtime report and
302
320
  exact manifest claims. Provider behavior is covered by implementation-owned tests.
303
321
 
304
- The current baseline uses fresh `1.0.0` official releases and `v1` local state.
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.
305
325
  Each named instance uses `<name>.localhost` unless an explicit domain is supplied;
306
326
  `default` is an ordinary name. Repository hosting uses a CMS instance with the
307
- `ulvia.repository@1.0.0` profile. Client PAT connections and local release caches
327
+ explicit Registry installation. Client PAT connections and local release caches
308
328
  are separate from the shared services and instance lifecycle.
309
329
 
310
330
  ## Collection examples
@@ -87,8 +87,6 @@ services:
87
87
  MODE: PROD
88
88
  NODE_ENV: production
89
89
  CMS_FILES_DIR: /var/lib/cms/files
90
- CMS_REPOSITORY_URL: ${CMS_REPOSITORY_URL:-https://repo.ulvia.fr}
91
- CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "${CMS_REPOSITORY_ALLOW_INSECURE_HTTP:-false}"
92
90
  CMS_SESSION_SECRET: ${ULVIA_PROVIDER_SESSION_SECRET}
93
91
  CMS_KEK_ACTIVE_ID: ${ULVIA_PROVIDER_KEK_ACTIVE_ID}
94
92
  CMS_KEK_RING_JSON: ${ULVIA_PROVIDER_KEK_RING_JSON}