@git.zone/cli 6.6.2 → 6.7.2

package/ts/mod_format/formatters/readme.formatter.ts

@@ -1,5 +1,5 @@
 import { BaseFormatter } from '../classes.baseformatter.js';
-import type { IPlannedChange } from '../interfaces.format.js';
+import type { IFormatWarning, IPlannedChange } from '../interfaces.format.js';
 import * as plugins from '../mod.plugins.js';
 import { logger } from '../../gitzone.logging.js';
 
@@ -7,9 +7,33 @@ const DEFAULT_README_CONTENT = `# Project Readme
 
 This is the initial readme file.`;
 
-const DEFAULT_README_HINTS_CONTENT = `# Project Readme Hints
+const DEFAULT_PLAN_CONTENT = `# Project Plan
 
-This is the initial readme hints file.`;
+This is the initial plan file. It holds implementation plans and is not published.`;
+
+const DEFAULT_HINTS_CONTENT = `# Project Hints
+
+This is the initial hints file. It holds development findings and is not published.`;
+
+/**
+ * Development documents used to live in readme.plan.md and readme.hints.md.
+ * npm-packlist force-includes every root file whose name starts with "readme",
+ * regardless of the package.json files array or .npmignore, so those documents
+ * shipped inside every published tarball. plan.md and hints.md carry the same
+ * content without being force-included.
+ */
+const DEVELOPMENT_DOCUMENTS = [
+  {
+    legacyPath: 'readme.plan.md',
+    path: 'plan.md',
+    defaultContent: DEFAULT_PLAN_CONTENT,
+  },
+  {
+    legacyPath: 'readme.hints.md',
+    path: 'hints.md',
+    defaultContent: DEFAULT_HINTS_CONTENT,
+  },
+] as const;
 
 export class ReadmeFormatter extends BaseFormatter {
   get name(): string {
@@ -19,7 +43,7 @@ export class ReadmeFormatter extends BaseFormatter {
   async analyze(): Promise<IPlannedChange[]> {
     const changes: IPlannedChange[] = [];
 
-    // Check readme.md
+    // Check readme.md - this one is meant to be published, keep it as is
     const readmeExists = await plugins.smartfs.file('readme.md').exists();
     if (!readmeExists) {
       changes.push({
@@ -31,22 +55,73 @@ export class ReadmeFormatter extends BaseFormatter {
       });
     }
 
-    // Check readme.hints.md
-    const hintsExists = await plugins.smartfs.file('readme.hints.md').exists();
-    if (!hintsExists) {
-      changes.push({
-        type: 'create',
-        path: 'readme.hints.md',
-        module: this.name,
-        description: 'Create readme.hints.md',
-        content: DEFAULT_README_HINTS_CONTENT,
-      });
+    for (const document of DEVELOPMENT_DOCUMENTS) {
+      const legacyExists = await plugins.smartfs
+        .file(document.legacyPath)
+        .exists();
+      const currentExists = await plugins.smartfs.file(document.path).exists();
+
+      if (legacyExists && currentExists) {
+        // Conflict: reported by validate(), never resolved by clobbering.
+        continue;
+      }
+
+      if (legacyExists) {
+        changes.push({
+          type: 'rename',
+          path: document.path,
+          fromPath: document.legacyPath,
+          module: this.name,
+          description: `Rename ${document.legacyPath} to ${document.path} so it is not published to npm`,
+        });
+        continue;
+      }
+
+      if (!currentExists) {
+        changes.push({
+          type: 'create',
+          path: document.path,
+          module: this.name,
+          description: `Create ${document.path}`,
+          content: document.defaultContent,
+        });
+      }
     }
 
     return changes;
   }
 
+  async validate(): Promise<IFormatWarning[]> {
+    const warnings: IFormatWarning[] = [];
+
+    for (const document of DEVELOPMENT_DOCUMENTS) {
+      const legacyExists = await plugins.smartfs
+        .file(document.legacyPath)
+        .exists();
+      const currentExists = await plugins.smartfs.file(document.path).exists();
+      if (legacyExists && currentExists) {
+        warnings.push({
+          level: 'error',
+          module: this.name,
+          message:
+            `Both ${document.legacyPath} and ${document.path} exist. ` +
+            `${document.legacyPath} is force-included in every npm tarball and must go away, ` +
+            `but ${document.path} would be overwritten. Merge them by hand, then remove ${document.legacyPath}.`,
+        });
+      }
+    }
+
+    return warnings;
+  }
+
   async applyChange(change: IPlannedChange): Promise<void> {
+    if (change.type === 'rename') {
+      if (!change.fromPath) return;
+      await this.renameFile(change.fromPath, change.path);
+      logger.log('info', `Renamed ${change.fromPath} to ${change.path}`);
+      return;
+    }
+
     if (change.type !== 'create' || !change.content) return;
 
     await this.createFile(change.path, change.content);

package/ts/mod_format/index.ts

@@ -206,6 +206,7 @@ const serializePlan = (plan: any) => {
     changes: plan.changes.map((change: any) => ({
       type: change.type,
       path: change.path,
+      fromPath: change.fromPath,
       module: change.module,
       description: change.description,
       mode: change.mode,

package/ts/mod_format/interfaces.format.ts

@@ -4,35 +4,40 @@ export type IFormatWarning = {
   module: string;
 };
 
+export type TPlannedChangeType = 'create' | 'modify' | 'delete' | 'rename';
+
 export type IFormatPlan = {
   summary: {
     totalFiles: number;
     filesAdded: number;
     filesModified: number;
     filesRemoved: number;
+    filesRenamed: number;
   };
   changes: IPlannedChange[];
   warnings: IFormatWarning[];
 };
 
 export type IPlannedChange = {
-  type: 'create' | 'modify' | 'delete';
+  type: TPlannedChangeType;
   path: string;
   module: string;
   description: string;
   content?: string; // New content for create/modify operations
   mode?: string; // Optional file mode, e.g. 0755 for generated executables
+  fromPath?: string; // Source path for rename operations, path is the destination
 };
 
 export interface ICheckResult {
   hasDiff: boolean;
   diffs: Array<{
     path: string;
-    type: 'create' | 'modify' | 'delete';
+    type: TPlannedChangeType;
     before?: string;
     after?: string;
     modeBefore?: string;
     modeAfter?: string;
+    fromPath?: string;
   }>;
 }
 

package/ts/mod_release/classes.releasejournal.ts

@@ -47,7 +47,7 @@ export interface IReleaseTargetStatus {
 
 export interface IReleaseArtifact {
   kind: "npm-tarball";
-  file: typeof releaseArtifactFileName;
+  file: string;
   packageName: string;
   version: string;
   size: number;
@@ -64,6 +64,7 @@ export interface IReleaseGitJournal extends IReleaseTargetStatus {
 
 export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
   registry: string;
+  packageName?: string;
 }
 
 export interface IReleaseJournalV1 {
@@ -135,7 +136,49 @@ export interface IReleaseJournalV2 {
   completedAt: string | null;
 }
 
-export type TReleaseJournal = IReleaseJournalV1 | IReleaseJournalV2;
+/** Ordered, independently packed modules from one tspublish repository release. */
+export interface IReleasePackage {
+  folder: string;
+  artifact: IReleaseArtifact;
+}
+
+export interface IReleaseJournalV3 extends Omit<
+  IReleaseJournalV1,
+  "schemaVersion" | "artifact"
+> {
+  schemaVersion: 3;
+  artifact: null;
+  packages: IReleasePackage[];
+}
+
+export type TReleaseJournal =
+  IReleaseJournalV1 | IReleaseJournalV2 | IReleaseJournalV3;
+
+export const releasePackageArtifactFile = (packageNameArg: string): string =>
+  `package.${plugins.crypto.createHash("sha256").update(packageNameArg).digest("hex")}.tgz`;
+
+export const getReleaseArtifacts = (
+  journalArg: TReleaseJournal,
+): IReleaseArtifact[] =>
+  journalArg.schemaVersion === 3
+    ? journalArg.packages.map((entryArg) => entryArg.artifact)
+    : journalArg.artifact
+      ? [journalArg.artifact]
+      : [];
+
+export const getReleaseNpmArtifact = (
+  journalArg: TReleaseJournal,
+  packageNameArg?: string,
+): IReleaseArtifact => {
+  const artifact =
+    journalArg.schemaVersion === 3
+      ? journalArg.packages.find(
+          (entryArg) => entryArg.artifact.packageName === packageNameArg,
+        )?.artifact
+      : journalArg.artifact;
+  if (!artifact) throw new Error("npm release target has no exact artifact.");
+  return artifact;
+};
 
 const releaseVersionRegex = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const gitOidRegex = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
@@ -356,7 +399,7 @@ const isComplete = (journalArg: TReleaseJournal): boolean => {
   ].every((stateArg) => stateArg === "verified" || stateArg === "skipped");
   if (
     !commonComplete ||
-    journalArg.schemaVersion === legacyReleaseJournalSchemaVersion
+    journalArg.schemaVersion !== releaseJournalSchemaVersion
   ) {
     return commonComplete;
   }
@@ -375,6 +418,9 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
     schemaVersion: journalArg.schemaVersion,
     release: journalArg.release,
     artifact: journalArg.artifact,
+    ...(journalArg.schemaVersion === 3
+      ? { packages: journalArg.packages }
+      : {}),
     git: {
       remote: journalArg.git.remote,
       destinationHash: journalArg.git.destinationHash,
@@ -384,8 +430,10 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
       access: journalArg.npm.access,
       tag: journalArg.npm.tag,
       alreadyPublished: journalArg.npm.alreadyPublished,
-      registries: journalArg.npm.registries.map(
-        (registryArg) => registryArg.registry,
+      registries: journalArg.npm.registries.map((registryArg) =>
+        journalArg.schemaVersion === 3
+          ? [registryArg.packageName, registryArg.registry]
+          : registryArg.registry,
       ),
     },
     docker:
@@ -994,6 +1042,138 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
   return valueArg as unknown as IReleaseJournalV2;
 };
 
+const assertReleaseJournalV3 = (
+  valueArg: Record<string, unknown>,
+): IReleaseJournalV3 => {
+  assertExactKeys(
+    valueArg,
+    [
+      "kind",
+      "schemaVersion",
+      "revision",
+      "release",
+      "artifact",
+      "packages",
+      "git",
+      "npm",
+      "createdAt",
+      "updatedAt",
+      "completedAt",
+    ],
+    "Release journal",
+  );
+  if (
+    valueArg.artifact !== null ||
+    !Array.isArray(valueArg.packages) ||
+    !valueArg.packages.length ||
+    valueArg.packages.length > 1000 ||
+    !isPlainObject(valueArg.npm) ||
+    !Array.isArray(valueArg.npm.registries)
+  ) {
+    throw new Error("Schema 3 requires an ordered npm package set.");
+  }
+  const names = new Set<string>();
+  const folders = new Set<string>();
+  const targets = valueArg.npm.registries;
+  let expectedRegistries: string[] | undefined;
+  let targetOffset = 0;
+  for (const entry of valueArg.packages) {
+    if (!isPlainObject(entry) || !isPlainObject(entry.artifact))
+      throw new Error("Invalid release package.");
+    assertExactKeys(entry, ["folder", "artifact"], "Release package");
+    if (
+      typeof entry.folder !== "string" ||
+      !/^ts(?:_[a-z0-9_]+)?$/.test(entry.folder) ||
+      folders.has(entry.folder)
+    ) {
+      throw new Error(
+        "Release package folders must be unique canonical source folders.",
+      );
+    }
+    folders.add(entry.folder);
+    const artifact = assertArtifact({
+      ...entry.artifact,
+      file: releaseArtifactFileName,
+    })!;
+    if (
+      names.has(artifact.packageName) ||
+      entry.artifact.file !== releasePackageArtifactFile(artifact.packageName)
+    ) {
+      throw new Error(
+        "Release packages require unique names and canonical artifact filenames.",
+      );
+    }
+    names.add(artifact.packageName);
+    const registries: IReleaseNpmRegistryJournal[] = [];
+    while (
+      targetOffset < targets.length &&
+      isPlainObject(targets[targetOffset]) &&
+      targets[targetOffset].packageName === artifact.packageName
+    ) {
+      const target = targets[targetOffset++];
+      assertExactKeys(
+        target,
+        ["state", "attempts", "attempt", "error", "registry", "packageName"],
+        "Release package target",
+      );
+      const { packageName, ...registry } = target;
+      registries.push(registry as unknown as IReleaseNpmRegistryJournal);
+    }
+    const registryUrls = registries.map((target) => target.registry);
+    if (
+      !registries.length ||
+      (expectedRegistries &&
+        JSON.stringify(expectedRegistries) !== JSON.stringify(registryUrls))
+    ) {
+      throw new Error(
+        "Release package targets must retain one complete, ordered registry matrix.",
+      );
+    }
+    expectedRegistries = registryUrls;
+    // Reuse the established identity, destination, state and timestamp validators.
+    // Each projection is validation-only; schema 1/2 data is never rewritten.
+    const { packages, ...common } = valueArg;
+    const complete = [
+      valueArg.git as IReleaseTargetStatus,
+      ...registries,
+    ].every(
+      (target) => target?.state === "verified" || target?.state === "skipped",
+    );
+    assertReleaseJournalV1({
+      ...common,
+      schemaVersion: 1,
+      artifact,
+      npm: { ...valueArg.npm, registries },
+      completedAt: complete ? valueArg.updatedAt : null,
+    });
+  }
+  if (targetOffset !== targets.length)
+    throw new Error("Unexpected or out-of-order release package target.");
+  const statuses = [
+    valueArg.git as IReleaseTargetStatus,
+    ...(targets as IReleaseTargetStatus[]),
+  ];
+  if (statuses.filter((target) => target.state === "publishing").length > 1) {
+    throw new Error("Schema 3 permits at most one active publication owner.");
+  }
+  const journal = valueArg as unknown as IReleaseJournalV3;
+  if (valueArg.completedAt !== null) {
+    const completedAt = assertIsoTimestamp(
+      valueArg.completedAt,
+      "Release journal completedAt",
+    );
+    if (
+      completedAt < journal.createdAt ||
+      completedAt > journal.updatedAt ||
+      !isComplete(journal)
+    ) {
+      throw new Error("Release journal completion state is inconsistent.");
+    }
+  } else if (isComplete(journal))
+    throw new Error("Complete release journal must record completedAt.");
+  return journal;
+};
+
 export const assertReleaseJournal = (valueArg: unknown): TReleaseJournal => {
   if (!isPlainObject(valueArg)) {
     throw new Error("Release journal root must be a JSON object.");
@@ -1004,6 +1184,7 @@ export const assertReleaseJournal = (valueArg: unknown): TReleaseJournal => {
   if (valueArg.schemaVersion === releaseJournalSchemaVersion) {
     return assertReleaseJournalV2(valueArg);
   }
+  if (valueArg.schemaVersion === 3) return assertReleaseJournalV3(valueArg);
   throw new Error("Release journal header is invalid or unsupported.");
 };
 
@@ -1014,7 +1195,7 @@ const prepareReleaseJournalSerialization = (
   journalArg: TReleaseJournal,
 ): TReleaseJournal => {
   const journal = assertReleaseJournal(journalArg);
-  if (journal.schemaVersion === legacyReleaseJournalSchemaVersion) {
+  if (journal.schemaVersion !== releaseJournalSchemaVersion) {
     return journal;
   }
   return {
@@ -1292,11 +1473,17 @@ export class ReleaseJournalStore {
     return plugins.path.join(this.rootPath, `v${version}`);
   }
 
-  public getArtifactPath(versionArg: string): string {
-    return plugins.path.join(
-      this.getReleaseDirectory(versionArg),
-      releaseArtifactFileName,
-    );
+  public getArtifactPath(
+    versionArg: string,
+    fileArg: string = releaseArtifactFileName,
+  ): string {
+    if (
+      fileArg !== releaseArtifactFileName &&
+      !/^package\.[0-9a-f]{64}\.tgz$/.test(fileArg)
+    ) {
+      throw new Error("Invalid release artifact filename.");
+    }
+    return plugins.path.join(this.getReleaseDirectory(versionArg), fileArg);
   }
 
   public async createTemporaryDirectory(versionArg: string): Promise<string> {
@@ -1379,6 +1566,21 @@ export class ReleaseJournalStore {
     if (journal.revision !== 1) {
       throw new Error("New release journals must start at revision 1.");
     }
+    if (
+      journal.schemaVersion === 3 &&
+      (journal.completedAt !== null ||
+        [journal.git, ...journal.npm.registries].some(
+          (target) =>
+            !["pending", "skipped"].includes(target.state) ||
+            target.attempts !== 0 ||
+            target.attempt !== null ||
+            target.error !== null,
+        ))
+    ) {
+      throw new Error(
+        "New schema 3 journals require unclaimed publication targets.",
+      );
+    }
     if (journal.schemaVersion === releaseJournalSchemaVersion) {
       const commonTargets = [journal.git, ...journal.npm.registries];
       const commonTargetsUnclaimed = commonTargets.every(
@@ -1419,28 +1621,25 @@ export class ReleaseJournalStore {
         "Prepared release directory is outside canonical storage.",
       );
     }
-    if (journal.artifact) {
-      const artifactPath = plugins.path.join(
-        temporaryDirectory,
-        releaseArtifactFileName,
-      );
+    for (const artifact of getReleaseArtifacts(journal)) {
+      const artifactPath = plugins.path.join(temporaryDirectory, artifact.file);
       const artifactStat = await plugins.fs.lstat(artifactPath);
       if (!artifactStat.isFile() || artifactStat.isSymbolicLink()) {
         throw new Error("Prepared release artifact must be a regular file.");
       }
       const artifactBytes = await plugins.fs.readFile(artifactPath);
       if (
-        artifactBytes.byteLength !== journal.artifact.size ||
+        artifactBytes.byteLength !== artifact.size ||
         plugins.crypto
           .createHash("sha1")
           .update(artifactBytes)
-          .digest("hex") !== journal.artifact.sha1 ||
+          .digest("hex") !== artifact.sha1 ||
         plugins.crypto
           .createHash("sha256")
           .update(artifactBytes)
-          .digest("hex") !== journal.artifact.sha256 ||
+          .digest("hex") !== artifact.sha256 ||
         `sha512-${plugins.crypto.createHash("sha512").update(artifactBytes).digest("base64")}` !==
-          journal.artifact.integrity
+          artifact.integrity
       ) {
         throw new Error(
           "Prepared release artifact does not match its journal identity.",