@cyaxis/ulvia 1.0.3 → 1.0.7
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 +109 -177
- package/README.md +75 -65
- package/dist/definitions/services.yml +2 -37
- package/dist/index.js +38758 -26895
- package/package.json +3 -3
- package/dist/definitions/repository-tls.yml +0 -38
- package/dist/definitions/repository.yml +0 -32
package/README.md
CHANGED
|
@@ -40,7 +40,6 @@ 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
44
|
bun run ulvia -- release packages/official-repository/collections/ulvia-official
|
|
46
45
|
bun run ulvia -- release /path/to/contract-directory
|
|
@@ -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,
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
114
|
-
|
|
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
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
116
|
+
```bash
|
|
117
|
+
ulvia services start
|
|
118
|
+
ulvia instance create registry --profile ulvia.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
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
|
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.
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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
|
|
203
|
-
is implicitly claimed and releases without
|
|
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
|
|
@@ -213,35 +222,29 @@ ulvia push all
|
|
|
213
222
|
```
|
|
214
223
|
|
|
215
224
|
`repository login` saves the default endpoint; `--repository` and
|
|
216
|
-
`ULVIA_REPOSITORY_URL` remain explicit overrides.
|
|
217
|
-
identity
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
idempotent
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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.
|
|
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
|
|
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
|
-
`
|
|
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
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
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
|
+
`ulvia.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.
|
|
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
|
-
|
|
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
|