@git.zone/cli 6.17.1 → 7.0.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.
package/readme.md CHANGED
@@ -194,10 +194,10 @@ The release core is not configurable plumbing. It always follows the same profes
194
194
  6. Move pending changelog entries into the new version section.
195
195
  7. Create the local release commit and tag on `main`.
196
196
  8. Create a disposable detached checkout of that release commit, install its locked dependencies when the commit carries a `package.json`, and run the configured release build there. An active Docker target additionally builds the release worktree its qualification reads.
197
- 9. When npm is selected, pack it once into an exact tarball from that checkout.
198
- 10. Atomically install a durable journal before final publication. Root npm releases use journal schema 1; Docker releases use schema 2; tspublish component releases use schema 3 in the same storage tree.
197
+ 9. When npm is selected, prepare every named tspublish module outside the repository, then pack each module and the public root package once into an exact tarball from that checkout.
198
+ 10. Atomically install a durable journal before final publication. A release that publishes only the root package to npm uses journal schema 1, one that also or only publishes tspublish modules uses schema 3, a Docker release uses schema 2 with or without modules, and a Gitea asset release uses schema 4, all in the same storage tree.
199
199
  11. For schema 2, run the project-local tSDocker qualification build and configured image tests, then durably record the candidate digest graph and complete ordered promotion set.
200
- 12. Publish and verify Git, then each npm registry, then each Docker destination. Remove only the exact qualified candidate after every destination is verified, or after a terminal qualification destination conflict before Git/npm publication.
200
+ 12. Publish and verify Git, then every npm package at every registry, modules first and the root package last, then each Docker destination. Remove only the exact qualified candidate after every destination is verified, or after a terminal qualification destination conflict before Git/npm publication.
201
201
  13. Remove the test artifacts tstest wrote, so a machine does not accumulate test output release after release. This runs only after a successful publication, leaving the logs in place when a release fails. It is skipped when the project has no tstest installed, and a project opts out with `{"@git.zone/tstest": {"cleanup": {"onRelease": false}}}` in `.smartconfig.json`. See the tstest readme for what it removes; snapshots are kept.
202
202
 
203
203
  ### The release builds and packs the release commit
@@ -253,10 +253,10 @@ Consequences worth knowing before upgrading:
253
253
  unreachable registry, a missing credential, an unusable store — stops the
254
254
  release with the local release commit and tag created, nothing pushed, and no
255
255
  release journal written. Fix the environment, then: a release with a Git
256
- target plus a root-npm and/or Docker target continues with `gitzone release
256
+ target plus an npm and/or Docker target continues with `gitzone release
257
257
  recover <version>`, which prepares and publishes that exact tagged commit
258
- without moving any ref. Other configurations — tspublish component releases,
259
- Gitea-asset releases, and single-target releases — have no recovery path,
258
+ without moving any ref. Other configurations — Gitea-asset releases and
259
+ single-target releases — have no recovery path,
260
260
  because nothing was published: delete the tag and drop the release commit
261
261
  (`git tag -d v<version>` and `git reset --hard HEAD^` on `main`), then release
262
262
  again. Confirm first that `HEAD` is the release commit — `git log -1
@@ -402,7 +402,7 @@ for inspect/resume if publication is interrupted.
402
402
 
403
403
  A selected Git target requires a canonical remote name and exactly one resolved push URL. Before any remote contact, including during `--plan`, GitZone rejects HTTP(S) usernames or passwords, embedded passwords, query strings, fragments, and unsupported protocols. Canonical local paths and SSH destinations may retain their required SSH username.
404
404
 
405
- Every release that reaches final publication stores `journal.json` under the repository's Git common directory. Root npm releases additionally run `pnpm pack` once and store the resulting `package.tgz` beside it. The `v1` path names the storage format and contains all supported journal schemas:
405
+ Every release that reaches final publication stores `journal.json` under the repository's Git common directory. A release that publishes the root package additionally runs `pnpm pack` once and stores the resulting `package.tgz` beside it; every tspublish module is stored as `package.<sha256-of-package-name>.tgz`. The `v1` path names the storage format and contains all supported journal schemas:
406
406
 
407
407
  ```text
408
408
  <git-common-dir>/gitzone/releases/v1/v<version>/package.tgz
@@ -454,12 +454,23 @@ publication work left continues to require the journaled release commit.
454
454
 
455
455
  ### Publishing independently installable components
456
456
 
457
- Set `release.targets.npm.packageSource` to `"tspublish"` to release the named
458
- `ts*/tspublish.json` modules in one repository. The default `"root"` continues
459
- to publish the root package. A tspublish repository can use a private root
460
- manifest as the shared dependency/version catalog. Each module must declare
461
- `"registries": ["useBase"]`; GitZone owns the destinations and access settings.
462
- Explicit, empty, and `extendBase` module registry declarations are rejected.
457
+ The npm target publishes what the project declares, without further
458
+ configuration:
459
+
460
+ - every `ts*/tspublish.json` descriptor that names a package, in tspublish's
461
+ dependency and `order` sequence;
462
+ - then the root package, unless `package.json` sets `"private": true`. A
463
+ private root manifest stays the shared version and dependency catalog, and
464
+ only its modules publish.
465
+
466
+ Descriptors without a `name` stay build-order-only folders for TsBuild. Every
467
+ named module must declare `"registries": ["useBase"]`: GitZone publishes it to
468
+ `release.targets.npm.registries` with the target's access level and
469
+ `alreadyPublished` policy, exactly like the root package. Explicit, empty, and
470
+ `extendBase` registry declarations are rejected before the release creates
471
+ anything, and so are a module named like a public root package, a non-boolean
472
+ `"private"`, and an enabled npm target with nothing to publish. Each error names
473
+ the file and the change that resolves it.
463
474
 
464
475
  ```json
465
476
  {
@@ -468,45 +479,67 @@ Explicit, empty, and `extendBase` module registry declarations are rejected.
468
479
  "targets": {
469
480
  "npm": {
470
481
  "enabled": true,
471
- "packageSource": "tspublish",
472
- "registries": ["https://registry.npmjs.org"],
482
+ "registries": [
483
+ "https://verdaccio.lossless.digital",
484
+ "https://registry.npmjs.org"
485
+ ],
473
486
  "accessLevel": "public"
474
- }
487
+ },
488
+ "docker": { "enabled": true, "engine": "tsdocker" }
475
489
  }
476
490
  }
477
491
  }
478
492
  }
479
493
  ```
480
494
 
481
- `gitzone release --plan` reads and validates the component plans and prints
482
- their dependency order. It does not build, prepare, or publish packages.
483
- The normal build must generate every component's compiled folders. GitZone
484
- then uses tspublish's `prepare()` API to isolate those outputs, packs each
485
- component once, and removes the disposable preparation directories.
486
-
487
- Schema 3 records the ordered package set and every package/registry target.
488
- Each retained tarball uses the canonical filename
489
- `package.<sha256-of-package-name>.tgz` beside `journal.json`. Every package
490
- uses the release version, and sibling dependencies use that exact version.
491
- Git is published before any npm package. All stored hashes are checked before
492
- publication; completion requires every package at every registry to verify.
493
- If publication fails partway through, `release resume <version> -y` verifies
494
- the completed targets and continues using the retained tarballs. Resume never
495
- reruns component discovery, preparation, builds, or packing.
495
+ `gitzone release --plan` reads and validates the package set and prints it in
496
+ publication order, for example:
497
+
498
+ ```text
499
+ plan: … core.releaseCheckout -> core.releaseCheckout.build -> core.prepareNpmModules -> core.packNpmArtifact -> core.writeReleaseJournal -> target.docker.qualify -> target.git -> target.npm -> target.docker.promote -> target.docker.cleanup
500
+ npm packages (publication order):
501
+ @example/api-client (ts_apiclient, ts_interfaces)
502
+ @example/service (root)
503
+ ```
504
+
505
+ A private root prints `root @example/service: private, not published` instead
506
+ of its line. Modules publish before the root package because a module can only
507
+ depend on its siblings and on the root's dependencies, while the root package
508
+ may depend on its own modules.
509
+
510
+ The normal build must generate every module's compiled folders. In the release
511
+ checkout, GitZone re-reads the package set from the release commit and refuses
512
+ to publish one that differs from the plan. It then uses tspublish's `prepare()`
513
+ API to isolate the built modules beside the checkout, outside every repository,
514
+ packs each module and the root package once, and removes the preparation
515
+ directory.
516
+
517
+ The journal records the ordered module set and one target per package and
518
+ registry: the modules first, then the root package. Each module tarball uses the
519
+ canonical filename `package.<sha256-of-package-name>.tgz` beside `journal.json`;
520
+ the root package keeps `package.tgz`. Every package uses the release version,
521
+ and sibling dependencies use that exact version. Git is published before any npm
522
+ package. All stored hashes are checked before publication; completion requires
523
+ every package at every registry to verify. If publication fails partway
524
+ through, `release resume <version> -y` verifies the completed targets and
525
+ publishes only the missing ones from the retained tarballs, never a target that
526
+ already verified. Resume never reruns discovery, preparation, builds, or
527
+ packing.
496
528
 
497
529
  npm can hold accepted uploads for publish-time scanning before they become
498
- installable. Component releases submit the package set in dependency order,
499
- then wait for availability across the submitted set so scans can overlap.
530
+ installable. A release with modules submits every package in publication order,
531
+ then waits for availability across the submitted set so scans can overlap.
500
532
  Command failures and artifact conflicts still stop submission immediately.
501
533
  Every package, tarball and `latest` tag must verify before the release is
502
- complete. Root npm and Docker release ordering is unchanged.
534
+ complete, and Docker promotion waits until every package verified.
503
535
 
504
536
  See [npm's publish-time scanning announcement](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/)
505
537
  for the registry's availability behavior.
506
538
 
507
- This component release mode supports Git and npm targets. A combined Docker
508
- target is rejected before release mutation. Root-package Docker releases
509
- continue to use schema 2.
539
+ GitZone is the only publisher of these packages. A `package.json` script that
540
+ runs the standalone `tspublish` publisher (without the `plan` or `prepare`
541
+ subcommand) fails every release and resume that publishes npm packages, because
542
+ it would upload different bytes for the same version outside the journal.
510
543
 
511
544
  ### Gitea release attachments before npm
512
545
 
@@ -619,7 +652,7 @@ Resume probes remotely observable targets before acting. A published Git release
619
652
 
620
653
  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.
621
654
 
622
- For a Git release with root npm and/or Docker targets whose local release commit
655
+ For a Git release with npm and/or Docker targets whose local release commit
623
656
  and annotated tag already exist, but whose build or pack failed before journal
624
657
  installation, use:
625
658
 
@@ -628,14 +661,15 @@ gitzone release recover 6.0.0 --plan
628
661
  gitzone release recover 6.0.0 -y
629
662
  ```
630
663
 
631
- Recovery supports configured Git with root npm and/or Docker targets. It requires
632
- clean `main`, the exact annotated tag at that commit, matching package and completed
633
- changelog versions, and no pending changes. The metadata commit must not change
634
- release configuration. It also checks remote ancestry, requires the release tag
635
- to be absent remotely, and requires an anonymous HTTP 404 for the version at every
636
- npm registry when npm is selected. Published or uncertain Git/npm state cannot be
637
- adopted without its original journal. Tspublish and Gitea asset preparation recovery
638
- are not supported.
664
+ Recovery supports configured Git with npm and/or Docker targets, including
665
+ tspublish modules. It requires clean `main`, the exact annotated tag at that
666
+ commit, matching package and completed changelog versions, and no pending
667
+ changes. The metadata commit must not change release configuration. It also
668
+ checks remote ancestry, requires the release tag to be absent remotely, and
669
+ requires an anonymous HTTP 404 for the version of every package it publishes at
670
+ every npm registry when npm is selected. Published or uncertain Git/npm state
671
+ cannot be adopted without its original journal. Gitea asset preparation recovery
672
+ is not supported.
639
673
 
640
674
  The first attempt records the exact refs, destination and resolved workflow under
641
675
  the common Git directory in `gitzone/releases/v1/v<version>.preparation.json`.
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '6.17.1',
6
+ version: '7.0.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
  }
@@ -8,6 +8,10 @@ import {
8
8
  } from "./mod_commit/mod.helpers.js";
9
9
  import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
10
10
  import { defaultNpmVerificationWindowMinutes } from "./mod_release/helpers.npmartifact.js";
11
+ import {
12
+ planReleaseNpmPackages,
13
+ type IReleaseNpmPackageSet,
14
+ } from "./mod_release/helpers.npmpackages.js";
11
15
 
12
16
  export type TConfirmationMode = "prompt" | "auto" | "plan";
13
17
 
@@ -48,7 +52,6 @@ export interface IReleaseGitTargetConfig {
48
52
 
49
53
  export interface IReleaseNpmTargetConfig {
50
54
  enabled?: boolean;
51
- packageSource?: "root" | "tspublish";
52
55
  registries?: string[];
53
56
  accessLevel?: "public" | "private";
54
57
  alreadyPublished?: "success" | "error";
@@ -217,7 +220,8 @@ export interface IResolvedReleaseWorkflow {
217
220
  pushTags: boolean;
218
221
  npmEnabled: boolean;
219
222
  npmRegistries: string[];
220
- npmPackageSource: "root" | "tspublish";
223
+ /** What the npm target publishes, read from the project when npm is a target. */
224
+ npmPackages?: IReleaseNpmPackageSet;
221
225
  npmAccessLevel: "public" | "private";
222
226
  npmAlreadyPublished: "success" | "error";
223
227
  npmVerificationWindowMinutes: number;
@@ -236,7 +240,6 @@ export interface IResolvedReleaseWorkflow {
236
240
 
237
241
  export interface IResolvedReleaseResumeConfiguration {
238
242
  gitRemote: string;
239
- npmPackageSource: "root" | "tspublish";
240
243
  npmRegistries: string[];
241
244
  npmAccessLevel: "public" | "private";
242
245
  npmAlreadyPublished: "success" | "error";
@@ -657,6 +660,7 @@ const buildReleasePlan = (options: {
657
660
  runBuild: boolean;
658
661
  projectType: ProjectType;
659
662
  targets: TReleaseTarget[];
663
+ npmModules: boolean;
660
664
  cleanTestArtifacts: boolean;
661
665
  }): string[] => {
662
666
  const plan: string[] = ["preflight.branch", "preflight.cleanTree"];
@@ -681,6 +685,7 @@ const buildReleasePlan = (options: {
681
685
  plan.push("core.releaseCheckout");
682
686
  if (options.runBuild) plan.push("core.releaseCheckout.build");
683
687
  }
688
+ if (options.npmModules) plan.push("core.prepareNpmModules");
684
689
  if (options.targets.includes("npm")) plan.push("core.packNpmArtifact");
685
690
  if (options.targets.includes("giteaAssets"))
686
691
  plan.push("core.freezeGiteaAssets");
@@ -802,12 +807,20 @@ export const resolveNpmVerificationWindowMinutes = (
802
807
  return valueArg;
803
808
  };
804
809
 
805
- const resolveNpmPackageSource = (valueArg: unknown): "root" | "tspublish" => {
806
- if (valueArg === undefined || valueArg === "root") return "root";
807
- if (valueArg === "tspublish") return valueArg;
808
- throw new Error(
809
- "release.targets.npm.packageSource must be root or tspublish",
810
- );
810
+ /**
811
+ * The npm target reads its package set from the project, so the setting that
812
+ * used to choose between the root package and the tspublish modules is gone.
813
+ * A configuration that still carries it would expect the old behaviour.
814
+ */
815
+ const assertNoRemovedNpmTargetSettings = (
816
+ npmConfigArg: IReleaseNpmTargetConfig,
817
+ ): void => {
818
+ if (Object.hasOwn(npmConfigArg, "packageSource")) {
819
+ throw new Error(
820
+ "release.targets.npm.packageSource was removed: the npm target publishes every named ts*/tspublish.json module " +
821
+ 'and the root package unless package.json is "private": true. Remove packageSource from .smartconfig.json.',
822
+ );
823
+ }
811
824
  };
812
825
 
813
826
  export const resolveReleaseWorkflow = async (
@@ -819,6 +832,7 @@ export const resolveReleaseWorkflow = async (
819
832
  const targetConfig = releaseConfig.targets || {};
820
833
  const gitConfig = targetConfig.git || {};
821
834
  const npmConfig = targetConfig.npm || {};
835
+ assertNoRemovedNpmTargetSettings(npmConfig);
822
836
  const dockerConfig = targetConfig.docker || {};
823
837
  const rawNpmRegistries = npmConfig.registries;
824
838
  const npmRegistryConfigurationPresent = Array.isArray(rawNpmRegistries)
@@ -946,6 +960,11 @@ export const resolveReleaseWorkflow = async (
946
960
  // folder of a Deno-only commit is the one case where the plan lists the step
947
961
  // and the step then does nothing.
948
962
  const projectType = await detectProjectType(process.cwd());
963
+ // The same holds for the npm package set: the release checkout re-reads it
964
+ // from the release commit and refuses to publish a different one.
965
+ const npmPackages = targets.includes("npm")
966
+ ? (await planReleaseNpmPackages(process.cwd())).packageSet
967
+ : undefined;
949
968
 
950
969
  return {
951
970
  confirmation,
@@ -955,6 +974,7 @@ export const resolveReleaseWorkflow = async (
955
974
  runBuild,
956
975
  projectType,
957
976
  targets,
977
+ npmModules: (npmPackages?.modules.length ?? 0) > 0,
958
978
  cleanTestArtifacts,
959
979
  }),
960
980
  projectType,
@@ -974,9 +994,7 @@ export const resolveReleaseWorkflow = async (
974
994
  pushTags,
975
995
  npmEnabled,
976
996
  npmRegistries,
977
- npmPackageSource: targets.includes("npm")
978
- ? resolveNpmPackageSource(npmConfig.packageSource)
979
- : "root",
997
+ ...(npmPackages ? { npmPackages } : {}),
980
998
  npmAccessLevel: npmConfig.accessLevel || "public",
981
999
  npmAlreadyPublished: npmConfig.alreadyPublished || "success",
982
1000
  npmVerificationWindowMinutes: resolveNpmVerificationWindowMinutes(
@@ -999,6 +1017,7 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
999
1017
  const targetConfig = releaseConfig.targets || {};
1000
1018
  const gitConfig = targetConfig.git || {};
1001
1019
  const npmConfig = targetConfig.npm || {};
1020
+ assertNoRemovedNpmTargetSettings(npmConfig);
1002
1021
  if (optionsArg.giteaAssets && targetConfig.giteaAssets?.enabled !== true) {
1003
1022
  throw new Error(
1004
1023
  "The journaled Gitea asset target must remain enabled for resume.",
@@ -1060,9 +1079,6 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1060
1079
  return {
1061
1080
  gitRemote,
1062
1081
  npmRegistries,
1063
- npmPackageSource: optionsArg.npm
1064
- ? resolveNpmPackageSource(npmConfig.packageSource)
1065
- : "root",
1066
1082
  npmAccessLevel,
1067
1083
  npmAlreadyPublished,
1068
1084
  npmVerificationWindowMinutes,
@@ -2041,6 +2041,13 @@ async function validateNpmTarget(
2041
2041
  const registries = Array.isArray(npmTarget.registries)
2042
2042
  ? npmTarget.registries
2043
2043
  : [];
2044
+ if (Object.hasOwn(npmTarget, "packageSource")) {
2045
+ findings.push({
2046
+ level: "error",
2047
+ message: "release.targets.npm.packageSource is no longer supported",
2048
+ fix: 'Remove it. The npm target publishes every named ts*/tspublish.json module and the root package unless package.json is "private": true.',
2049
+ });
2050
+ }
2044
2051
  const enabled = npmTarget.enabled ?? registries.length > 0;
2045
2052
  if (!enabled) {
2046
2053
  findings.push({ level: "ok", message: "npm release target is disabled" });
@@ -2076,16 +2083,6 @@ async function validateNpmTarget(
2076
2083
  fix: "Use success or error.",
2077
2084
  });
2078
2085
  }
2079
- if (
2080
- npmTarget.packageSource !== undefined &&
2081
- !["root", "tspublish"].includes(npmTarget.packageSource)
2082
- ) {
2083
- findings.push({
2084
- level: "error",
2085
- message: `Invalid npm package source: ${npmTarget.packageSource}`,
2086
- fix: "Use root or tspublish.",
2087
- });
2088
- }
2089
2086
  try {
2090
2087
  const windowMinutes = resolveNpmVerificationWindowMinutes(
2091
2088
  npmTarget.verificationWindowMinutes,