@cyaxis/ulvia 0.1.0-beta → 0.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/INSTALLATION.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # Install Ulvia
2
2
 
3
- This guide installs the Ulvia CLI and creates a first CMS instance on Ubuntu.
3
+ This guide installs the Ulvia CLI and runs a CMS instance or a standalone
4
+ Repository on Ubuntu. For a Repository-only server, follow section 1 and the
5
+ standalone Repository procedure in section 9.
4
6
  It is for operators and site owners; workspace contributors should use the
5
7
  [development guide](../development/README.md).
6
8
 
@@ -204,130 +206,192 @@ the [development and validation guide](../development/README.md).
204
206
 
205
207
  ## 9. Standalone Repository
206
208
 
207
- A public Repository is independent of CMS shared services. It needs Docker and
208
- the CLI, with one persistent local volume and one active server. The commands
209
- below describe the candidate implementation; the exact CLI and image versions
210
- must be published before they can be installed or pulled from a registry.
209
+ This is the standard installation on a dedicated Ubuntu server. The CLI owns
210
+ one Repository deployment and its HTTPS proxy. No CMS instance, Provider or
211
+ database is required.
211
212
 
212
- On the Repository host, configure networking and start the default deployment:
213
+ ### Prepare The Server
214
+
215
+ Complete the Docker Engine, Compose and Bun prerequisites in section 1. The
216
+ account running Ulvia must be able to execute `docker version` and
217
+ `docker compose version` without `sudo`.
218
+
219
+ Before enabling HTTPS:
220
+
221
+ - Point the domain's DNS A record to the server's public IPv4 address.
222
+ - Make inbound TCP ports 80 and 443 reachable and available on the host.
223
+ - Choose a real email address for certificate registration and renewal notices.
224
+
225
+ Replace `repository.example.com`, `ops@example.com` and the example namespace
226
+ `acme` below with your own values. Install the published CLI version:
213
227
 
214
228
  ```bash
215
- ulvia repository configure --tls external --public-url https://repository.example
216
- ulvia repository start --version 0.1.0
217
- ulvia repository status
218
- ulvia repository stop
219
- ulvia repository start
220
- ulvia repository upgrade --version 0.1.1
229
+ bun add --global @cyaxis/ulvia@0.1.0-beta
230
+ ulvia --version
221
231
  ```
222
232
 
223
- The versions above are examples, not a claim that those images are published.
224
- No `global`, `community` or deployment name is required. The CLI pulls an exact
225
- official image, validates its labels and pins its immutable registry digest.
226
- It does not build or publish images. A failed activation attempts to restart the
227
- previous image; it does not reverse data migrations. Back up data before upgrades.
233
+ The CLI bundles `0.1.0-beta` as its initial stack version. No deployment name or
234
+ `global`/`community` qualifier is required.
228
235
 
229
- Choose one persistent network mode:
236
+ ### Start Locally And Claim The Publisher
230
237
 
231
- | Mode | Configuration | Exposure |
232
- | --- | --- | --- |
233
- | Local | `repository configure --tls local --port 5010` | Loopback HTTP only |
234
- | External proxy | `repository configure --tls external --public-url https://repository.example` | Loopback backend; operator supplies the HTTPS proxy |
235
- | Managed ACME | `repository configure --tls acme --public-url https://repository.example --acme-email ops@example.com` | Dedicated proxy on host ports 80/443, plus certificate renewals |
238
+ Start the Repository before exposing it publicly:
236
239
 
237
- Run `repository start` after configuring to apply changes. External proxies
238
- forward to `127.0.0.1:5010` (or the configured port), preserve request bodies and
239
- allow 100 MiB assets plus protocol overhead. Managed ACME requires public DNS
240
- pointing to this host and ports 80/443 available; it cannot share these ports
241
- with another local proxy. It starts only Repository, proxy and ACME containers.
242
- Certificate issuance requires the public domain; local tests validate the
243
- Compose model without issuing a public certificate. `REPOSITORY_PUBLIC_URL`
244
- controls resource links; forwarded headers do not override it.
240
+ ```bash
241
+ ulvia repository start
242
+ ulvia repository status
243
+ curl --fail http://127.0.0.1:5010/readyz
244
+ ```
245
245
 
246
- On an author's machine, save the connection once:
246
+ The endpoint initially binds only to `127.0.0.1:5010`. Create a local signing
247
+ identity and claim the publisher namespace while the server is still private:
247
248
 
248
249
  ```bash
249
- ulvia repository login https://repository.example
250
- ulvia identity list
250
+ ulvia identity create owner
251
+ ulvia repository login http://127.0.0.1:5010 --identity owner
251
252
  ulvia namespace claim acme
252
253
  ulvia namespace status acme
254
+ ```
255
+
256
+ Save a secure backup of the signing identity before continuing. By default its
257
+ private key is `~/.config/ulvia/keys/owner.pem`; preserve the matching client
258
+ configuration too. There is no operator recovery after losing every key copy.
259
+
260
+ Every namespace follows public first claim, including `ulvia.official`. For an
261
+ official Repository, claim that namespace instead of `acme` before public access.
262
+ There is no reserved-name bootstrap or operator publication token.
263
+
264
+ ### Enable Public HTTPS
265
+
266
+ Persist the domain and certificate configuration, then apply it:
267
+
268
+ ```bash
269
+ ulvia repository configure \
270
+ --tls acme \
271
+ --public-url https://repository.example.com \
272
+ --acme-email ops@example.com
273
+
274
+ ulvia repository start
275
+ ulvia repository status
276
+ ```
277
+
278
+ This starts the Repository, a dedicated Nginx proxy and its ACME companion.
279
+ Only the proxy publishes ports 80/443; the Repository's host endpoint stays on
280
+ loopback. Certificates and renewal state persist with the deployment. Issuance
281
+ requires working public DNS and HTTP access to port 80. Container readiness does
282
+ not by itself confirm that the public certificate has been issued.
283
+
284
+ After issuance, verify public access and save the HTTPS connection:
285
+
286
+ ```bash
287
+ curl --fail https://repository.example.com/readyz
288
+ curl --fail https://repository.example.com/v1/repository
289
+ ulvia repository login https://repository.example.com --identity owner
290
+ ulvia namespace status acme
291
+ ```
292
+
293
+ The Repository identity and namespace ownership must match the local endpoint.
294
+ Public catalogue reads need no credentials; writes require the namespace owner's
295
+ signature. Login saves the endpoint and verifies the Repository identity. It
296
+ does not create a bearer-token session; private keys stay on the signing host.
297
+
298
+ ### Publish Resources
299
+
300
+ On a signing machine with the owner identity, release an authored resource and
301
+ push its exact coordinate:
302
+
303
+ ```bash
253
304
  ulvia release /path/to/authored-resource
254
305
  ulvia push contract acme/example.contract@1.0.0
255
- ulvia pull contract acme/example.contract@1.0.0
256
306
  ```
257
307
 
258
- Login creates a default local identity if needed and saves the Repository's
259
- persistent identity. It does not log into a bearer-token session: every mutation
260
- is signed locally. Claim is public, first valid claimant wins. The resource's
261
- `publisherId` must match the owned namespace. Release and push are separate;
262
- dependencies must be released and pushed first. Collections and provider
263
- manifests use `push collection` and `push provider` with exact coordinates.
264
- Publishing an artifact does not install it on a CMS site.
265
-
266
- Create or import named signing identities when needed:
308
+ The development CLI adds recursive release, inferred push kinds and `push all`:
267
309
 
268
310
  ```bash
269
- ulvia identity create official
270
- ulvia identity import imported --key-file /private/existing.pem
271
- ulvia identity use official
272
- ulvia identity public-key official
273
- ulvia repository login https://repository.example --identity official
274
- ulvia identity create replacement
275
- ulvia namespace rotate acme --replacement-identity replacement
276
- ulvia namespace revoke acme --yes
277
- ulvia repository logout
311
+ ulvia release /path/to/resources --recursive
312
+ ulvia push acme/example.contract@1.0.0
313
+ ulvia push all
278
314
  ```
279
315
 
280
- Rotation requires the current owner's key and proof of the replacement key.
281
- Publication automatically selects the saved key matching the current namespace
282
- owner. Revocation is permanent. Losing every copy of an owner key is permanent;
283
- there is no operator recovery. Logout preserves local identities.
316
+ Recursive release prepares sources locally. `push all` publishes every
317
+ non-yanked release in the local cache to the saved Repository, respecting local
318
+ dependency order. It verifies all artifacts and namespace owner keys before
319
+ uploading. A failed batch can leave completed publications; rerun it to resume
320
+ idempotently. A type is required only when a coordinate matches several local
321
+ resource kinds. The published `0.1.0-beta` CLI does not yet include these additions.
322
+
323
+ The resource's `publisherId` must match the owned namespace. Dependencies must
324
+ be released and pushed first. Collections and provider manifests use
325
+ `push collection` and `push provider`. Publishing does not install a collection
326
+ on a CMS site.
327
+
328
+ Other authors use `repository login` and `namespace claim` with their own local
329
+ identities and namespace names. No environment exports are needed.
284
330
 
285
- The official public Repository will use `https://repo.ulvia.fr`. Its namespace
286
- `ulvia.official` follows exactly the same first-claim rule. Initialize it on the
287
- host while the service is still available only over loopback:
331
+ ### Daily Operations And Upgrades
288
332
 
289
333
  ```bash
290
- ulvia repository start --version 0.1.0
291
- ulvia identity create official
292
- ulvia repository login http://127.0.0.1:5010 --identity official
293
- ulvia namespace claim ulvia.official
294
- ulvia repository configure --tls acme --public-url https://repo.ulvia.fr --acme-email ops@ulvia.fr
334
+ ulvia repository status
335
+ ulvia repository stop
295
336
  ulvia repository start
296
- ulvia repository login https://repo.ulvia.fr --identity official
297
- ulvia release /path/to/official-contract
298
- ulvia push contract ulvia.official/example.contract@1.0.0
299
337
  ```
300
338
 
301
- Run the first claim before opening public access. A separate signing machine can
302
- reach the loopback listener through an SSH tunnel instead. There is no reserved
303
- namespace bootstrap or operator token. After the first claim, existing ownership
304
- survives restarts, upgrades, rotations and terminal revocation. Tests use temporary local
305
- repositories; they never contact or publish to `repo.ulvia.fr`.
306
-
307
- Client settings and identities live in `$XDG_CONFIG_HOME/ulvia` or
308
- `~/.config/ulvia`, overridable with `ULVIA_CONFIG_DIR`. `config.json` contains
309
- public keys, key-file references and the active connection; private PEM files
310
- live in `keys/`. Files are private (0600), directories 0700. Preserve secure
311
- backups of keys. Setting only `ULVIA_DATA_DIR` isolates client settings beneath
312
- `<data>/config`, useful for tests or separate installations.
313
-
314
- Deployment configuration lives in `<data>/repository-service/config.json`;
315
- `service.json` records the last applied image and configuration; `data/` holds
316
- Repository identity, namespace history, releases and upload/replay state.
317
- Managed TLS material lives in `proxy/`. Back up the complete stopped deployment
318
- and the matching signing identities. `reset --yes` affects the CMS installation
319
- and local release cache; it preserves independent Repository deployments and
320
- client identities. There is no compatibility path for previous Repository states, deployment names
321
- or token credentials.
322
-
323
- For a contributor's unpublished candidate, use the local Docker regression
324
- runner instead of `repository start`, which intentionally pulls a published
325
- registry image:
339
+ Stopping preserves data, identities and certificates. Starts reuse the installed
340
+ image digest. To upgrade, use `ulvia repository upgrade --version VERSION`,
341
+ replacing `VERSION` with an exact published version. The CLI pulls the tag,
342
+ checks the image labels and pins its immutable digest. A failed activation
343
+ attempts to restart the previous image; it does not reverse data migrations.
344
+ Back up the stopped deployment and signing identities before upgrading.
345
+
346
+ `identity import NAME --key-file PATH` copies an existing private key into a
347
+ managed local identity. Rotation uses `namespace rotate NAMESPACE
348
+ --replacement-identity NAME` and requires both owner and replacement keys.
349
+ Revocation uses `namespace revoke NAMESPACE --yes` and is permanent.
350
+ `repository logout` removes the connection while preserving local keys.
351
+
352
+ ### Configuration And Storage
353
+
354
+ Client configuration lives in `$XDG_CONFIG_HOME/ulvia` or `~/.config/ulvia`,
355
+ overridable with `ULVIA_CONFIG_DIR`. `config.json` contains public keys, private
356
+ key-file references and the active connection; PEM files live in `keys/`.
357
+ Files use mode 0600 and directories 0700. Setting only `ULVIA_DATA_DIR` isolates
358
+ client settings below `<data>/config`.
359
+
360
+ Deployment data defaults to `$XDG_DATA_HOME/ulvia/repository-service` or
361
+ `~/.local/share/ulvia/repository-service`, overridable through `ULVIA_DATA_DIR`:
362
+
363
+ | Path | Content |
364
+ | --- | --- |
365
+ | `config.json` | Desired network configuration |
366
+ | `service.json` | Installed image digest and last applied configuration |
367
+ | `data/` | Repository identity, namespace history, releases and upload/replay state |
368
+ | `proxy/` | Certificates, virtual hosts, HTTP challenges and ACME renewal state |
369
+
370
+ A complete backup includes the stopped deployment and matching signing
371
+ identities. `reset --yes` affects the CMS installation and local release cache;
372
+ it preserves the independent Repository deployment and client identities.
373
+
374
+ ### Other Network Modes
375
+
376
+ The standard procedure above uses managed ACME. The CLI also supports:
377
+
378
+ | Mode | Command | Exposure |
379
+ | --- | --- | --- |
380
+ | Local | `repository configure --tls local --port 5010` | Loopback HTTP only |
381
+ | External proxy | `repository configure --tls external --public-url https://repository.example.com` | Loopback backend; the operator supplies and connects the HTTPS proxy |
382
+
383
+ Run `repository start` after configuration changes. An external proxy must
384
+ forward to the backend, allow 100 MiB assets plus protocol overhead and preserve
385
+ request bodies. The CLI's external mode does not configure the operator's proxy
386
+ or join its Docker network. The public origin controls resource links; forwarded
387
+ headers do not override it.
388
+
389
+ Local regression tests validate deployment configuration and publication using
390
+ temporary repositories. They do not issue public certificates or contact the
391
+ official Repository. Contributor-only image builds and Docker regression tests
392
+ are separate from the installation procedure:
326
393
 
327
394
  ```bash
328
395
  bun run infra/images/build.ts build --version 0.1.0-repository.0 repository
329
396
  ULVIA_REPOSITORY_DOCKER_IMAGE=docker.io/cyaxis/ulvia-official-repository:0.1.0-repository.0 bun test infra/images/official-repository/tests
330
397
  ```
331
-
332
- These tests launch loopback-only containers, exercise the CLI against their local
333
- endpoints and remove their temporary data. They publish nothing externally.
package/README.md CHANGED
@@ -155,6 +155,23 @@ releases. It preserves independent Repository deployments and signing identities
155
155
  `collection`, `contract`, or `provider-manifest`. It validates and stores one
156
156
  immutable release. A provider manifest must reference exact contract releases
157
157
  already in the local repository. Release does not connect to or test a provider.
158
+ `release <directory> --recursive` discovers authored resource roots below a
159
+ folder, stopping before nested Bloc or conformance definitions. It orders
160
+ contracts by inheritance and capability requirements, validates conformance
161
+ against the complete planned contract set, then prepares providers and
162
+ collections. Existing local dependencies are reused. Source admission happens
163
+ before any resource is stored; each resource is committed separately, so a
164
+ storage or publication conflict can leave a partial batch. Retrying identical
165
+ releases is idempotent. Duplicate coordinates and symbolic links are rejected.
166
+ Discovery is bounded to 256 resources, 4096 directories and 32 directory levels;
167
+ prepared canonical bytes and assets are bounded to 512 MiB. `push` remains an
168
+ explicit separate command.
169
+
170
+ ```bash
171
+ ulvia release packages/official-repository/contracts --recursive
172
+ ulvia release packages/official-repository --recursive
173
+ ```
174
+
158
175
  Contract fixture assets declared in `definition.json` are read from
159
176
  `fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
160
177
  different content fails. The local Repository serves stored resources
@@ -184,10 +201,28 @@ dependencies, before storing the contract. Conformance publication and live
184
201
  execution are separate Gateway/repository APIs; the CLI does not yet orchestrate
185
202
  a disposable provider environment.
186
203
 
187
- `push` publishes one exact local coordinate, and `pull` downloads and re-admits
188
- one exact remote coordinate before storing it locally. Both support
189
- `collection`, `contract`, and `provider`; dependencies must be transferred
190
- first. `repository login` saves the default endpoint; `--repository` and
204
+ `push <publisher/id@version>` infers the kind from local cached releases. If the
205
+ same coordinate exists in several catalogues, specify `push contract`,
206
+ `push collection` or `push provider` to resolve the ambiguity. `pull` still takes
207
+ an explicit kind and downloads and re-admits one exact coordinate locally.
208
+
209
+ `push all` publishes every non-yanked release in the local cache, independently
210
+ of the working directory. It orders contract inheritance and requirements,
211
+ then providers and known local collection dependencies. All artifacts and every
212
+ namespace's local owner key are checked before the first upload. No namespace
213
+ is implicitly claimed and releases without an owner key are not silently skipped.
214
+ A remote refusal or transfer failure stops the batch; already completed
215
+ publications remain visible. Repeating the command reconciles identical releases
216
+ and resumes the remainder. The receiving Repository still validates dependency
217
+ availability and every immutable artifact. For single pushes, transfer required
218
+ dependencies first.
219
+
220
+ ```bash
221
+ ulvia push ulvia.official/ulvia.cms.emailer@1.0.0
222
+ ulvia push all
223
+ ```
224
+
225
+ `repository login` saves the default endpoint; `--repository` and
191
226
  `ULVIA_REPOSITORY_URL` remain explicit overrides. Owner signatures bind Repository
192
227
  identity, namespace revision, action, content digest, timestamp and nonce.
193
228
  The server rejects stale or replayed