@git.zone/cli 5.0.0 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@git.zone/cli",
   "private": false,
-  "version": "5.0.0",
+  "version": "6.0.0",
   "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.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",

package/readme.hints.md

@@ -104,11 +104,57 @@ The commit module no longer bumps versions, creates tags, or publishes packages.
 - Release publishing is target-based under `@git.zone/cli.release.targets`.
 - NPM registries only live under `@git.zone/cli.release.targets.npm.registries`.
 
+### Exact artifact release journal v1
+
+Every release that reaches final Git/npm publication atomically installs
+canonical state below the Git common directory at
+`gitzone/releases/v1/v<version>/`. npm releases contain exactly one
+`package.tgz`; the journal binds that file's package identity, byte length,
+SHA-1, SHA-256, SHA-512 integrity, release commit, annotated tag object, hashed
+Git destination, registry list, and target attempts. The state is deliberately
+outside the worktree so build cleanliness checks do not conflict with durable
+recovery.
+
+Journal writes are fsynced same-directory replacements under the shared
+atomic-mkdir lock and require the caller's exact prior revision. Transactions
+may update target attempts and completion state but cannot alter release,
+artifact, destination, or target identity. A malformed, noncanonical, future,
+or manually reformatted journal fails closed.
+
+Selected Git publication requires a canonical remote name and validates its
+single resolved push URL before remote contact, including during planning.
+Embedded HTTP(S) credentials, passwords, parameters, and unsupported protocols
+fail closed. Git publication then probes the exact branch, annotated tag
+object, and peeled tag commit before and after an atomic leased push. npm publication always uses the
+stored tarball and verifies each public registry anonymously with redirects
+disabled. Verification covers metadata identity, integrity and shasum, bounded
+downloaded bytes, SHA-256, and the `latest` dist-tag.
+
+`gitzone release inspect [version]` is read-only. `gitzone release resume
+<version>` rejects fresh-release overrides and never rebuilds or repacks. It
+also rejects changed journaled configuration. A target left in `publishing`
+state first reconciles exact remote
+state. If the remote still looks absent, recovery requires the exact recorded
+attempt ID and independent proof that its process stopped; no timeout or PID
+guess reclaims publication authority.
+
+Schema v1 recovery begins only after atomic journal installation. Local
+version, changelog, commit, tag, build, and pack failures before that point, as
+well as the pre-release `--merge` integration push, require explicit operator
+reconciliation; they are not represented as publication attempts.
+
+Schema v1 supports Git and public npm only and requires resolved pnpm 11.21.0.
+Private npm cannot be anonymously verified. Docker releases remain blocked
+until tSDocker returns structured immutable digest qualification and promotion
+results. Legacy tag-triggered `npmci npm publish` jobs must be removed because
+they bypass journal ownership.
+
 **Benefits:**
 
 - Commit is safer and has no publishing side effects.
 - Multiple source commits can accumulate into one release via `Pending`.
-- Per-artifact release results can distinguish published, already-published, skipped, and failed targets.
+- Durable target states distinguish pending, publishing, verified, failed,
+  conflicting, and skipped publication while retaining exact attempt evidence.
 
 ### Auto-Accept Flag for Commits
 

package/readme.md

@@ -137,7 +137,7 @@ Commit flags:
 
 `--merge` is intentionally strict: the source and existing `main` worktree must be clean, the source must be linearly rebased onto current remote `main`, and the Git target must push both the branch and tag. GitZone pins the single configured push URL, compare-and-swap fast-forwards local `main`, updates its verified worktree, and lease-pushes that exact source commit before creating release metadata. It rejects diverged or merged history, local replacement refs or grafts, stale worktrees, incomplete shallow history, changed destinations, and remote races. If the pre-release push fails, GitZone restores local `main` only when doing so cannot overwrite concurrent work. This plumbing-level integration intentionally does not run merge hooks or write `ORIG_HEAD`.
 
-`gitzone release` performs the release core once, then publishes to configured targets. An active Git target must succeed before npm or Docker publication can start.
+`gitzone release` performs the release core once, then publishes to configured targets. An active Git target must succeed and be verified before npm publication can start.
 
 The release core is not configurable plumbing. It always follows the same professional release transaction:
 
@@ -149,14 +149,15 @@ The release core is not configurable plumbing. It always follows the same profes
 6. Move pending changelog entries into the new version section.
 7. Create the local release commit and tag on `main`.
 8. Run the configured release build, require a clean tree, and revalidate the release checkout.
+9. When npm is selected, pack it once into an exact tarball. Atomically install a durable journal for Git-only and npm releases before final Git release-ref or npm publication.
 
 Targets decide what happens after that:
 
 | Target | What it does |
 | --- | --- |
 | `git` | Atomically pushes the exact `main` release commit and new tag, often triggering remote CI release builds |
-| `npm` | Publishes the package to configured npm registries |
-| `docker` | Delegates container builds and pushes to `tsdocker` |
+| `npm` | Publishes the same journaled tarball to every configured registry and verifies its bytes anonymously |
+| `docker` | Fails closed in journal schema v1 until tSDocker provides structured digest-qualified publication results |
 
 ```bash
 # Preview the resolved release plan
@@ -171,10 +172,7 @@ gitzone release --merge
 # Release only to npm
 gitzone release --target npm
 
-# Release only to git and Docker
-gitzone release --target git,docker
-
-# Skip package/container publishing and keep only git target
+# Remove npm and Docker from the resolved targets; Git remains only if configured
 gitzone release --no-publish
 
 # Override inferred semver level
@@ -188,15 +186,57 @@ Release flags:
 | `-y`, `--yes` | Run without interactive confirmation |
 | `-t`, `--test` | Enable preflight tests |
 | `-b`, `--build` | Enable the release build after local release metadata is created |
-| `-p`, `--push` | Enable the `git` target |
-| `--target <csv>` | Use only selected targets, e.g. `git,npm` |
-| `--npm` | Enable the `npm` target |
-| `--docker` | Enable the `docker` target |
-| `--no-publish` | Keep release core and `git` target only |
+| `-p`, `--push` | Explicitly select the `git` target; combine with other target flags as needed |
+| `--target <csv>` | Replace configured targets with a non-empty comma-separated subset of `git`, `npm`, and `docker`; empty or unknown elements fail |
+| `--npm` | Explicitly select the `npm` target; combine with other target flags as needed |
+| `--docker` | Explicitly select `docker`; planning is supported, but a mutating schema v1 release fails before integration or release metadata |
+| `--no-publish` | Remove npm and Docker from the resolved target set without implicitly enabling Git |
 | `--no-build` | Disable the post-metadata release build for this run |
 | `--merge` | Fast-forward and lease-push a cleanly rebased feature branch into `main`, then release from `main` |
 | `--major`, `--minor`, `--patch` | Override inferred semver level |
 | `--plan` | Show the resolved workflow without fetching or mutating refs, files, the index, or worktrees |
+| `inspect [version]` | Read one or all durable release journals; add `--json` for machine-readable output |
+| `resume <version>` | Resume only journaled Git/npm publication; fresh-release overrides, including negated forms, are rejected, and `--json` remains inspect-only |
+| `--recover-attempt <id>` | Recover the exact 32-character lowercase hexadecimal `attempt.id` shown by `inspect --json`, after independently proving its publisher stopped |
+
+### Exact npm artifacts and release journals
+
+Journal schema v1 supports Git and public npm publication. Fresh and resumed npm publication requires the resolved `pnpm` binary to be exactly the version pinned by this package (`11.21.0`). Registries must be unique canonical credential-free HTTP(S) URLs, and `release.targets.npm.accessLevel` must be `public` so verification does not depend on publisher credentials.
+
+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.
+
+Every release that reaches final Git/npm publication stores `journal.json` under the repository's Git common directory. npm releases additionally run `pnpm pack` once and store the resulting `package.tgz` beside it:
+
+```text
+<git-common-dir>/gitzone/releases/v1/v<version>/package.tgz
+<git-common-dir>/gitzone/releases/v1/v<version>/journal.json
+```
+
+The canonical journal binds the release commit, annotated tag object, hashed Git destination, npm registries, per-target attempt states, and, when npm is selected, the package identity, tarball size, SHA-1, SHA-256, and SHA-512 integrity. Journal updates use revision compare-and-swap under an interprocess lock. Release identity and destinations cannot change after journal creation. Inspect and resume reject malformed, future, noncanonical, duplicate-key, or merely reformatted journal JSON rather than repairing or normalizing it.
+
+Packing must leave the release tree clean. Each registry receives that exact stored tarball through `pnpm publish <tarball> --ignore-scripts`, so publish lifecycle scripts do not run. Success is recorded only after anonymous no-redirect probes verify version metadata, SHA-1 and integrity fields, the downloaded tarball bytes, and the `latest` dist-tag. A matching pre-existing version follows `release.targets.npm.alreadyPublished`; conflicting bytes always stop the release, while transient responses and dist-tag propagation remain retryable.
+
+Independent tag-triggered npm publishers are incompatible with this transaction. GitZone rejects a release while `.gitea/workflows/default_tags.yaml` or `.gitlab-ci.yml` still contains the legacy `npmci npm publish` command. Apply the v6 Gitea workflow template or remove the legacy GitLab job and commit that change first.
+
+Inspect and resume without regenerating release identity:
+
+```bash
+# List journals or inspect one exact version
+gitzone release inspect
+gitzone release inspect 6.0.0 --json
+
+# Reconcile remote state, then continue only unfinished targets
+gitzone release resume 6.0.0 -y
+
+# Only after proving the recorded publisher process has stopped
+gitzone release resume 6.0.0 -y --recover-attempt="$ATTEMPT_ID"
+```
+
+Resume requires the local `main` commit, annotated release tag, and each journaled destination setting to remain exact. The Git remote must still match when Git is journaled; npm registry, access, and already-published settings must still match when npm is journaled. Non-journaled target configuration is ignored, so releases created with a target subset remain resumable. Fresh-release overrides such as targets, integration, build, test, and version flags are rejected even in negated forms such as `--no-git`, `--no-publish`, and `--no-build`; JSON output is available only through `inspect --json`. Resume probes remote state before acting. Exact remote state is accepted without republishing; positive byte, metadata, or ref conflicts fail closed, while absent, pending, inconclusive, and dist-tag propagation results do not overwrite a previously verified state. A target left in `publishing` state is never reclaimed from an absent remote result unless the exact recorded 32-character lowercase hexadecimal `attempt.id` from `git.attempt` or an npm registry attempt is supplied.
+
+Schema v1 resumes only final Git release-ref and npm publication after the journal is atomically installed. It does not recover local version, changelog, commit, tag, build, or pack failures that occur before installation, nor the pre-release `--merge` integration push. Those failures stop before the final release commit/tag or npm artifact is published and require explicit operator reconciliation.
+
+Docker target configuration remains available for planning and future journal schemas, but a mutating v6 release with an active Docker target stops before release integration or metadata changes. This restriction remains until tSDocker owns structured immutable digest qualification and promotion.
 
 ## Standard Changelog
 
@@ -218,7 +258,7 @@ The standard buckets are `Breaking Changes`, `Features`, `Fixes`, `Documentation
 
 ## Configuration
 
-CLI workflow config lives under `@git.zone/cli` in `.smartconfig.json`. Docker build and registry behavior lives under `@git.zone/tsdocker` and is used by the Docker release target.
+CLI workflow config lives under `@git.zone/cli` in `.smartconfig.json`. Dormant Docker build and registry settings remain under `@git.zone/tsdocker` for the later journal schema that will restore Docker publication.
 
 ```json
 {
@@ -249,7 +289,7 @@ CLI workflow config lives under `@git.zone/cli` in `.smartconfig.json`. Docker b
           "alreadyPublished": "success"
         },
         "docker": {
-          "enabled": true,
+          "enabled": false,
           "engine": "tsdocker",
           "registry": "registry.gitlab.com",
           "buildRegistries": ["registry.gitlab.com"],
@@ -284,23 +324,18 @@ values should be hosts without `http://` or `https://`:
 @git.zone/tsdocker.registries
 ```
 
-The Docker release target runs the project's pinned `@git.zone/tsdocker` through
-`pnpm exec`; install it in each Docker-producing project:
+Docker release configuration uses the project's pinned `@git.zone/tsdocker`
+through `pnpm exec`. Install it in each Docker-producing project, but keep the
+target disabled while release journal schema v1 is active:
 
 ```bash
 pnpm add --save-dev @git.zone/tsdocker
 ```
 
-Set `release.targets.docker.registry` to select one destination already declared
-by the tSDocker config when a release must not publish to every configured
-registry.
-Set `release.targets.docker.buildRegistries` when the build should authenticate
-only the configured registries used by private base images; an empty list keeps
-the compatibility default of authenticating every configured registry. Bounded
-build authentication requires project-local `@git.zone/tsdocker` 3.3.0 or newer.
-Set `release.targets.docker.test` to `true` to require every selected image test
-to pass before destination publication. This requires project-local
-`@git.zone/tsdocker` 3.4.0 or newer.
+The dormant `release.targets.docker.registry`, `buildRegistries`, and `test`
+settings describe the intended tSDocker destination, bounded base-image
+authentication, and pre-publication image tests. They do not execute while
+journal schema v1 is active.
 
 Useful config commands:
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/cli',
-  version: '5.0.0',
+  version: '6.0.0',
   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.'
 }

package/ts/helpers.climode.ts

@@ -24,6 +24,29 @@ interface ICliConfigSettings {
 
 type TArgSource = Record<string, any> & { _?: string[] };
 
+const booleanLongFlags = new Set([
+  "agent",
+  "allow-breaking",
+  "allow-empty",
+  "build",
+  "check-updates",
+  "docker",
+  "help",
+  "interactive",
+  "json",
+  "major",
+  "merge",
+  "minor",
+  "npm",
+  "patch",
+  "plain",
+  "plan",
+  "push",
+  "quiet",
+  "test",
+  "yes",
+]);
+
 const camelCase = (value: string): string => {
   return value.replace(/-([a-z])/g, (_match, group: string) =>
     group.toUpperCase(),
@@ -55,13 +78,23 @@ const parseRawArgv = (argv: string[]): TArgSource => {
 
     if (currentArg.startsWith("--")) {
       const withoutPrefix = currentArg.slice(2);
-      const [rawKey, inlineValue] = withoutPrefix.split("=", 2);
+      const equalsIndex = withoutPrefix.indexOf("=");
+      const rawKey =
+        equalsIndex === -1 ? withoutPrefix : withoutPrefix.slice(0, equalsIndex);
+      const inlineValue =
+        equalsIndex === -1 ? undefined : withoutPrefix.slice(equalsIndex + 1);
       if (inlineValue !== undefined) {
         parsedArgv[rawKey] = inlineValue;
         parsedArgv[camelCase(rawKey)] = inlineValue;
         continue;
       }
 
+      if (booleanLongFlags.has(rawKey)) {
+        parsedArgv[rawKey] = true;
+        parsedArgv[camelCase(rawKey)] = true;
+        continue;
+      }
+
       const nextArg = argv[i + 1];
       if (nextArg && !nextArg.startsWith("-")) {
         parsedArgv[rawKey] = nextArg;

package/ts/helpers.workflow.ts

@@ -127,6 +127,13 @@ export interface IResolvedReleaseWorkflow {
   dockerNoBuild: boolean;
 }
 
+export interface IResolvedReleaseResumeConfiguration {
+  gitRemote: string;
+  npmRegistries: string[];
+  npmAccessLevel: "public" | "private";
+  npmAlreadyPublished: "success" | "error";
+}
+
 interface ICliWorkflowConfig {
   commit?: ICommitWorkflowConfig;
   release?: IReleaseWorkflowConfig;
@@ -339,12 +346,31 @@ const normalizeCommitSteps = (rawSteps: TCommitStep[]): TCommitStep[] => {
 
 const getTargetOverride = (argvArg: any): TReleaseTarget[] | undefined => {
   const validTargets: TReleaseTarget[] = ["git", "npm", "docker"];
-  const rawTargets = argvArg.target || argvArg.targets;
-  if (typeof rawTargets === "string") {
-    return rawTargets
+  const targetKey = ["target", "targets"].find((keyArg) =>
+    Object.prototype.hasOwnProperty.call(argvArg, keyArg),
+  );
+  if (targetKey) {
+    const rawTargets = argvArg[targetKey];
+    if (typeof rawTargets !== "string" || !rawTargets.trim()) {
+      throw new Error(
+        "--target requires a non-empty comma-separated list of release targets.",
+      );
+    }
+    const requestedTargets = rawTargets
       .split(",")
-      .map((target) => target.trim())
-      .filter((target): target is TReleaseTarget => validTargets.includes(target as TReleaseTarget));
+      .map((target) => target.trim());
+    if (requestedTargets.some((target) => !target)) {
+      throw new Error(
+        "--target requires a non-empty comma-separated list of release targets.",
+      );
+    }
+    const invalidTargets = requestedTargets.filter(
+      (target) => !validTargets.includes(target as TReleaseTarget),
+    );
+    if (invalidTargets.length > 0) {
+      throw new Error(`Unknown release target: ${invalidTargets.join(", ")}`);
+    }
+    return requestedTargets as TReleaseTarget[];
   }
 
   const targets: TReleaseTarget[] = [];
@@ -369,6 +395,8 @@ const buildReleasePlan = (options: {
   }
   plan.push("core.version", "core.changelog", "core.commit", "core.tag");
   if (options.runBuild) plan.push("core.build");
+  if (options.targets.includes("npm")) plan.push("core.packNpmArtifact");
+  plan.push("core.writeReleaseJournal");
   for (const target of options.targets) {
     plan.push(`target.${target}`);
   }
@@ -435,8 +463,11 @@ export const resolveReleaseWorkflow = async (argvArg: any): Promise<IResolvedRel
   const gitConfig = targetConfig.git || {};
   const npmConfig = targetConfig.npm || {};
   const dockerConfig = targetConfig.docker || {};
-  const npmRegistries = (npmConfig.registries || []).map(normalizeRegistryUrl);
-  const npmEnabled = npmConfig.enabled ?? npmRegistries.length > 0;
+  const rawNpmRegistries = npmConfig.registries;
+  const npmRegistryConfigurationPresent = Array.isArray(rawNpmRegistries)
+    ? rawNpmRegistries.length > 0
+    : rawNpmRegistries !== undefined;
+  const npmEnabled = npmConfig.enabled ?? npmRegistryConfigurationPresent;
   const gitEnabled = gitConfig.enabled ?? true;
   const dockerEnabled = dockerConfig.enabled ?? false;
   const pushBranch = resolveGitPushSetting(
@@ -479,6 +510,22 @@ export const resolveReleaseWorkflow = async (argvArg: any): Promise<IResolvedRel
   targets = releaseTargetOrder.filter((target) =>
     selectedTargets.includes(target),
   );
+  let npmRegistries: string[] = [];
+  if (targets.includes("npm")) {
+    if (
+      rawNpmRegistries !== undefined &&
+      (!Array.isArray(rawNpmRegistries) ||
+        rawNpmRegistries.some((registryArg) => typeof registryArg !== "string"))
+    ) {
+      throw new Error("release.targets.npm.registries must be an array of strings");
+    }
+    npmRegistries = (rawNpmRegistries || []).map(normalizeRegistryUrl);
+    if (new Set(npmRegistries).size !== npmRegistries.length) {
+      throw new Error(
+        "release.targets.npm.registries must be unique after normalization",
+      );
+    }
+  }
   const mergeRequested = argvArg.merge === true;
 
   return {
@@ -521,3 +568,63 @@ export const resolveReleaseWorkflow = async (argvArg: any): Promise<IResolvedRel
     dockerNoBuild: dockerConfig.noBuild ?? false,
   };
 };
+
+export const resolveReleaseResumeConfiguration = async (optionsArg: {
+  git: boolean;
+  npm: boolean;
+}): Promise<IResolvedReleaseResumeConfiguration> => {
+  const cliConfig = await readCliWorkflowConfig();
+  const releaseConfig = cliConfig.release || {};
+  const targetConfig = releaseConfig.targets || {};
+  const gitConfig = targetConfig.git || {};
+  const npmConfig = targetConfig.npm || {};
+
+  const gitRemote = optionsArg.git ? gitConfig.remote || "origin" : "origin";
+  if (typeof gitRemote !== "string" || !gitRemote.trim()) {
+    throw new Error("release.targets.git.remote must be a non-empty string");
+  }
+
+  let npmRegistries: string[] = [];
+  let npmAccessLevel: "public" | "private" = "public";
+  let npmAlreadyPublished: "success" | "error" = "success";
+  if (optionsArg.npm) {
+    if (
+      npmConfig.registries !== undefined &&
+      (!Array.isArray(npmConfig.registries) ||
+        npmConfig.registries.some((registryArg) => typeof registryArg !== "string"))
+    ) {
+      throw new Error("release.targets.npm.registries must be an array of strings");
+    }
+    npmRegistries = (npmConfig.registries || []).map(normalizeRegistryUrl);
+    if (new Set(npmRegistries).size !== npmRegistries.length) {
+      throw new Error(
+        "release.targets.npm.registries must be unique after normalization",
+      );
+    }
+    if (
+      npmConfig.accessLevel !== undefined &&
+      npmConfig.accessLevel !== "public" &&
+      npmConfig.accessLevel !== "private"
+    ) {
+      throw new Error("release.targets.npm.accessLevel must be public or private");
+    }
+    if (
+      npmConfig.alreadyPublished !== undefined &&
+      npmConfig.alreadyPublished !== "success" &&
+      npmConfig.alreadyPublished !== "error"
+    ) {
+      throw new Error(
+        "release.targets.npm.alreadyPublished must be success or error",
+      );
+    }
+    npmAccessLevel = npmConfig.accessLevel || "public";
+    npmAlreadyPublished = npmConfig.alreadyPublished || "success";
+  }
+
+  return {
+    gitRemote,
+    npmRegistries,
+    npmAccessLevel,
+    npmAlreadyPublished,
+  };
+};