@git.zone/cli 6.12.0 → 6.13.2

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
@@ -457,34 +457,46 @@ Resume probes remotely observable targets before acting. Exact state is accepted
457
457
 
458
458
  Schema 1 resumes final Git release-ref and npm publication after the journal is atomically installed. Schema 2 additionally resumes Docker qualification, ordered promotion, and cleanup. Schema 3 resumes the complete npm package set. `--merge` remains available only for non-Docker releases because its pre-release Git push would violate qualification-before-publication ordering.
459
459
 
460
- For a root npm release whose local release commit and annotated tag already exist,
461
- but whose build or pack failed before journal installation, use:
460
+ For a Git release with root npm and/or Docker targets whose local release commit
461
+ and annotated tag already exist, but whose build or pack failed before journal
462
+ installation, use:
462
463
 
463
464
  ```bash
464
465
  gitzone release recover 6.0.0 --plan
465
466
  gitzone release recover 6.0.0 -y
466
467
  ```
467
468
 
468
- Recovery supports configured Git and root npm targets together. It requires clean
469
- `main`, the exact annotated tag at that commit, matching package and completed
469
+ Recovery supports configured Git with root npm and/or Docker targets. It requires
470
+ clean `main`, the exact annotated tag at that commit, matching package and completed
470
471
  changelog versions, and no pending changes. The metadata commit must not change
471
472
  release configuration. It also checks remote ancestry, requires the release tag
472
473
  to be absent remotely, and requires an anonymous HTTP 404 for the version at every
473
- npm registry. Published or uncertain state cannot be adopted without its original
474
- journal. Docker and tspublish preparation recovery are not supported.
474
+ npm registry when npm is selected. Published or uncertain Git/npm state cannot be
475
+ adopted without its original journal. Tspublish and Gitea asset preparation recovery
476
+ are not supported.
475
477
 
476
478
  The first attempt records the exact refs, destination and resolved workflow under
477
479
  the common Git directory in `gitzone/releases/v1/v<version>.preparation.json`.
480
+ For Docker, this binding also includes the exact canonical qualification request.
478
481
  Retries must match that binding. Recovery creates a disposable detached worktree
479
482
  from the tagged commit, runs `pnpm install --frozen-lockfile`, and runs the configured
480
483
  tests and build before packing. Ignored runtime data and local project secrets are
481
484
  not copied. A build that depends on those files must be made reproducible through
482
485
  the project's normal configuration before it can recover.
483
486
 
484
- The validated tarball is installed through the normal journal API and published
485
- through the existing Git-first workflow. Recovery never creates another version
486
- or moves refs. Once the journal exists, another `recover` call uses `resume`
487
- without rebuilding or repacking. Use `resume --recover-attempt` for an interrupted
487
+ Prepared npm artifacts are installed through the normal journal API. Docker
488
+ recovery verifies the project-local tSDocker capabilities and configuration before
489
+ preparation and validates again before installing a schema-2 journal. Its complete
490
+ qualification, including a fresh build and configured image tests, runs from the
491
+ unchanged canonical checkout before Git or npm publication. Candidate state stays
492
+ at that stable project identity for later resume; images from the disposable
493
+ preflight build are not adopted. Docker destinations retain the normal qualified
494
+ digest, observed alias predecessor, probe and conflict checks.
495
+
496
+ Recovery never creates another version or moves refs. Once the journal exists,
497
+ another `recover` call uses `resume`
498
+ without repeating preparation. Any unfinished Docker qualification remains part
499
+ of the normal resume workflow. Use `resume --recover-attempt` for an interrupted
488
500
  publisher that still owns a journaled attempt, after proving that process stopped.
489
501
 
490
502
  Concurrent preparations are excluded by `v<version>.prepare.lock`. A process crash
@@ -732,6 +744,9 @@ Pin pnpm 11 or later in `package.json` using `packageManager`. The workflow inst
732
744
  that version directly with the pinned official `pnpm/setup` action before the
733
745
  explicit frozen dependency install. This avoids an older container-provided pnpm
734
746
  launcher rewriting the lockfile while selecting the project's package manager.
747
+ The image's Deno CLI installs `sealedRelease.denoVersion` with `deno upgrade --force`.
748
+ The next command verifies the effective compiler version before dependency installation;
749
+ this setup does not require a separate Deno action.
735
750
 
736
751
  ```json
737
752
  {
@@ -1087,6 +1102,102 @@ gitzone --version --json
1087
1102
  in legacy global roots, provided the active root already supplies them and no
1088
1103
  command shim still points there.
1089
1104
 
1105
+ ## Approved Testing Domains
1106
+
1107
+ `gitzone testing` uses the testing API in dcrouter 19.1.1 or later. An operator
1108
+ first enables an explicit testing-zone policy, provisions a machine registration,
1109
+ and approves each exact hostname requested by that registration. Approved grants
1110
+ survive credential rotation. Wildcards, parent domains, arbitrary TXT records,
1111
+ and production routes are outside this command's authority.
1112
+
1113
+ Inject `GITZONE_TESTING_BASE_URL` and `GITZONE_TESTING_TOKEN` from your environment
1114
+ or secret manager. Admin commands select `GITZONE_TESTING_ADMIN_TOKEN` instead.
1115
+ The URL must be an HTTPS origin; plain HTTP is accepted only on loopback for
1116
+ isolated tests. Credentials are never accepted as command arguments or saved to
1117
+ project/global configuration. `--token-stdin` reads at most 8192 bytes from a
1118
+ non-terminal stdin and requires the selected environment credential to be absent.
1119
+
1120
+ ```sh
1121
+ gitzone testing --help
1122
+ gitzone help testing --json
1123
+ gitzone testing whoami --json
1124
+ gitzone testing zone list --limit 25 --json
1125
+ gitzone testing grant request --zone ZONE_ID --hostname alice.testing.example.com --idempotency-key grant-alice-1 --json
1126
+ gitzone testing grant status --grant GRANT_ID --json
1127
+ gitzone testing cert ensure --grant GRANT_ID --idempotency-key cert-alice-1 --wait --json
1128
+ gitzone testing cert status --job JOB_ID --json
1129
+ ```
1130
+
1131
+ Mutation keys are supplied explicitly. Repeat the same key and payload after a
1132
+ lost response; use a new key only for a new operation. Certificate requests reuse
1133
+ usable cached material. `--wait` follows queued/running/retry-wait jobs while
1134
+ respecting their polling and retry times. `--timeout-ms` bounds acquisition and
1135
+ requests (default five minutes, maximum one hour). A local deadline or signal
1136
+ does not cancel durable server work. Poll the returned operation ID or repeat
1137
+ the original idempotency key to find its outcome. Unknown or abandoned outcomes
1138
+ require operator recovery and never trigger automatic mutation resubmission.
1139
+
1140
+ Run a development server with disposable certificate files:
1141
+
1142
+ ```sh
1143
+ gitzone testing cert run --grant GRANT_ID --idempotency-key cert-alice-1 -- node server.js --port 8443
1144
+ ```
1145
+
1146
+ The child receives `GITZONE_TESTING_CERTIFICATE_FILE`,
1147
+ `GITZONE_TESTING_PRIVATE_KEY_FILE`, and `GITZONE_TESTING_HOSTNAME`. Its environment
1148
+ excludes the parent's `GITZONE_TESTING_*` values, including both credentials.
1149
+ The directory has mode 0700 and both files have mode 0600. GitZone invokes the
1150
+ program directly, preserves every argument after `--`, returns its exit status,
1151
+ and removes the directory after exit or termination. SIGINT/SIGTERM are forwarded
1152
+ to the child; a child that does not stop is killed after five seconds. JSON output
1153
+ is rejected for `cert run` because child stdout is inherited. Certificate renewal
1154
+ is on demand: this command obtains material once; restart it to obtain renewed
1155
+ material when due. It does not save a permanent certificate cache.
1156
+
1157
+ DNS operations are restricted to records owned by the approved grant. Use `new`
1158
+ for creation and the current record revision for replacement/deletion:
1159
+
1160
+ ```sh
1161
+ gitzone testing dns upsert --grant GRANT_ID --record-key web-v4 --revision new --type A --value 192.0.2.10 --ttl 60 --idempotency-key dns-web-1 --wait --json
1162
+ gitzone testing dns list --grant GRANT_ID --json
1163
+ gitzone testing dns delete --grant GRANT_ID --record-key web-v4 --revision 1 --idempotency-key dns-delete-1 --wait --json
1164
+ gitzone testing dns status --mutation MUTATION_ID --json
1165
+ ```
1166
+
1167
+ Admin enrollment and rotation require a caller-preopened writable non-terminal
1168
+ descriptor of at least 3. Supply it through the parent secret-manager integration;
1169
+ GitZone writes exactly the new token plus a newline to that descriptor, and only
1170
+ registration metadata to ordinary output. No credential can be retrieved again
1171
+ after a lost delivery; list registrations and rotate the relevant credential.
1172
+
1173
+ ```sh
1174
+ # Descriptor 3 must already be connected to the caller's secret store.
1175
+ gitzone testing admin registration create --name developer-alice --expires-at 2027-01-01T00:00:00Z --idempotency-key enroll-alice-1 --secret-fd 3 --json
1176
+ gitzone testing admin registration list --json
1177
+ gitzone testing admin registration rotate --registration REGISTRATION_ID --generation 1 --expires-at 2027-01-01T00:00:00Z --secret-fd 3 --json
1178
+ gitzone testing admin zone put --domain DOMAIN_ID --revision new --enabled true --record-types A,AAAA,CNAME --min-ttl 60 --max-ttl 3600 --max-grants 25 --json
1179
+ gitzone testing admin grant list --state pending --json
1180
+ gitzone testing admin grant review --grant GRANT_ID --revision 1 --action approve --reason 'Approved development hostname' --json
1181
+ ```
1182
+
1183
+ `admin registration revoke` and `admin grant review --action revoke` require a
1184
+ revision and reason. Revocation blocks future access and schedules cleanup of
1185
+ proven-owned DNS records; already delivered keys cannot be recalled. Operator
1186
+ recovery remains revision checked and audited:
1187
+
1188
+ ```sh
1189
+ gitzone testing admin recovery list --kind certificate --state indeterminate --json
1190
+ gitzone testing admin recovery status --kind certificate --operation JOB_ID --json
1191
+ gitzone testing admin recovery action --kind certificate --operation JOB_ID --revision 3 --action recheck --reason 'Inspect interrupted issuance' --idempotency-key recovery-1 --json
1192
+ ```
1193
+
1194
+ For DNS recovery, `--operation` may identify a mutation or a grant's retained
1195
+ cleanup operation. Only actions listed by the server are supported. Abandonment
1196
+ retains unknown effects and their reservations; it does not make them safe to
1197
+ repeat. Lists accept `--after` and `--limit` (25 by default, at most 100) and return
1198
+ `nextAfterId`. Exit codes are 0 for success/admitted work, 1 for failure or an
1199
+ unresolved terminal operation, 2 for invalid input, and 130/143 for interruption.
1200
+
1090
1201
  ## Templates
1091
1202
 
1092
1203
  Start new projects with built-in scaffolds:
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '6.12.0',
6
+ version: '6.13.2',
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
  }
package/ts/gitzone.cli.ts CHANGED
@@ -95,6 +95,11 @@ const runParsedCommand = async (argvArg: any): Promise<void> => {
95
95
  await modServices.run(argvArg);
96
96
  break;
97
97
  }
98
+ case "testing": {
99
+ const modTesting = await import("./mod_testing/index.js");
100
+ await modTesting.run(argvArg);
101
+ break;
102
+ }
98
103
  default: {
99
104
  const modStandard = await import("./mod_standard/index.js");
100
105
  await modStandard.run(argvArg);
@@ -51,6 +51,8 @@ const booleanLongFlags = new Set([
51
51
  "push",
52
52
  "quiet",
53
53
  "test",
54
+ "token-stdin",
55
+ "wait",
54
56
  "yes",
55
57
  ]);
56
58
 
@@ -85,7 +87,11 @@ const parseRawArgv = (argv: string[]): TArgSource => {
85
87
  const currentArg = argv[i];
86
88
 
87
89
  if (currentArg === "--") {
88
- parsedArgv._!.push(...argv.slice(i + 1));
90
+ if (parsedArgv._?.[0] === "testing") {
91
+ parsedArgv["--"] = argv.slice(i + 1);
92
+ } else {
93
+ parsedArgv._!.push(...argv.slice(i + 1));
94
+ }
89
95
  break;
90
96
  }
91
97
 
@@ -12,7 +12,10 @@ import {
12
12
  assertNpmPackageName,
13
13
  hashReleaseDestination,
14
14
  } from "./helpers.npmartifact.js";
15
- import { canonicalReleaseJson } from "./helpers.tsdockerprotocol.js";
15
+ import {
16
+ canonicalReleaseJson,
17
+ type IReleaseQualificationRequest,
18
+ } from "./helpers.tsdockerprotocol.js";
16
19
 
17
20
  interface IRecoveryRefs {
18
21
  mainOid: string;
@@ -26,6 +29,7 @@ export interface IReleasePreparationRecovery {
26
29
  refs: IRecoveryRefs;
27
30
  version: string;
28
31
  store: ReleaseJournalStore;
32
+ dockerRequest?: IReleaseQualificationRequest;
29
33
  }
30
34
 
31
35
  const git = async (
@@ -50,10 +54,13 @@ export const assertPackageReleaseRecovery = async (
50
54
  ): Promise<string> => {
51
55
  const { workflow, branch, version } = options;
52
56
  if (
53
- workflow.targets.length !== 2 ||
57
+ workflow.targets.length < 2 ||
58
+ workflow.targets.some(
59
+ (target) => !["git", "npm", "docker"].includes(target),
60
+ ) ||
54
61
  !workflow.targets.includes("git") ||
55
- !workflow.targets.includes("npm") ||
56
- workflow.npmPackageSource !== "root" ||
62
+ (workflow.targets.includes("npm") &&
63
+ workflow.npmPackageSource !== "root") ||
57
64
  !workflow.pushBranch ||
58
65
  !workflow.pushTags ||
59
66
  branch.sourceBranch !== "main" ||
@@ -61,7 +68,7 @@ export const assertPackageReleaseRecovery = async (
61
68
  !branch.remoteMainOid
62
69
  ) {
63
70
  throw new Error(
64
- "Release recover requires configured Git and root npm targets from clean main.",
71
+ "Release recover requires configured Git with root npm and/or Docker targets from clean main.",
65
72
  );
66
73
  }
67
74
  const manifest = JSON.parse(
@@ -149,8 +156,10 @@ export const assertRecoveryUnpublished = async (
149
156
  throw new Error(
150
157
  "Recovery cannot adopt an existing remote release tag. Use its original journal.",
151
158
  );
152
- for (const registry of options.workflow.npmRegistries)
153
- await assertNpmVersionAbsent(registry, packageName, options.version);
159
+ if (options.workflow.targets.includes("npm")) {
160
+ for (const registry of options.workflow.npmRegistries)
161
+ await assertNpmVersionAbsent(registry, packageName, options.version);
162
+ }
154
163
  };
155
164
 
156
165
  const preparationBinding = (options: IReleasePreparationRecovery) => ({
@@ -165,6 +174,7 @@ const preparationBinding = (options: IReleasePreparationRecovery) => ({
165
174
  workflow: JSON.parse(
166
175
  JSON.stringify({ ...options.workflow, confirmation: "auto" }),
167
176
  ),
177
+ ...(options.dockerRequest ? { dockerRequest: options.dockerRequest } : {}),
168
178
  });
169
179
 
170
180
  const bindPreparation = async (
@@ -815,7 +815,26 @@ const runReleaseRecover = async (
815
815
  version,
816
816
  branch.sourceOid,
817
817
  );
818
- const options = { smartshell: shell, workflow, branch, refs, version, store };
818
+ const tsdocker = workflow.targets.includes("docker")
819
+ ? new TsdockerReleaseClient(shell, paths.cwd)
820
+ : undefined;
821
+ const dockerRequest = tsdocker
822
+ ? createDockerQualificationRequest(
823
+ workflow,
824
+ paths.cwd,
825
+ version,
826
+ refs.mainOid,
827
+ )
828
+ : undefined;
829
+ const options = {
830
+ smartshell: shell,
831
+ workflow,
832
+ branch,
833
+ refs,
834
+ version,
835
+ store,
836
+ dockerRequest,
837
+ };
819
838
  const packageName = await assertPackageReleaseRecovery(options);
820
839
  if (!branch.planAncestryVerified) {
821
840
  console.log(
@@ -823,7 +842,7 @@ const runReleaseRecover = async (
823
842
  );
824
843
  }
825
844
  console.log(
826
- `Recover existing ${packageName}@${version}\ncommit: ${refs.mainOid}\ntag object: ${refs.tagOid}\nGit destination: ${branch.gitRemote}\nnpm registries: ${workflow.npmRegistries.join(", ")}\nBuild and pack an isolated checkout, install its journal, then publish configured targets.`,
845
+ `Recover existing ${packageName}@${version}\ncommit: ${refs.mainOid}\ntag object: ${refs.tagOid}\nGit destination: ${branch.gitRemote}\nTargets: ${workflow.targets.join(", ")}\n${workflow.targets.includes("npm") ? `npm registries: ${workflow.npmRegistries.join(", ")}\n` : ""}Run configured checks in an isolated checkout, install its journal, then ${tsdocker ? "qualify Docker before publishing configured targets" : "publish configured targets"}.`,
827
846
  );
828
847
  if (argvArg.plan) return;
829
848
  const pnpmCapability = await assertFreshReleaseCapabilities(
@@ -831,7 +850,9 @@ const runReleaseRecover = async (
831
850
  workflow,
832
851
  paths.cwd,
833
852
  branch.pushUrl,
853
+ tsdocker,
834
854
  );
855
+ if (tsdocker && dockerRequest) await tsdocker.validate(dockerRequest);
835
856
  if (!mode.yes) {
836
857
  if (!mode.interactive)
837
858
  throw new Error(
@@ -874,6 +895,8 @@ const runReleaseRecover = async (
874
895
  expectedRemoteMainOid: branch.remoteMainOid,
875
896
  version,
876
897
  refs,
898
+ dockerRequest,
899
+ tsdocker,
877
900
  ensurePublicationState: async () => {
878
901
  await ensureCheckout();
879
902
  await ensureUnpublished();
@@ -887,6 +910,7 @@ const runReleaseRecover = async (
887
910
  store: context.store,
888
911
  journal: context.journal,
889
912
  pushUrl: branch.pushUrl,
913
+ tsdocker,
890
914
  ensurePublicationState: ensureState,
891
915
  });
892
916
  printReleaseJournalSummary(result);
@@ -23,6 +23,7 @@ const commandSummaries: ICommandHelpSummary[] = [
23
23
  { name: "format", description: "Plan or apply project formatting changes" },
24
24
  { name: "config", description: "Read and change .smartconfig.json settings" },
25
25
  { name: "services", description: "Manage or configure development services" },
26
+ { name: "testing", description: "Use approved dcrouter testing domains, certificates, and DNS" },
26
27
  { name: "tools", description: "Manage the global @git.zone toolchain" },
27
28
  { name: "template", description: "Create a project from a template" },
28
29
  { name: "open", description: "Open project assets and CI pages" },
@@ -218,6 +219,11 @@ async function showCommandHelp(
218
219
  mode: ICliMode,
219
220
  ): Promise<boolean> {
220
221
  switch (commandName) {
222
+ case "testing": {
223
+ const modTesting = await import("../mod_testing/index.js");
224
+ modTesting.showHelp(mode);
225
+ return true;
226
+ }
221
227
  case "commit": {
222
228
  const modCommit = await import("../mod_commit/index.js");
223
229
  modCommit.showHelp(mode);