@git.zone/cli 6.12.0 → 6.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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
@@ -1087,6 +1099,102 @@ gitzone --version --json
1087
1099
  in legacy global roots, provided the active root already supplies them and no
1088
1100
  command shim still points there.
1089
1101
 
1102
+ ## Approved Testing Domains
1103
+
1104
+ `gitzone testing` uses the testing API in dcrouter 19.1.1 or later. An operator
1105
+ first enables an explicit testing-zone policy, provisions a machine registration,
1106
+ and approves each exact hostname requested by that registration. Approved grants
1107
+ survive credential rotation. Wildcards, parent domains, arbitrary TXT records,
1108
+ and production routes are outside this command's authority.
1109
+
1110
+ Inject `GITZONE_TESTING_BASE_URL` and `GITZONE_TESTING_TOKEN` from your environment
1111
+ or secret manager. Admin commands select `GITZONE_TESTING_ADMIN_TOKEN` instead.
1112
+ The URL must be an HTTPS origin; plain HTTP is accepted only on loopback for
1113
+ isolated tests. Credentials are never accepted as command arguments or saved to
1114
+ project/global configuration. `--token-stdin` reads at most 8192 bytes from a
1115
+ non-terminal stdin and requires the selected environment credential to be absent.
1116
+
1117
+ ```sh
1118
+ gitzone testing --help
1119
+ gitzone help testing --json
1120
+ gitzone testing whoami --json
1121
+ gitzone testing zone list --limit 25 --json
1122
+ gitzone testing grant request --zone ZONE_ID --hostname alice.testing.example.com --idempotency-key grant-alice-1 --json
1123
+ gitzone testing grant status --grant GRANT_ID --json
1124
+ gitzone testing cert ensure --grant GRANT_ID --idempotency-key cert-alice-1 --wait --json
1125
+ gitzone testing cert status --job JOB_ID --json
1126
+ ```
1127
+
1128
+ Mutation keys are supplied explicitly. Repeat the same key and payload after a
1129
+ lost response; use a new key only for a new operation. Certificate requests reuse
1130
+ usable cached material. `--wait` follows queued/running/retry-wait jobs while
1131
+ respecting their polling and retry times. `--timeout-ms` bounds acquisition and
1132
+ requests (default five minutes, maximum one hour). A local deadline or signal
1133
+ does not cancel durable server work. Poll the returned operation ID or repeat
1134
+ the original idempotency key to find its outcome. Unknown or abandoned outcomes
1135
+ require operator recovery and never trigger automatic mutation resubmission.
1136
+
1137
+ Run a development server with disposable certificate files:
1138
+
1139
+ ```sh
1140
+ gitzone testing cert run --grant GRANT_ID --idempotency-key cert-alice-1 -- node server.js --port 8443
1141
+ ```
1142
+
1143
+ The child receives `GITZONE_TESTING_CERTIFICATE_FILE`,
1144
+ `GITZONE_TESTING_PRIVATE_KEY_FILE`, and `GITZONE_TESTING_HOSTNAME`. Its environment
1145
+ excludes the parent's `GITZONE_TESTING_*` values, including both credentials.
1146
+ The directory has mode 0700 and both files have mode 0600. GitZone invokes the
1147
+ program directly, preserves every argument after `--`, returns its exit status,
1148
+ and removes the directory after exit or termination. SIGINT/SIGTERM are forwarded
1149
+ to the child; a child that does not stop is killed after five seconds. JSON output
1150
+ is rejected for `cert run` because child stdout is inherited. Certificate renewal
1151
+ is on demand: this command obtains material once; restart it to obtain renewed
1152
+ material when due. It does not save a permanent certificate cache.
1153
+
1154
+ DNS operations are restricted to records owned by the approved grant. Use `new`
1155
+ for creation and the current record revision for replacement/deletion:
1156
+
1157
+ ```sh
1158
+ 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
1159
+ gitzone testing dns list --grant GRANT_ID --json
1160
+ gitzone testing dns delete --grant GRANT_ID --record-key web-v4 --revision 1 --idempotency-key dns-delete-1 --wait --json
1161
+ gitzone testing dns status --mutation MUTATION_ID --json
1162
+ ```
1163
+
1164
+ Admin enrollment and rotation require a caller-preopened writable non-terminal
1165
+ descriptor of at least 3. Supply it through the parent secret-manager integration;
1166
+ GitZone writes exactly the new token plus a newline to that descriptor, and only
1167
+ registration metadata to ordinary output. No credential can be retrieved again
1168
+ after a lost delivery; list registrations and rotate the relevant credential.
1169
+
1170
+ ```sh
1171
+ # Descriptor 3 must already be connected to the caller's secret store.
1172
+ gitzone testing admin registration create --name developer-alice --expires-at 2027-01-01T00:00:00Z --idempotency-key enroll-alice-1 --secret-fd 3 --json
1173
+ gitzone testing admin registration list --json
1174
+ gitzone testing admin registration rotate --registration REGISTRATION_ID --generation 1 --expires-at 2027-01-01T00:00:00Z --secret-fd 3 --json
1175
+ 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
1176
+ gitzone testing admin grant list --state pending --json
1177
+ gitzone testing admin grant review --grant GRANT_ID --revision 1 --action approve --reason 'Approved development hostname' --json
1178
+ ```
1179
+
1180
+ `admin registration revoke` and `admin grant review --action revoke` require a
1181
+ revision and reason. Revocation blocks future access and schedules cleanup of
1182
+ proven-owned DNS records; already delivered keys cannot be recalled. Operator
1183
+ recovery remains revision checked and audited:
1184
+
1185
+ ```sh
1186
+ gitzone testing admin recovery list --kind certificate --state indeterminate --json
1187
+ gitzone testing admin recovery status --kind certificate --operation JOB_ID --json
1188
+ gitzone testing admin recovery action --kind certificate --operation JOB_ID --revision 3 --action recheck --reason 'Inspect interrupted issuance' --idempotency-key recovery-1 --json
1189
+ ```
1190
+
1191
+ For DNS recovery, `--operation` may identify a mutation or a grant's retained
1192
+ cleanup operation. Only actions listed by the server are supported. Abandonment
1193
+ retains unknown effects and their reservations; it does not make them safe to
1194
+ repeat. Lists accept `--after` and `--limit` (25 by default, at most 100) and return
1195
+ `nextAfterId`. Exit codes are 0 for success/admitted work, 1 for failure or an
1196
+ unresolved terminal operation, 2 for invalid input, and 130/143 for interruption.
1197
+
1090
1198
  ## Templates
1091
1199
 
1092
1200
  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.1',
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);