@git.zone/cli 7.4.1 → 8.1.0

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.
Files changed (39) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/mod_services/classes.dockercontainer.d.ts +13 -2
  3. package/dist_ts/mod_services/classes.dockercontainer.js +40 -40
  4. package/dist_ts/mod_services/classes.globalregistry.d.ts +12 -0
  5. package/dist_ts/mod_services/classes.globalregistry.js +96 -13
  6. package/dist_ts/mod_services/classes.globalregistrystore.d.ts +7 -1
  7. package/dist_ts/mod_services/classes.globalregistrystore.js +6 -6
  8. package/dist_ts/mod_services/classes.legacymongomigration.d.ts +239 -0
  9. package/dist_ts/mod_services/classes.legacymongomigration.js +970 -0
  10. package/dist_ts/mod_services/classes.serviceconfiguration.d.ts +112 -15
  11. package/dist_ts/mod_services/classes.serviceconfiguration.js +274 -62
  12. package/dist_ts/mod_services/classes.servicedatamarker.d.ts +42 -1
  13. package/dist_ts/mod_services/classes.servicedatamarker.js +101 -8
  14. package/dist_ts/mod_services/classes.servicemanager.d.ts +99 -33
  15. package/dist_ts/mod_services/classes.servicemanager.js +652 -384
  16. package/dist_ts/mod_services/classes.servicepruner.js +27 -20
  17. package/dist_ts/mod_services/index.js +62 -13
  18. package/dist_ts/mod_services/mod.plugins.d.ts +2 -1
  19. package/dist_ts/mod_services/mod.plugins.js +4 -2
  20. package/dist_ts_migration/002.runtime-config.d.ts +1 -1
  21. package/dist_ts_migration/002.runtime-config.js +8 -2
  22. package/dist_ts_migration/003.service-data-marker.js +125 -30
  23. package/dist_ts_migration/004.global-registry.js +30 -8
  24. package/package.json +1 -1
  25. package/readme.md +197 -32
  26. package/ts/00_commitinfo_data.ts +1 -1
  27. package/ts/mod_services/classes.dockercontainer.ts +58 -50
  28. package/ts/mod_services/classes.globalregistry.ts +115 -14
  29. package/ts/mod_services/classes.globalregistrystore.ts +16 -6
  30. package/ts/mod_services/classes.legacymongomigration.ts +1308 -0
  31. package/ts/mod_services/classes.serviceconfiguration.ts +387 -69
  32. package/ts/mod_services/classes.servicedatamarker.ts +149 -8
  33. package/ts/mod_services/classes.servicemanager.ts +877 -454
  34. package/ts/mod_services/classes.servicepruner.ts +27 -19
  35. package/ts/mod_services/index.ts +81 -12
  36. package/ts/mod_services/mod.plugins.ts +4 -1
  37. package/ts_migration/002.runtime-config.ts +8 -1
  38. package/ts_migration/003.service-data-marker.ts +168 -29
  39. package/ts_migration/004.global-registry.ts +38 -7
package/readme.md CHANGED
@@ -1246,7 +1246,7 @@ Supported services:
1246
1246
 
1247
1247
  | Service | Lifecycle/log aliases |
1248
1248
  | ----------------------------- | --------------------- |
1249
- | MongoDB | `mongo`, `mongodb` |
1249
+ | MongoDB (NoSQLDB engine) | `mongo`, `mongodb` |
1250
1250
  | ObjectStorage (S3-compatible) | `objectstorage`, `s3` |
1251
1251
  | Elasticsearch | `elasticsearch`, `es` |
1252
1252
 
@@ -1269,25 +1269,46 @@ gitzone services status --json
1269
1269
  # Print MongoDB Compass connection string
1270
1270
  gitzone services compass
1271
1271
 
1272
+ # Migrate legacy mongod data into NoSQLDB explicitly (start does it automatically)
1273
+ gitzone services migrate mongodb --yes
1274
+
1272
1275
  # Show logs
1273
1276
  gitzone services logs mongo 50
1274
1277
  ```
1275
1278
 
1276
1279
  Service config is stored in `.nogit/env.json`. Newly created config files use
1277
1280
  owner-only permissions; writes are atomic and reject a stale in-memory snapshot
1278
- rather than overwriting a concurrent change. MongoDB, ObjectStorage, and
1279
- Elasticsearch data is stored in `.nogit/mongodata`,
1281
+ rather than overwriting a concurrent change. MongoDB (NoSQLDB), ObjectStorage,
1282
+ and Elasticsearch data is stored in `.nogit/nosqldbdata`,
1280
1283
  `.nogit/objectstoragedata`, and `.nogit/esdata`, so it stays out of Git.
1281
1284
 
1285
+ The `mongodb` service runs the NoSQLDB engine from the digest-pinned
1286
+ `code.foss.global/lossless.zone/database` 2.0.0 image (`@lossless.org/nosqldb`
1287
+ 10.7.3) as `<project>-nosqldb`. It
1288
+ speaks the MongoDB wire protocol, so the `.nogit/env.json` contract
1289
+ (`MONGODB_URL`, `MONGODB_HOST`, `MONGODB_PORT`, `MONGODB_USER`, `MONGODB_PASS`,
1290
+ `MONGODB_NAME`, `MONGODB_AUTH_ENABLED`) is unchanged and consumers need no code
1291
+ change. The wire port is published as `127.0.0.1:MONGODB_PORT` only. The
1292
+ engine's management UI is not published; its password `MONGODB_ADMIN_PASSWORD`
1293
+ is generated per project, never printed, and redacted from logs and
1294
+ `services config --json`. Startup refuses the default `admin` passwords and an
1295
+ admin password reused as `MONGODB_PASS`, hardens `.nogit/nosqldbdata` to the
1296
+ engine user with mode `0700`, recreates an owned container by immutable ID when
1297
+ its image, port, data bind, `DBST_*` environment, restart policy, command,
1298
+ entrypoint, user, or health check drifted, and waits for an authenticated
1299
+ readiness round trip through `@lossless.org/client/nosqldb`. Transactions run on
1300
+ the single node without a replica set.
1301
+
1282
1302
  ObjectStorage uses `S3_PORT` for its local S3 API and `S3_UI_PORT` for its
1283
1303
  management UI. `S3_REGION` defaults to `us-east-1`; `S3_ADMIN_PASSWORD` is a
1284
1304
  separate randomly generated password for the UI's `admin` user. Startup rejects
1285
1305
  empty credentials, `admin`/`admin` S3 defaults, the default admin password, and
1286
1306
  an admin password reused as either S3 credential. `gitzone services config
1287
- --json` replaces those three ObjectStorage credential values with `"***"`.
1288
- Other fields are unchanged, including MongoDB and Elasticsearch passwords and
1289
- credential-bearing URLs, so the complete output must still be treated as
1290
- sensitive.
1307
+ --json` replaces those three ObjectStorage credential values with `"***"`, as
1308
+ it does the credential-bearing platform names listed under "serve.zone platform
1309
+ environment" below. It prints every other field as stored, including the
1310
+ MongoDB and Elasticsearch passwords and the credential-bearing `MONGODB_URL` and
1311
+ `ELASTICSEARCH_URL`, so treat the complete output as sensitive.
1291
1312
 
1292
1313
  GitZone runs a digest-pinned ObjectStorage image with both the S3 API and
1293
1314
  management UI published on loopback. `S3_HOST`, `S3_ENDPOINT`, `S3_USESSL`, and
@@ -1321,6 +1342,71 @@ stopped safely; an uncertain pre-existing start is left adoptable rather than
1321
1342
  risking stopping another concurrent invocation. A canonical container created
1322
1343
  but not yet started remains stopped for a safe retry.
1323
1344
 
1345
+ ### serve.zone platform environment
1346
+
1347
+ `.nogit/env.json` also carries the environment names a serve.zone `database`
1348
+ and `objectstorage` binding injects (see "Capability environment" in the
1349
+ serve.zone app-integration guide), so a serve.zone app runs locally against
1350
+ `gitzone services` without a hand-edited environment. They are derived from the
1351
+ GitZone fields on every start, reconfiguration, and write; edit the GitZone
1352
+ fields, never the derived names, which are overwritten. Other keys you add to
1353
+ the file are preserved.
1354
+
1355
+ | Platform name | Value |
1356
+ | --- | --- |
1357
+ | `MONGODB_URI`, `MONGODB_URL`, `MONGO_URL` | one identical URI: `mongodb://MONGODB_USER:MONGODB_PASS@MONGODB_HOST:MONGODB_PORT/MONGODB_NAME?authSource=admin&directConnection=true` |
1358
+ | `MONGODB_HOST`, `MONGODB_PORT` | the GitZone fields of the same name |
1359
+ | `MONGODB_DATABASE`, `MONGO_DBNAME` | `MONGODB_NAME` |
1360
+ | `MONGODB_USERNAME`, `MONGO_DBUSER` | `MONGODB_USER` |
1361
+ | `MONGODB_PASSWORD`, `MONGO_DBPASS` | `MONGODB_PASS` |
1362
+ | `AWS_ENDPOINT_URL` | the endpoint origin resolved from `S3_ENDPOINT` (see below), e.g. `http://localhost:29000`; the scheme's default port is omitted |
1363
+ | `S3_ENDPOINT_HOST` | the host of that origin, as written in `S3_ENDPOINT`; an IPv6 address without brackets |
1364
+ | `S3_PORT`, `S3_REGION`, `S3_BUCKET` | the GitZone fields of the same name |
1365
+ | `S3_USE_SSL` | `"true"` or `"false"`, the scheme of that origin |
1366
+ | `AWS_REGION` | `S3_REGION` |
1367
+ | `AWS_S3_FORCE_PATH_STYLE` | `"true"` |
1368
+ | `S3_ACCESS_KEY`, `S3_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_ID` | `S3_ACCESSKEY` |
1369
+ | `S3_SECRET_KEY`, `S3_SECRET_ACCESS_KEY`, `AWS_SECRET_ACCESS_KEY` | `S3_SECRETKEY` |
1370
+
1371
+ Two values differ from the platform deliberately:
1372
+
1373
+ - `S3_ENDPOINT` keeps the value you set, by default the bare host `localhost`,
1374
+ where the platform delivers the endpoint origin. Read `AWS_ENDPOINT_URL` for
1375
+ the origin; it means the same locally and on the platform.
1376
+ - The local MongoDB credential is the root user in `admin`, so the URIs
1377
+ authenticate with `authSource=admin` where the platform names the application
1378
+ database. The path names the database in both. `MONGODB_URL` gained
1379
+ `directConnection=true` in the same release, matching the standalone NoSQLDB
1380
+ node; its value is otherwise unchanged.
1381
+
1382
+ `S3_ENDPOINT` is never rewritten, and every non-empty value loads. The origin
1383
+ is resolved from it in one of three forms:
1384
+
1385
+ - a bare host or IP address (`localhost`, `::1`): the scheme comes from
1386
+ `S3_USESSL` and the port from `S3_PORT`;
1387
+ - `host:port` or `[ipv6]:port` (`minio.local:9000`): its port wins over
1388
+ `S3_PORT`, and the scheme comes from `S3_USESSL`;
1389
+ - an origin, `http(s)://host[:port]` (`https://s3.example.test`): a complete
1390
+ origin, so its scheme wins over `S3_USESSL` and its port, or the scheme's
1391
+ default port, over `S3_PORT`.
1392
+
1393
+ The host is kept as written, so IPv4 shorthand such as `127.1` and IPv4-mapped
1394
+ IPv6 addresses are not rewritten. User info, a path, a query, a fragment, a
1395
+ scheme other than `http`/`https`, and a port outside 1-65535 are not part of an
1396
+ origin and are not carried over; an endpoint without a host, such as `:9000`,
1397
+ takes its host from `S3_HOST`. `S3_PORT` stays the managed ObjectStorage's local
1398
+ API port: GitZone reconciles the local instance through `127.0.0.1` and that
1399
+ port whatever `S3_ENDPOINT` says, so when `S3_ENDPOINT` carries its own port or
1400
+ is an origin, `S3_PORT` is not the port of `AWS_ENDPOINT_URL`.
1401
+
1402
+ While MongoDB authentication is disabled, the URIs carry no credentials and the
1403
+ four credential names (`MONGODB_USERNAME`, `MONGO_DBUSER`, `MONGODB_PASSWORD`,
1404
+ `MONGO_DBPASS`) are absent; `MONGODB_USER` and `MONGODB_PASS` are kept for when
1405
+ it is enabled again. `gitzone services config --json` replaces every platform
1406
+ name that carries a credential (`MONGODB_URI`, `MONGO_URL`, the password pair,
1407
+ and the six S3 key names) with `"***"`; `MONGODB_URL` and `MONGODB_PASS` keep
1408
+ their earlier, unredacted output.
1409
+
1324
1410
  ### Migrating legacy MinIO state
1325
1411
 
1326
1412
  Persisted `minio` and `s3` service selections are rewritten to the canonical
@@ -1357,6 +1443,81 @@ directory, verify its provenance outside GitZone, start a fresh canonical
1357
1443
  service, and import required objects through S3. Do not synthesize a marker for
1358
1444
  unverified data.
1359
1445
 
1446
+ ### Migrating legacy MongoDB (mongod) state
1447
+
1448
+ Releases before NoSQLDB ran `mongo:7.0` as `<project>-mongodb` on
1449
+ `.nogit/mongodata`. The persisted-state migrations move the registry's
1450
+ `containers.mongo` claim to `legacy.mongoContainer` and the marker's mongod
1451
+ directory to a `safeToPrune: false` legacy entry; neither is ever treated as
1452
+ NoSQLDB ownership.
1453
+
1454
+ `gitzone services start` (and the explicit `gitzone services migrate mongodb`,
1455
+ which asks first unless `--yes` is given) migrates the data automatically when
1456
+ ownership is proven: the container carries the exact legacy GitZone labels for
1457
+ this project (or has no GitZone labels and exactly one legacy registry claim),
1458
+ runs `mongo:7.0`, and binds exactly `.nogit/mongodata` at `/data/db`. Data whose
1459
+ container is gone is proven by the marker's legacy entry or a legacy registry
1460
+ claim.
1461
+
1462
+ The migration journals every step in `.nogit/.gitzone-mongodb-migration.json`:
1463
+
1464
+ 1. Both images are present before anything is touched.
1465
+ 2. Freeze: the legacy container is stopped (by immutable ID, with a 60-second
1466
+ clean-shutdown grace) before anything reads its data, so no application
1467
+ write can land after the snapshot.
1468
+ 3. A temporary reader, `<project>-mongodb-migration-<token>`, opens
1469
+ `.nogit/mongodata` with the legacy container's exact image ID. It runs
1470
+ standalone (no `--replSet`, so the stored replica-set configuration is never
1471
+ consulted) with `recoverFromOplogAsStandalone`, which replays the oplog like
1472
+ the replica-set member would and then keeps the node read-only; data that
1473
+ never ran as a replica set is opened as a plain standalone. The reader has
1474
+ no network, no published port, restart policy `no`, and no access control:
1475
+ only short-lived fenced helpers that join its network namespace can reach it.
1476
+ 4. From the reader, an inventory (every non-system namespace with document count
1477
+ and index names) and a `mongodump --archive` are taken. MongoDB views are
1478
+ refused before the dump with an error naming every view: NoSQLDB has no
1479
+ general views. The reader is then removed.
1480
+ 5. The NoSQLDB container is created on a new `.nogit/nosqldbdata` with no
1481
+ network, no published port, and restart policy `no`, and `mongorestore`
1482
+ restores everything except `admin.*`, `config.*`, and `local.*` with
1483
+ `--stopOnError`. Credentials reach the tools only through the environment
1484
+ and a private config file, never argv.
1485
+ 6. The NoSQLDB inventory must match the legacy inventory exactly. The
1486
+ restore-phase container is stopped, and only then does the journal move
1487
+ from `running` to `committing`.
1488
+ 7. The restore-phase container is replaced by the published service container
1489
+ (loopback port, `unless-stopped`) on the same data, the legacy container is
1490
+ removed by immutable ID together with its anonymous `/data/configdb` volume,
1491
+ and the journal records `completed`. The bind-mounted `.nogit/mongodata` is
1492
+ never deleted. An interrupted commit resumes on the next start.
1493
+
1494
+ Invariant: while the journal is `running`, no application has ever been able to
1495
+ reach the NoSQLDB data, so it contains only migration writes. Any failure
1496
+ before the commit therefore rolls back safely: the reader and the NoSQLDB
1497
+ container and its data directory are removed, the legacy container is started
1498
+ again by its immutable ID if it was running, and the error carries the redacted
1499
+ tool output. An interrupted migration is rolled back on the next start. Other
1500
+ features NoSQLDB does not support (for example collations, text or geo indexes)
1501
+ surface as restore or verification failures rather than being dropped.
1502
+
1503
+ Every attempt writes its evidence to its own
1504
+ `.nogit/mongodb-migration/<timestamp>-<token>/`: the helper scripts
1505
+ (`inventory.js`, `readiness.js`), the inventories (`source-inventory.json`,
1506
+ `target-inventory.json`), the tool logs (`source-inventory.log`, `dump.log`,
1507
+ `target-readiness.log`, `restore.log`, `target-inventory.log`), and
1508
+ `dump.archive`. Each file exists only if its step ran. A rollback deletes only
1509
+ `dump.archive`, a derived copy of data that stays in `.nogit/mongodata`, and
1510
+ keeps the scripts, inventories, and logs of the failed attempt. After a
1511
+ completed migration, the whole directory, `dump.archive` included, is kept.
1512
+ `.nogit/mongodata` and `.nogit/mongodb-migration/` are never deleted by any
1513
+ GitZone command, including `clean` and `prune`. Remove them manually once the
1514
+ migrated data is confirmed. The journal stays as a permanent completion record,
1515
+ so a later `clean` never re-imports the old data. If ownership cannot be proven, startup
1516
+ stops before any Docker mutation and prints the manual recovery steps. Projects
1517
+ that never run the new CLI keep their running legacy container untouched.
1518
+ `gitzone services stop` and `stop -g` may stop a proven-owned legacy container;
1519
+ nothing else acts on it.
1520
+
1360
1521
  ### Consuming a service programmatically
1361
1522
 
1362
1523
  `gitzone services status --json` emits only JSON on stdout, so a test suite or
@@ -1368,9 +1529,10 @@ gitzone services status --json | jq -r '.services.mongodb.connectionString'
1368
1529
 
1369
1530
  The ObjectStorage status key is `.services.objectstorage`; the former
1370
1531
  `.services.minio` key no longer exists. Preserved predecessor evidence is
1371
- reported separately under `.legacy`. `minioDataDirectory` and `minioDataExists`
1372
- are always emitted; `minioContainer` is present only when container evidence
1373
- exists. Consumers must treat this as a breaking response-schema change rather
1532
+ reported separately under `.legacy`. `minioDataDirectory`, `minioDataExists`,
1533
+ `mongoDataDirectory`, `mongoDataExists`, `mongoMigrationDirectory`, and
1534
+ `mongoMigrationDirectoryExists` are always emitted; `minioContainer` and
1535
+ `mongoContainer` are present only when container evidence exists. Consumers must treat this as a breaking response-schema change rather
1374
1536
  than interpreting legacy evidence as an active service.
1375
1537
 
1376
1538
  ### Cleanup levels
@@ -1395,8 +1557,8 @@ whether still `created` or already `exited`, can be recovered only after their
1395
1557
  complete runtime envelope, bind target, age, and immutable ID are proven;
1396
1558
  running, fresh, or noncanonical occupants block the operation.
1397
1559
 
1398
- A helper carries exactly one read-write bind of its target. Service images such
1399
- as `mongo:7.0` additionally declare their own `VOLUME` destinations, for which
1560
+ A helper carries exactly one read-write bind of its target. Images such as
1561
+ `mongo:7.0` additionally declare their own `VOLUME` destinations, for which
1400
1562
  Docker attaches anonymous volumes GitZone never requested; those are accepted
1401
1563
  only where Docker proves them image-declared and anonymous, namely the local
1402
1564
  driver, a random 64-character volume name, and a destination the container's own
@@ -1444,26 +1606,30 @@ container running. Anything ambiguous — an unlabeled container claimed by more
1444
1606
  than one project, an unreachable Docker daemon, a directory still mounted by a
1445
1607
  running container — is reported and skipped rather than reclaimed. Containers
1446
1608
  are identified by an exact canonical GitZone label envelope. An unambiguous
1447
- registry claim is used only for older MongoDB and Elasticsearch containers with
1448
- no `git.zone.*` labels at all. ObjectStorage has no unlabeled predecessor
1449
- fallback; partial, missing, or conflicting GitZone labels fail closed. Removal
1609
+ registry claim is used only for older Elasticsearch containers with no
1610
+ `git.zone.*` labels at all. NoSQLDB and ObjectStorage have no unlabeled
1611
+ predecessor fallback, and their data is reclaimable only with marker proof;
1612
+ partial, missing, or conflicting GitZone labels fail closed. Removal
1450
1613
  revalidates and uses the container's immutable ID, never its mutable name, so
1451
1614
  pruning cannot touch a same-name replacement. If Docker becomes unavailable,
1452
1615
  registry claims are preserved as well as containers and data.
1453
1616
 
1454
- Legacy MinIO containers and registry references are reported as preserved
1455
- migration resources and are never prune candidates. `.nogit/miniodata` is
1456
- deliberately outside the prune allowlist; current-project `status` reports its
1457
- presence, while machine-wide prune leaves it untouched.
1617
+ Legacy MinIO and mongod containers are reported as preserved migration
1618
+ resources and are never prune candidates. A legacy MinIO registry reference is
1619
+ kept permanently. A legacy mongod registry reference is dropped together with
1620
+ its project's registry entry once the project directory is gone and no
1621
+ container with that name remains, because it can then identify nothing; while
1622
+ such a container exists, the entry is kept so the container stays identifiable.
1623
+ `.nogit/miniodata`,
1624
+ `.nogit/mongodata`, and `.nogit/mongodb-migration` are deliberately outside the
1625
+ prune allowlist; current-project `status` reports their presence, while
1626
+ machine-wide prune leaves them untouched.
1458
1627
 
1459
1628
  ### MongoDB authentication
1460
1629
 
1461
- MongoDB runs as a single-node replica set with authentication enabled, so
1462
- multi-document transactions work. The managed container also uses a 65,536
1463
- soft/hard `nofile` limit so persistent, collection-heavy test suites do not hit
1464
- Docker's low default. `services start` reconciles legacy containers to this limit
1465
- by recreating only the container while preserving the bind-mounted data directory.
1466
- Authentication can be disabled per project for
1630
+ NoSQLDB runs with SCRAM-SHA-256 authentication enabled; the root user is
1631
+ `MONGODB_USER`/`MONGODB_PASS` in the `admin` database. Authentication can be
1632
+ disabled per project for
1467
1633
  runtimes whose `node:crypto` cannot complete a SCRAM handshake (notably Deno):
1468
1634
 
1469
1635
  ```bash
@@ -1471,12 +1637,11 @@ gitzone services auth mongodb off
1471
1637
  gitzone services start mongo
1472
1638
  ```
1473
1639
 
1474
- This is opt-in and never implicit. With authentication disabled the database is
1475
- published on `127.0.0.1` only, and the combination of no authentication with a
1476
- non-local `MONGODB_HOST` is refused outright. Transactions continue to work, and
1477
- `gitzone services status` reports the mode. Re-enabling authentication over data
1478
- created without it bootstraps the configured root user through MongoDB's
1479
- localhost exception.
1640
+ This is opt-in and never implicit. The database is always published on
1641
+ `127.0.0.1` only, and the combination of no authentication with a non-local
1642
+ `MONGODB_HOST` is refused outright. Transactions continue to work, and
1643
+ `gitzone services status` reports the mode. Changing the mode recreates the
1644
+ container with the matching engine configuration.
1480
1645
 
1481
1646
  The setting is recorded in `.smartconfig.json`, so it is committed and a fresh
1482
1647
  clone or CI run reproduces it without any manual step:
@@ -1504,7 +1669,7 @@ authentication is enabled. Because a declaration affects everyone who clones the
1504
1669
  repository, `services status` states where the setting came from:
1505
1670
 
1506
1671
  ```text
1507
- ⚠️ Auth: DISABLED (loopback only), declared in .smartconfig.json (applies to every checkout)
1672
+ ⚠️ Auth: DISABLED, declared in .smartconfig.json (applies to every checkout)
1508
1673
  ```
1509
1674
 
1510
1675
  An older CLI that predates `serviceOptions` ignores the key and starts MongoDB
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '7.4.1',
6
+ version: '8.1.0',
7
7
  description: 'A comprehensive CLI tool for enhancing and managing local development workflows with gitzone utilities, focusing on project setup, version control, code formatting, and template management.'
8
8
  }
@@ -3,6 +3,7 @@ import * as helpers from './helpers.js';
3
3
  import { logger } from '../gitzone.logging.js';
4
4
  import {
5
5
  getServiceDataDirectory,
6
+ isLegacyServiceContainerLabels,
6
7
  markerProvesServiceDataDirectory,
7
8
  readServiceDataMarker,
8
9
  serviceBindOperation,
@@ -22,8 +23,6 @@ export interface IDockerUlimit {
22
23
 
23
24
  export type TDockerUlimits = Record<string, IDockerUlimit>;
24
25
 
25
- export type TDockerUlimitMatch = 'match' | 'mismatch' | 'unavailable';
26
-
27
26
  export interface IDockerRunOptions {
28
27
  name: string;
29
28
  image: string;
@@ -41,6 +40,8 @@ export interface IDockerCreateArgvOptions extends Omit<IDockerRunOptions, 'comma
41
40
  command?: readonly string[];
42
41
  user?: string;
43
42
  entrypoint?: string;
43
+ /** Docker network mode, e.g. `container:<64-hex id>` to share a service's namespace. */
44
+ network?: string;
44
45
  }
45
46
 
46
47
  export interface IDockerExecArgvOptions {
@@ -73,6 +74,12 @@ export interface IFencedBindOperationOptions extends IFencedBindOperationSpecifi
73
74
  executionOptions: () => IDockerExecArgvOptions;
74
75
  rollbackTimeoutMs?: number;
75
76
  recoverablePredecessors?: readonly IFencedBindOperationSpecification[];
77
+ /** Container user; root (`0`) unless the operation must write as the invoking user. */
78
+ user?: string;
79
+ /** Exact network mode; `container:<64-hex id>` joins one service's namespace. */
80
+ network?: string;
81
+ /** Passed by name, so values never enter Docker's argv. */
82
+ environment?: Record<string, string>;
76
83
  }
77
84
 
78
85
  interface IFencedBindRuntimeOptions extends IFencedBindOperationOptions {
@@ -429,42 +436,6 @@ export const renderDockerUlimits = (ulimitsArg: TDockerUlimits = {}): string =>
429
436
  return rendered;
430
437
  };
431
438
 
432
- export const matchDockerUlimits = (
433
- inspectDataArg: unknown,
434
- expectedArg: TDockerUlimits,
435
- ): TDockerUlimitMatch => {
436
- if (!Array.isArray(inspectDataArg) || inspectDataArg.length !== 1) {
437
- return 'unavailable';
438
- }
439
- const container = inspectDataArg[0] as {
440
- HostConfig?: {
441
- Ulimits?: Array<{ Name?: unknown; Soft?: unknown; Hard?: unknown }> | null;
442
- };
443
- };
444
- if (!container?.HostConfig) {
445
- return 'unavailable';
446
- }
447
- if (!Object.hasOwn(container.HostConfig, 'Ulimits')) {
448
- return 'unavailable';
449
- }
450
- const actual = container.HostConfig.Ulimits ?? [];
451
- if (!Array.isArray(actual)) {
452
- return 'unavailable';
453
- }
454
- for (const [name, expected] of Object.entries(expectedArg)) {
455
- assertDockerUlimit(name, expected);
456
- const matchingName = actual.filter((entry) => entry?.Name === name);
457
- if (
458
- matchingName.length !== 1 ||
459
- matchingName[0].Soft !== expected.soft ||
460
- matchingName[0].Hard !== expected.hard
461
- ) {
462
- return 'mismatch';
463
- }
464
- }
465
- return 'match';
466
- };
467
-
468
439
  const isUnknownRecord = (valueArg: unknown): valueArg is Record<string, any> => {
469
440
  return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
470
441
  };
@@ -478,6 +449,7 @@ interface IFencedBindInspection {
478
449
  status: string;
479
450
  exitCode: number;
480
451
  user: string;
452
+ networkMode: string;
481
453
  entrypoint: string[];
482
454
  command: string[];
483
455
  labels: Record<string, string>;
@@ -541,8 +513,13 @@ const parseFencedBindInspection = (
541
513
  const inspected = parsed[0];
542
514
  const config = inspected.Config;
543
515
  const state = inspected.State;
516
+ const hostConfig = inspected.HostConfig;
544
517
  const normalizedName = String(inspected.Name || '').replace(/^\//u, '');
545
518
  const createdAtMs = Date.parse(String(inspected.Created || ''));
519
+ const networkMode =
520
+ isUnknownRecord(hostConfig) && typeof hostConfig.NetworkMode === 'string'
521
+ ? hostConfig.NetworkMode
522
+ : '';
546
523
  if (
547
524
  typeof inspected.Id !== 'string' ||
548
525
  !/^[a-f0-9]{64}$/u.test(inspected.Id) ||
@@ -591,6 +568,7 @@ const parseFencedBindInspection = (
591
568
  status: state.Status,
592
569
  exitCode: state.ExitCode,
593
570
  user: config.User,
571
+ networkMode,
594
572
  entrypoint: [...config.Entrypoint],
595
573
  command: [...config.Cmd],
596
574
  labels,
@@ -722,6 +700,9 @@ export class DockerContainer {
722
700
  if (optionsArg.user) {
723
701
  argv.push('--user', optionsArg.user);
724
702
  }
703
+ if (optionsArg.network) {
704
+ argv.push('--network', optionsArg.network);
705
+ }
725
706
  if (optionsArg.entrypoint) {
726
707
  argv.push('--entrypoint', optionsArg.entrypoint);
727
708
  }
@@ -759,7 +740,8 @@ export class DockerContainer {
759
740
  if (
760
741
  inspectionArg.name !== optionsArg.name ||
761
742
  inspectionArg.image !== optionsArg.image ||
762
- inspectionArg.user !== '0' ||
743
+ inspectionArg.user !== (optionsArg.user ?? '0') ||
744
+ (optionsArg.network !== undefined && inspectionArg.networkMode !== optionsArg.network) ||
763
745
  inspectionArg.entrypoint.length !== 1 ||
764
746
  inspectionArg.entrypoint[0] !== optionsArg.entrypoint ||
765
747
  inspectionArg.command.length !== optionsArg.command.length ||
@@ -818,7 +800,8 @@ export class DockerContainer {
818
800
  if (
819
801
  inspectionArg.name !== expectedNameArg ||
820
802
  inspectionArg.image !== optionsArg.image ||
821
- inspectionArg.user !== '0' ||
803
+ inspectionArg.user !== (optionsArg.user ?? '0') ||
804
+ (optionsArg.network !== undefined && inspectionArg.networkMode !== optionsArg.network) ||
822
805
  !operationMatches ||
823
806
  !labelsMatch ||
824
807
  !mountMatches
@@ -973,9 +956,11 @@ export class DockerContainer {
973
956
  [plugins.path.resolve(runtimeOptions.hostPath)]: runtimeOptions.containerPath,
974
957
  },
975
958
  labels: runtimeOptions.labels,
976
- user: '0',
959
+ user: runtimeOptions.user ?? '0',
977
960
  entrypoint: runtimeOptions.entrypoint,
978
961
  command: runtimeOptions.command,
962
+ ...(runtimeOptions.network ? { network: runtimeOptions.network } : {}),
963
+ ...(runtimeOptions.environment ? { environment: runtimeOptions.environment } : {}),
979
964
  },
980
965
  runtimeOptions.executionOptions(),
981
966
  );
@@ -1373,6 +1358,18 @@ export class DockerContainer {
1373
1358
  );
1374
1359
  }
1375
1360
 
1361
+ /**
1362
+ * `removeDataDirectory` for a caller that already holds this service's data
1363
+ * operation lock (the lock is not re-entrant). Used by lifecycle rollback.
1364
+ */
1365
+ public async removeDataDirectoryHoldingLock(
1366
+ hostPathArg: string,
1367
+ imageArg: string,
1368
+ optionsArg: IRemoveDataDirectoryOptions,
1369
+ ): Promise<boolean> {
1370
+ return this.removeDataDirectoryLocked(hostPathArg, imageArg, optionsArg);
1371
+ }
1372
+
1376
1373
  private async removeDataDirectoryLocked(
1377
1374
  hostPathArg: string,
1378
1375
  imageArg: string,
@@ -1418,7 +1415,7 @@ export class DockerContainer {
1418
1415
  );
1419
1416
  }
1420
1417
 
1421
- if (optionsArg.service === 'objectstorage' && (canonicalExists || quarantineExists)) {
1418
+ if (optionsArg.service !== 'elasticsearch' && (canonicalExists || quarantineExists)) {
1422
1419
  const marker = await readServiceDataMarker(projectPath);
1423
1420
  if (
1424
1421
  !markerProvesServiceDataDirectory(
@@ -1427,7 +1424,9 @@ export class DockerContainer {
1427
1424
  optionsArg.service,
1428
1425
  )
1429
1426
  ) {
1430
- throw new Error(`Refusing ObjectStorage cleanup with unproven ownership: ${hostPath}`);
1427
+ throw new Error(
1428
+ `Refusing ${optionsArg.service} data cleanup with unproven ownership: ${hostPath}`,
1429
+ );
1431
1430
  }
1432
1431
  }
1433
1432
  const targetPaths = [hostPath, quarantinePath];
@@ -1435,9 +1434,19 @@ export class DockerContainer {
1435
1434
  `label=git.zone.project-path=${projectPath}`,
1436
1435
  `label=git.zone.service=${optionsArg.service}`,
1437
1436
  ];
1438
- let serviceContainerIds = await this.listIds(serviceContainerFilters);
1439
- if (serviceContainerIds.length > 0) {
1440
- const serviceContainers = await this.inspectMany(serviceContainerIds);
1437
+ // Predecessor containers (legacy mongod) carry the same service label but
1438
+ // never mount the canonical path; the mount check below still proves that.
1439
+ const listActiveServiceContainers = async (): Promise<IContainerInspectInfo[]> => {
1440
+ const ids = await this.listIds(serviceContainerFilters);
1441
+ if (ids.length === 0) {
1442
+ return [];
1443
+ }
1444
+ return (await this.inspectMany(ids)).filter(
1445
+ (container) => !isLegacyServiceContainerLabels(container.labels),
1446
+ );
1447
+ };
1448
+ let serviceContainers = await listActiveServiceContainers();
1449
+ if (serviceContainers.length > 0) {
1441
1450
  const helperTargets = new Set<string>();
1442
1451
  for (const container of serviceContainers) {
1443
1452
  const helperTarget = targetPaths.find((targetPathArg) =>
@@ -1456,11 +1465,10 @@ export class DockerContainer {
1456
1465
  getFencedBindOperationName(helperTarget),
1457
1466
  );
1458
1467
  }
1459
- serviceContainerIds = await this.listIds(serviceContainerFilters);
1460
- if (serviceContainerIds.length > 0) {
1461
- const [container] = await this.inspectMany(serviceContainerIds);
1468
+ serviceContainers = await listActiveServiceContainers();
1469
+ if (serviceContainers.length > 0) {
1462
1470
  throw new Error(
1463
- `Refusing service data cleanup while container ${container?.name || serviceContainerIds[0]} exists.`,
1471
+ `Refusing service data cleanup while container ${serviceContainers[0].name} exists.`,
1464
1472
  );
1465
1473
  }
1466
1474
  }