@cyaxis/ulvia 1.0.3 → 1.0.8

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
@@ -40,15 +40,14 @@ bun run ulvia -- instance delete preview --yes
40
40
  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
- bun run ulvia -- upgrade repository --version 0.0.1-beta
44
43
  bun run ulvia -- reset --yes
45
- bun run ulvia -- release packages/official-repository/collections/ulvia-official
44
+ bun run ulvia -- release packages/official-repository/collections/mossa
46
45
  bun run ulvia -- release /path/to/contract-directory
47
46
  bun run ulvia -- release /path/to/provider-directory
48
- bun run ulvia -- push contract ulvia.official/ulvia.cms.installations@1.0.0 --repository https://repository.example
49
- bun run ulvia -- pull collection ulvia.official/ulvia-official@1.0.0 --repository https://repository.example
50
- bun run ulvia -- yank collection ulvia.official/ulvia-official@1.0.0 --repository https://repository.example --reason "Superseded"
51
- 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.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
52
51
  bun run ulvia -- prune
53
52
  ```
54
53
 
@@ -62,7 +61,7 @@ The lifecycle commands manage the same Docker Compose projects for loopback and
62
61
  public installations from any directory. Persistent
63
62
  data lives below `$XDG_DATA_HOME/ulvia` or `~/.local/share/ulvia`;
64
63
  `ULVIA_DATA_DIR` remains an explicit isolation override for tests and CI. The
65
- CLI stores authored releases in `<data>/repository`. Shared Provider, Repository,
64
+ CLI stores authored releases in `<data>/repository`. Shared Provider,
66
65
  MongoDB, proxy, files, secrets and logs live below `<data>/services`; each
67
66
  stateless Edge has independent state and logs below `<data>/instances/<name>`.
68
67
  The CLI never starts application servers, supervises their PIDs, or builds
@@ -88,9 +87,10 @@ The configuration is persisted under `<data>/services/installation.json` and
88
87
  is not a per-start mode. ACME requires `0.0.0.0` and every instance in an ACME
89
88
  installation requires an explicit DNS domain. Network configuration is locked
90
89
  after the first instance because its canonical Edge URL is part of Provider
91
- provisioning. Repository and Provider management ports remain loopback-only.
90
+ provisioning. The Provider operator port remains loopback-only; a Repository instance is
91
+ exposed through its own Edge and the shared proxy.
92
92
 
93
- `services start` starts only the shared proxy, MongoDB, Repository and Provider.
93
+ `services start` starts only the shared proxy, MongoDB and Provider.
94
94
  On first initialization it uses the exact version embedded by `cli:build`, or
95
95
  an explicit `services start --version <version>` override. Later starts reuse
96
96
  the persisted digests and reject a conflicting `--version`; component changes
@@ -98,9 +98,9 @@ must go through `upgrade`.
98
98
  `instance create` provisions one isolated Provider tenant and immediately starts
99
99
  its dedicated Edge. `instance start` restarts only an already-provisioned
100
100
  instance's Edge. All Edges use the shared proxy port: an instance named
101
- `default` is available at `http://localhost:5100`, while any other instance such
101
+ `default` is available at `http://default.localhost:5100`, while an instance such
102
102
  as `preview` uses `http://preview.localhost:5100`.
103
- `ULVIA_HTTP_PORT`, `ULVIA_REPOSITORY_PORT`, and `ULVIA_PROVIDER_PORT` provide
103
+ `ULVIA_HTTP_PORT` and `ULVIA_PROVIDER_PORT` provide
104
104
  initial isolation defaults for tests and CI. Interactive configuration belongs
105
105
  to `ulvia configure network`. The Provider still listens on its canonical port
106
106
  5103 inside the private Docker network; only its operator port on the host
@@ -110,29 +110,37 @@ previously created local instance; it never creates an implicit instance.
110
110
 
111
111
  The lifecycle boundary is deliberate:
112
112
 
113
- Independent Repository deployments use `ulvia repository start`, `status`, `stop`
114
- and `upgrade --version <exact-version>`. Their default volume and image pin live
115
- below `<data>/repository-service`. No deployment name or `global`/`community`
116
- qualifier is required. The command does not start
117
- shared services or a Edge.
113
+ A Repository is an ordinary named CMS instance with an explicit application
114
+ profile:
118
115
 
119
- `ulvia repository login <url>` verifies and saves the remote identity and creates
120
- a default local signing identity if none exists. `ulvia identity create`, `import`,
121
- `use`, `list` and `public-key` manage reusable Ed25519 identities. Namespace
122
- commands and publication use the saved connection and select an identity matching
123
- the namespace's current owner. No environment exports are needed. `logout`
124
- removes only the connection, preserving keys.
116
+ ```bash
117
+ ulvia services start
118
+ ulvia instance create registry --profile repository@1.0.0
119
+ ulvia instance status registry
120
+ ```
121
+
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.
125
136
 
126
137
  Client configuration lives in `$XDG_CONFIG_HOME/ulvia/config.json` or
127
- `~/.config/ulvia/config.json`; private keys live in its `keys/` directory. Files
128
- use mode 0600, directories 0700. `ULVIA_CONFIG_DIR` overrides that location;
129
- `ULVIA_DATA_DIR` alone isolates client configuration under `<data>/config`.
130
- Deployment configuration is separate: `<data>/repository-service/config.json`.
131
- `repository configure` persists local, external HTTPS proxy or managed ACME
132
- networking. All namespaces, including `ulvia.official`, use public first claim.
133
- Claim platform-owned names locally before enabling public access. Ownership
134
- persists across restarts and cannot be reset through deployment configuration.
135
- See the [installation guide](../../../docs/installation/README.md#9-standalone-repository)
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)
136
144
  and [Repository architecture](../../../docs/architecture/community-repository.md).
137
145
 
138
146
  | Command | Provider tenant | Edge container |
@@ -148,9 +156,13 @@ private runtime files. Shared services and every instance have independent
148
156
  `stop`, `status`, and `logs` boundaries. Software upgrades are explicit and
149
157
  component-scoped through `upgrade <component> --version <exact-version>`.
150
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.
151
161
  `reset --yes`
152
162
  removes shared Compose projects, instances, shared state and local repository
153
- releases. It preserves independent Repository deployments and signing identities. It does not inspect or modify the current working directory.
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.
154
166
  `release <resource-directory>` reads `definition.json` and routes by `kind`:
155
167
  `collection`, `contract`, or `provider-manifest`. It validates and stores one
156
168
  immutable release. A provider manifest must reference exact contract releases
@@ -173,15 +185,12 @@ ulvia release packages/official-repository --recursive
173
185
 
174
186
  Contract fixture assets declared in `definition.json` are read from
175
187
  `fixtures/<asset-id>` and verified by digest. Releasing the same coordinate with
176
- different content fails. The local Repository serves stored resources
177
- at `/v1/collections`, `/v1/contracts`, and `/v1/providers` on loopback port
178
- 5102, with declared contract fixtures at
179
- `/v1/contracts/<publisher>/<contract>/<version>/fixtures/<asset-id>`, and sees
180
- new releases without restarting. The CMS consumes the collection and provider
181
- repository endpoints. The Provider administration Page imports an exact
182
- manifest, approves an account connection and replaces the site's exact contract
183
- selections for Gateway calls. `prune` empties all local repository content
184
- without deleting service or instance data.
188
+ different content fails. Local release storage is a private CLI cache, not an
189
+ 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
192
+ consume those public sources. `prune` empties the local cache without deleting
193
+ service or instance data.
185
194
 
186
195
  Contract authors may keep only release metadata in `definition.json` and split
187
196
  capabilities recursively below `capabilities/`. Each capability is one JSON
@@ -199,8 +208,8 @@ an explicit kind and downloads and re-admits one exact coordinate locally.
199
208
  `push all` publishes every non-yanked release in the local cache, independently
200
209
  of the working directory. It orders contract inheritance and requirements,
201
210
  then providers and known local collection dependencies. All artifacts and every
202
- namespace's local owner key are checked before the first upload. No namespace
203
- is implicitly claimed and releases without an owner key are not silently skipped.
211
+ namespace's account ownership are checked before the first upload. No namespace
212
+ is implicitly claimed and releases without usable account credentials are not silently skipped.
204
213
  A remote refusal or transfer failure stops the batch; already completed
205
214
  publications remain visible. Repeating the command reconciles identical releases
206
215
  and resumes the remainder. The receiving Repository still validates dependency
@@ -208,40 +217,34 @@ availability and every immutable artifact. For single pushes, transfer required
208
217
  dependencies first.
209
218
 
210
219
  ```bash
211
- ulvia push ulvia.official/ulvia.cms.emailer@1.0.0
220
+ ulvia push ulvia/cms.emailer@1.0.0
212
221
  ulvia push all
213
222
  ```
214
223
 
215
224
  `repository login` saves the default endpoint; `--repository` and
216
- `ULVIA_REPOSITORY_URL` remain explicit overrides. Owner signatures bind Repository
217
- identity, namespace revision, action, content digest, timestamp and nonce.
218
- The server rejects stale or replayed
219
- requests, serializes writes across processes, re-runs admission and evolution
220
- rules, and stages every declared asset as a separately signed raw stream. A final
221
- idempotent commit makes the immutable artifact visible only after all byte lengths
222
- and SHA-256 digests pass. Interrupted and rejected sessions never expose a partial
223
- release. An exact republish is idempotent; different bytes at an existing coordinate
224
- reject.
225
-
226
- The protocol, exact-coordinate client and mutation endpoint live in
227
- `@bernouy/cms-repository/repository/publication`. The CLI uses the publication
228
- client and local filesystem release storage; `official-repository-server`
229
- composes the HTTP listener inside its container. The filesystem composition
230
- persists upload sessions and replay claims below the repository root.
231
- A production repository can replace those ports without depending on this
232
- executable package.
225
+ `ULVIA_REPOSITORY_URL` remain explicit overrides. Every protected request uses
226
+ the origin/identity-bound PAT. Uploads bind the account, namespace and ownership
227
+ revision; transfer or revocation prevents unauthorized continuation. Publication
228
+ re-runs admission and evolution rules, streams bounded assets, verifies byte
229
+ lengths and SHA-256 digests, and makes the artifact visible last. Exact retries
230
+ are idempotent; different bytes at an existing coordinate reject.
231
+
232
+ The protocol and exact-coordinate client live in
233
+ `@bernouy/cms-repository/repository/publication`. The CLI and CMS authoring
234
+ implementation share those clients. The official Provider composes the domain
235
+ service and persistence for explicitly enabled Repository instances; Edge
236
+ exposes the selected admitted contract. The Repository uses ordinary CMS capabilities and account PATs.
233
237
 
234
238
  `yank` is reversible catalogue metadata: it hides a release from new catalogue
235
239
  resolution without deleting its exact historical bytes. `restore` exposes it
236
240
  again. Contract yanks block new dependent publications while previously
237
- published provider manifests remain readable. The loopback Repository uses the
238
- same owner-signing protocol. Signing keys stay in local identities.
241
+ published provider manifests remain readable.
239
242
 
240
243
  A collection keeps immutable administration copy in recursive locale
241
244
  directories such as `translations/en/collection.json` and
242
245
  `translations/en/theme/colors.json`. Every JSON object below
243
246
  `translations/<locale>/` contributes to that locale's flat catalogue.
244
- Collection, Bloc, setting, text, theme and Page metadata stores
247
+ Collection, Bloc, setting, text, theme and example metadata stores
245
248
  reusable keys from those catalogues rather than inline labels. A key may occur
246
249
  in only one fragment per locale. The collection locale must define every
247
250
  referenced key; additional locale directories may be partial and fall back to
@@ -259,7 +262,7 @@ typed `font-face` entries backed by local WOFF2 assets.
259
262
  Collection assets are discovered recursively below `assets/`; their lowercase
260
263
  relative paths are their stable IDs. They are not declared in the collection
261
264
  `definition.json`. An optional root `assets/definition.json` accepts only a
262
- `generations` object keyed by those paths. The compiler derives media type,
265
+ `deprecations` object keyed by those paths. The compiler derives media type,
263
266
  size and digest. Safe presentation-only SVG files receive the `inline-svg`
264
267
  profile automatically; other SVGs remain downloadable assets but cannot be
265
268
  expanded into authored Page DOM.
@@ -277,11 +280,12 @@ ID, and discovery stops there so `settings/definition.json` is never mistaken
277
280
  for a nested Bloc. Intermediate grouping directories contain only directories
278
281
  and do not affect release identity.
279
282
 
280
- The Official Repository image contains the admitted CMS contracts, provider
281
- manifest, and administration collection. It installs that snapshot only into
282
- absent or empty persistent storage. A non-empty repository is never overlaid on
283
- image upgrade. The workspace bootstrap command builds the admitted snapshot
284
- used by the image:
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:
285
289
 
286
290
  ```bash
287
291
  bun run generate:official-bootstrap
@@ -297,11 +301,17 @@ image replacement remain separate actions.
297
301
  API, then starts its Edge. Connection review validates the runtime report and
298
302
  exact manifest claims. Provider behavior is covered by implementation-owned tests.
299
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.
309
+
300
310
  ## Collection examples
301
311
 
302
312
  `ulvia preview <collection-directory> --output <new-directory> [--dependency <directory>] [--locale <locale>] [--theme-mode <light|dark>] [--no-screenshots] [--serve]`
303
313
  exports collection example frames, generated PNGs, an interactive local explorer and a
304
314
  provenance manifest. Screenshots require the Playwright Chromium browser
305
- (`bunx playwright@1.63.0 install chromium`). Dependencies and required contracts are
315
+ (`bunx playwright@1.64.1 install chromium`). Dependencies and required contracts are
306
316
  resolved explicitly from local sources/cache; preview never publishes. See
307
317
  [collection examples](../../../docs/blocs/examples.md) for source and release formats.
@@ -49,40 +49,6 @@ services:
49
49
  start_period: 10s
50
50
  stop_grace_period: 30s
51
51
 
52
- repository:
53
- image: ${OFFICIAL_REPOSITORY_IMAGE}
54
- restart: unless-stopped
55
- init: true
56
- user: "${ULVIA_UID}:${ULVIA_GID}"
57
- environment:
58
- MODE: PROD
59
- NODE_ENV: production
60
- REPOSITORY_HOST: 0.0.0.0
61
- REPOSITORY_PORT: "3000"
62
- REPOSITORY_PUBLIC_URL: http://127.0.0.1:${ULVIA_REPOSITORY_PORT}
63
- ULVIA_REPOSITORY_DIR: /var/lib/ulvia-repository
64
- ULVIA_REPOSITORY_SEED_DIR: /opt/ulvia-repository-seed
65
- stop_grace_period: 30s
66
- volumes:
67
- - type: bind
68
- source: ${ULVIA_REPOSITORY_DIR}
69
- target: /var/lib/ulvia-repository
70
- ports:
71
- - "127.0.0.1:${ULVIA_REPOSITORY_PORT}:3000"
72
- networks:
73
- - private
74
- read_only: true
75
- tmpfs:
76
- - /tmp:rw,nosuid,nodev,noexec,size=64m
77
- cap_drop: [ALL]
78
- security_opt: [no-new-privileges:true]
79
- healthcheck:
80
- test: ["CMD", "bun", "-e", "const r=await fetch('http://127.0.0.1:3000/readyz'); if(!r.ok) process.exit(1); await r.body?.cancel()"]
81
- interval: 30s
82
- timeout: 5s
83
- retries: 3
84
- start_period: 5s
85
-
86
52
  mongo-provision:
87
53
  image: mongo:7.0.37@sha256:d5b3ca8c3f3cdce78d44870dc0871b76d5235e9b2ad4ea6bea5d1fbff8027703
88
54
  restart: "no"
@@ -124,7 +90,8 @@ services:
124
90
  CMS_REPOSITORY_URL: ${CMS_REPOSITORY_URL:-https://repo.ulvia.fr}
125
91
  CMS_REPOSITORY_ALLOW_INSECURE_HTTP: "${CMS_REPOSITORY_ALLOW_INSECURE_HTTP:-false}"
126
92
  CMS_SESSION_SECRET: ${ULVIA_PROVIDER_SESSION_SECRET}
127
- CMS_KEK_HEX: ${ULVIA_PROVIDER_KEK_HEX}
93
+ CMS_KEK_ACTIVE_ID: ${ULVIA_PROVIDER_KEK_ACTIVE_ID}
94
+ CMS_KEK_RING_JSON: ${ULVIA_PROVIDER_KEK_RING_JSON}
128
95
  MONGO_URL: mongodb://${ULVIA_MONGO_PROVIDER_USERNAME}:${ULVIA_MONGO_PROVIDER_PASSWORD}@mongo:27017/ulvia_provider_control?authSource=admin&retryWrites=false
129
96
  ULVIA_PROVIDER_HOST: 0.0.0.0
130
97
  ULVIA_PROVIDER_PORT: "5103"
@@ -144,8 +111,6 @@ services:
144
111
  depends_on:
145
112
  mongo-provision:
146
113
  condition: service_completed_successfully
147
- repository:
148
- condition: service_healthy
149
114
  read_only: true
150
115
  tmpfs:
151
116
  - /tmp:rw,nosuid,nodev,noexec,size=256m