@git.zone/cli 6.10.0 → 6.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@git.zone/cli",
   "private": false,
-  "version": "6.10.0",
+  "version": "6.12.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",
@@ -48,7 +48,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "3.1095.0",
     "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsdocker": "3.5.2",
+    "@git.zone/tsdocker": "3.5.6",
     "@git.zone/tspublish": "^1.14.0",
     "@push.rocks/commitinfo": "^1.0.13",
     "@push.rocks/early": "^4.0.4",

package/readme.md

@@ -107,6 +107,12 @@ gitzone commit -ytbp
 
 # Show the resolved workflow without mutating anything
 gitzone commit --plan
+
+# Supply a message and changelog entry without AI
+gitzone commit -y --message 'fix(cache): expire stale entries' --changelog 'Expired entries are removed before lookup.'
+
+# Preserve a multiline message and custom Pending Markdown
+gitzone commit -y --message-file /tmp/commit.txt --changelog-file /tmp/pending.md
 ```
 
 The commit flow:
@@ -128,6 +134,43 @@ Commit flags:
 | `-p`, `--push`     | Push after the source commit                                   |
 | `-f`, `--format`   | Run `gitzone format --write` before commit                     |
 | `--plan`           | Show resolved workflow only                                    |
+| `-m`, `--message <text>` | Use a complete semantic commit message without AI         |
+| `--message-file <path>` | Read the complete message from a UTF-8 file                 |
+| `--changelog <text>` | Supply custom Pending text with a manual message                |
+| `--changelog-file <path>` | Read custom Pending text from a UTF-8 file                 |
+
+Manual messages start with `type(scope): description`; the scope is optional.
+Conventional `!` subjects and `BREAKING CHANGE:` footers are supported. The entire
+message, including its body, is passed literally to Git. File inputs preserve
+multiline text; CRLF becomes LF and terminal newlines are normalized. Each input
+is limited to 128 KiB. Use `--message` or `--message-file` once, and at most one
+changelog option. Changelog overrides require a manual message.
+
+Without a changelog override, GitZone derives the Pending entry from the semantic
+subject and body. Custom text becomes an entry in the message's semantic bucket.
+For complete Markdown, supply a Pending fragment such as:
+
+```markdown
+### Fixes
+
+- Remove expired entries before lookup.
+  - Preserve entries whose validity has not expired.
+```
+
+Fragments may contain `### Breaking Changes`, `### Features`, `### Fixes`,
+`### Documentation`, and `### Maintenance`. Omit the document title, `## Pending`,
+and version headings. GitZone merges entries into the existing Pending buckets
+and preserves previous entries and release history. Pending headings continue to
+determine the release bump; a breaking message requires a Breaking Changes entry,
+and either a breaking message or new breaking changelog text requires the usual
+interactive confirmation or `-y --allow-breaking`.
+
+Manual mode replaces the AI analysis step with `manual`. It keeps the configured
+format, test, build, staging and push behavior. `--plan` validates and displays the
+message and changelog without mutation or AI access. A clean repository remains
+unchanged. Input is validated before workflow steps run; it never falls back to AI
+after an input error. Place input files outside the repository if they should not
+be included by the existing stage-all workflow.
 
 `-r` is intentionally not part of commit anymore. Use `gitzone release`.
 
@@ -206,7 +249,7 @@ Release flags:
 
 ### Exact artifacts and release journals
 
-Journal schema 1 supports Git and public npm publication. Schema 2 adds Docker qualification, promotion, and cleanup evidence without changing the storage path or schema-1 parsing and resume behavior. Fresh and resumed npm publication requires a qualified exact `pnpm` version: `11.25.0`, `12.1.0`, `12.2.1`, `12.3.0`, or `12.3.4`. GitZone checks that version's pack/publish command contract; other versions and missing required capabilities fail before publication. 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.
+Journal schema 1 supports Git and public npm publication. Schema 2 adds Docker qualification, promotion, and cleanup evidence without changing the storage path or schema-1 parsing and resume behavior. Fresh and resumed npm publication dynamically qualifies the active stable `pnpm` version; there is no version allowlist. GitZone reads `minimum-release-age` and `minimum-release-age-exclude` through that exact pnpm invocation in the release directory, so project configuration and global policy retain pnpm's normal precedence. It verifies the selected version's publication time through the configured registry unless the effective policy disables the age delay or excludes that version. Missing timestamps follow `minimum-release-age-ignore-missing-time`, including pnpm's default of `true`; malformed policy, metadata failures, immature versions, and prerelease versions stop qualification. GitZone also verifies the required pack/publish command contract and keeps every subsequent command bound to the qualified exact version. A new pnpm version with the same capabilities needs no GitZone update once it satisfies the policy. 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.
 
 GitZone keeps the selected pnpm version for help checks, packing, and publication
 through `pnpm with <version>`, including release recovery and resume. This avoids
@@ -214,7 +257,7 @@ mixing a launcher's help output with a project-selected package-manager version.
 Use a standalone pnpm installation; Corepack launchers cannot run `pnpm with`.
 The normal release-age policy also applies when pnpm provisions that version.
 
-The pnpm release tests keep deterministic contracts for every supported version
+The pnpm release tests cover known command dialects and dynamic version qualification
 and qualify actual packaging and script-free tarball publication with the active
 version. Run `testUnit` with each maturity-eligible standalone version and a matching
 project pin in an isolated checkout. For a focused matrix, invoke the project-local

package/ts/00_commitinfo_data.ts

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

@@ -1,11 +1,7 @@
 import * as plugins from "./plugins.js";
 
 export type TChangelogBucket =
-  | "Breaking Changes"
-  | "Features"
-  | "Fixes"
-  | "Documentation"
-  | "Maintenance";
+  "Breaking Changes" | "Features" | "Fixes" | "Documentation" | "Maintenance";
 
 export interface IChangelogEntry {
   type: string;
@@ -25,7 +21,7 @@ interface IChangelogSection {
   end: number;
 }
 
-const bucketForCommitType = (commitType: string): TChangelogBucket => {
+export const bucketForCommitType = (commitType: string): TChangelogBucket => {
   switch (commitType) {
     case "BREAKING CHANGE":
       return "Breaking Changes";
@@ -44,18 +40,30 @@ const readChangelog = async (filePath: string): Promise<string> => {
   if (!(await plugins.smartfs.file(filePath).exists())) {
     return "# Changelog\n\n";
   }
-  return (await plugins.smartfs.file(filePath).encoding("utf8").read()) as string;
+  return (await plugins.smartfs
+    .file(filePath)
+    .encoding("utf8")
+    .read()) as string;
 };
 
-const writeChangelog = async (filePath: string, content: string): Promise<void> => {
-  await plugins.smartfs.file(filePath).encoding("utf8").write(content.endsWith("\n") ? content : `${content}\n`);
+const writeChangelog = async (
+  filePath: string,
+  content: string,
+): Promise<void> => {
+  await plugins.smartfs
+    .file(filePath)
+    .encoding("utf8")
+    .write(content.endsWith("\n") ? content : `${content}\n`);
 };
 
 const findPendingSection = (
   content: string,
   sectionName: string,
 ): IChangelogSection | null => {
-  const headingRegex = new RegExp(`^##\\s+${sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
+  const headingRegex = new RegExp(
+    `^##\\s+${sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`,
+    "m",
+  );
   const match = headingRegex.exec(content);
   if (!match || match.index === undefined) {
     return null;
@@ -64,7 +72,9 @@ const findPendingSection = (
   const bodyStart = match.index + match[0].length;
   const rest = content.slice(bodyStart);
   const nextHeadingMatch = /^##\s+/m.exec(rest);
-  const end = nextHeadingMatch ? bodyStart + nextHeadingMatch.index : content.length;
+  const end = nextHeadingMatch
+    ? bodyStart + nextHeadingMatch.index
+    : content.length;
   return { start: match.index, bodyStart, end };
 };
 
@@ -95,30 +105,89 @@ export const appendPendingChangelogEntry = async (
   sectionName: string,
   entry: IChangelogEntry,
 ): Promise<void> => {
-  let content = await ensurePendingSection(filePath, sectionName);
-  const pendingSection = findPendingSection(content, sectionName)!;
-  let pendingBody = content.slice(pendingSection.bodyStart, pendingSection.end);
   const bucket = bucketForCommitType(entry.type);
-  const bucketHeading = `### ${bucket}`;
-
-  const entryLines = [`- ${entry.message}${entry.scope ? ` (${entry.scope})` : ""}`];
+  const entryLines = [
+    `- ${entry.message}${entry.scope ? ` (${entry.scope})` : ""}`,
+  ];
   for (const detail of entry.details || []) {
     entryLines.push(`  - ${detail}`);
   }
   const renderedEntry = entryLines.join("\n");
+  await appendPendingChangelogMarkdown(
+    filePath,
+    sectionName,
+    `### ${bucket}\n\n${renderedEntry}`,
+  );
+};
 
-  const bucketRegex = new RegExp(`^###\\s+${bucket.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
-  const bucketMatch = bucketRegex.exec(pendingBody);
-  if (!bucketMatch || bucketMatch.index === undefined) {
-    pendingBody = `${pendingBody.trimEnd()}\n\n${bucketHeading}\n\n${renderedEntry}\n`;
-  } else {
-    const bucketBodyStart = bucketMatch.index + bucketMatch[0].length;
-    const afterBucket = pendingBody.slice(bucketBodyStart);
-    const nextBucketMatch = /^###\s+/m.exec(afterBucket);
-    const insertAt = nextBucketMatch ? bucketBodyStart + nextBucketMatch.index : pendingBody.length;
-    const beforeInsert = pendingBody.slice(0, insertAt).trimEnd();
-    const afterInsert = pendingBody.slice(insertAt).replace(/^\n+/, "");
-    pendingBody = `${beforeInsert}\n${renderedEntry}\n\n${afterInsert}`;
+/** A Pending fragment contains canonical buckets, never the document/version headings. */
+export const validatePendingChangelogMarkdown = (markdown: string): void => {
+  const headings = [...markdown.matchAll(/^#{1,3}\s+.*$/gm)].map(
+    (match) => match[0],
+  );
+  const allowed = new Set(
+    [
+      "Breaking Changes",
+      "Features",
+      "Fixes",
+      "Documentation",
+      "Maintenance",
+    ].map((bucket) => `### ${bucket}`),
+  );
+  if (
+    !markdown.startsWith("### ") ||
+    headings.length === 0 ||
+    headings.some((heading) => !allowed.has(heading))
+  ) {
+    throw new Error(
+      "Changelog fragments must use canonical ### bucket headings, without title, Pending or version headings.",
+    );
+  }
+  for (const block of markdown.split(/^### .+\n?/m).slice(1)) {
+    if (!block.trim())
+      throw new Error("Changelog buckets must contain an entry.");
+  }
+};
+
+export const appendPendingChangelogMarkdown = async (
+  filePath: string,
+  sectionName: string,
+  markdown: string,
+): Promise<void> => {
+  validatePendingChangelogMarkdown(markdown);
+  let content = await ensurePendingSection(filePath, sectionName);
+  const pendingSection = findPendingSection(content, sectionName)!;
+  let pendingBody = content.slice(pendingSection.bodyStart, pendingSection.end);
+  const sections = [...markdown.matchAll(/^### (.+)\n/gm)];
+  for (let index = 0; index < sections.length; index++) {
+    const section = sections[index];
+    const bucket = section[1];
+    const bucketHeading = `### ${bucket}`;
+    const renderedEntry = markdown
+      .slice(
+        section.index! + section[0].length,
+        sections[index + 1]?.index ?? markdown.length,
+      )
+      .trim();
+
+    const bucketRegex = new RegExp(
+      `^###\\s+${bucket.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`,
+      "m",
+    );
+    const bucketMatch = bucketRegex.exec(pendingBody);
+    if (!bucketMatch || bucketMatch.index === undefined) {
+      pendingBody = `${pendingBody.trimEnd()}\n\n${bucketHeading}\n\n${renderedEntry}\n`;
+    } else {
+      const bucketBodyStart = bucketMatch.index + bucketMatch[0].length;
+      const afterBucket = pendingBody.slice(bucketBodyStart);
+      const nextBucketMatch = /^###\s+/m.exec(afterBucket);
+      const insertAt = nextBucketMatch
+        ? bucketBodyStart + nextBucketMatch.index
+        : pendingBody.length;
+      const beforeInsert = pendingBody.slice(0, insertAt).trimEnd();
+      const afterInsert = pendingBody.slice(insertAt).replace(/^\n+/, "");
+      pendingBody = `${beforeInsert}\n${renderedEntry}\n\n${afterInsert}`;
+    }
   }
 
   content = `${content.slice(0, pendingSection.bodyStart)}\n${pendingBody.trim()}\n\n${content.slice(pendingSection.end).replace(/^\n+/, "")}`;
@@ -140,7 +209,9 @@ export const readPendingChangelog = async (
   };
 };
 
-export const inferVersionTypeFromPending = (pendingBlock: string): "patch" | "minor" | "major" => {
+export const inferVersionTypeFromPending = (
+  pendingBlock: string,
+): "patch" | "minor" | "major" => {
   if (/^###\s+Breaking Changes\s*$/m.test(pendingBlock)) {
     return "major";
   }
@@ -162,7 +233,9 @@ export const movePendingToVersion = async (
   if (!pendingSection) {
     throw new Error("No pending changelog entries. Nothing to release.");
   }
-  const pendingBlock = content.slice(pendingSection.bodyStart, pendingSection.end).trim();
+  const pendingBlock = content
+    .slice(pendingSection.bodyStart, pendingSection.end)
+    .trim();
   if (!pendingBlock) {
     throw new Error("No pending changelog entries. Nothing to release.");
   }
@@ -171,7 +244,10 @@ export const movePendingToVersion = async (
     .replaceAll("{{version}}", version)
     .replaceAll("{{date}}", dateString);
   const beforePending = content.slice(0, pendingSection.start).trimEnd();
-  const afterPending = content.slice(pendingSection.end).replace(/^\n+/, "").trimEnd();
+  const afterPending = content
+    .slice(pendingSection.end)
+    .replace(/^\n+/, "")
+    .trimEnd();
   content = [beforePending, renderedHeading, pendingBlock, afterPending]
     .filter((block) => block.length > 0)
     .join("\n\n");

package/ts/helpers.climode.ts

@@ -24,6 +24,13 @@ interface ICliConfigSettings {
 
 type TArgSource = Record<string, any> & { _?: string[] };
 
+const commitValueFlags = new Set([
+  "message",
+  "message-file",
+  "changelog",
+  "changelog-file",
+]);
+
 const booleanLongFlags = new Set([
   "agent",
   "allow-breaking",
@@ -65,10 +72,23 @@ const getArgValue = (argvArg: TArgSource, key: string): any => {
 
 const parseRawArgv = (argv: string[]): TArgSource => {
   const parsedArgv: TArgSource = { _: [] };
+  const setCommitValue = (key: string, value: string | undefined): void => {
+    if (Object.hasOwn(parsedArgv, key))
+      throw new Error(`--${key} may only be supplied once.`);
+    if (value === undefined || value.length === 0)
+      throw new Error(`--${key} requires a value.`);
+    parsedArgv[key] = value;
+    parsedArgv[camelCase(key)] = value;
+  };
 
   for (let i = 0; i < argv.length; i++) {
     const currentArg = argv[i];
 
+    if (currentArg === "--") {
+      parsedArgv._!.push(...argv.slice(i + 1));
+      break;
+    }
+
     if (currentArg.startsWith("--no-")) {
       const key = currentArg.slice(5);
       parsedArgv[key] = false;
@@ -80,9 +100,20 @@ const parseRawArgv = (argv: string[]): TArgSource => {
       const withoutPrefix = currentArg.slice(2);
       const equalsIndex = withoutPrefix.indexOf("=");
       const rawKey =
-        equalsIndex === -1 ? withoutPrefix : withoutPrefix.slice(0, equalsIndex);
+        equalsIndex === -1
+          ? withoutPrefix
+          : withoutPrefix.slice(0, equalsIndex);
       const inlineValue =
         equalsIndex === -1 ? undefined : withoutPrefix.slice(equalsIndex + 1);
+      if (commitValueFlags.has(rawKey)) {
+        const next = argv[i + 1];
+        setCommitValue(
+          rawKey,
+          inlineValue ?? (next && !next.startsWith("-") ? next : undefined),
+        );
+        if (inlineValue === undefined) i++;
+        continue;
+      }
       if (inlineValue !== undefined) {
         parsedArgv[rawKey] = inlineValue;
         parsedArgv[camelCase(rawKey)] = inlineValue;
@@ -108,7 +139,19 @@ const parseRawArgv = (argv: string[]): TArgSource => {
     }
 
     if (currentArg.startsWith("-") && currentArg.length > 1) {
-      for (const shortFlag of currentArg.slice(1).split("")) {
+      const flags = currentArg.slice(1);
+      for (let flagIndex = 0; flagIndex < flags.length; flagIndex++) {
+        const shortFlag = flags[flagIndex];
+        if (shortFlag === "m") {
+          const attached = flags.slice(flagIndex + 1);
+          const next = argv[i + 1];
+          setCommitValue(
+            "message",
+            attached || (next && !next.startsWith("-") ? next : undefined),
+          );
+          if (!attached) i++;
+          break;
+        }
         parsedArgv[shortFlag] = true;
       }
       continue;

package/ts/helpers.workflow.ts

@@ -1,4 +1,5 @@
 import { getCliConfigValue } from "./helpers.smartconfig.js";
+import { getProcessUserArgv } from "./helpers.climode.js";
 
 export type TConfirmationMode = "prompt" | "auto" | "plan";
 
@@ -171,7 +172,7 @@ export interface IReleaseWorkflowConfig {
 export interface IResolvedCommitWorkflow {
   confirmation: TConfirmationMode;
   allowBreaking: boolean;
-  steps: TCommitStep[];
+  steps: Array<TCommitStep | "manual">;
   staging: "all";
   testCommand: string;
   buildCommand: string;
@@ -479,7 +480,7 @@ const readCliWorkflowConfig = async (): Promise<ICliWorkflowConfig> => {
 };
 
 const getOrderedArgsAfterCommand = (commandName: string): string[] => {
-  const rawArgs = process.argv.slice(2);
+  const rawArgs = getProcessUserArgv();
   const commandIndex = rawArgs.indexOf(commandName);
   if (commandIndex === -1) {
     return rawArgs;
@@ -489,15 +490,29 @@ const getOrderedArgsAfterCommand = (commandName: string): string[] => {
 
 const getOrderedShortFlags = (commandName: string): string[] => {
   const orderedFlags: string[] = [];
-  for (const arg of getOrderedArgsAfterCommand(commandName)) {
+  const args = getOrderedArgsAfterCommand(commandName);
+  const valueFlags = new Set([
+    "--message",
+    "--message-file",
+    "--changelog",
+    "--changelog-file",
+  ]);
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
     if (arg === "--") {
       break;
     }
     if (arg.startsWith("--")) {
+      if (valueFlags.has(arg)) index++;
       continue;
     }
     if (arg.startsWith("-") && arg.length > 1) {
-      orderedFlags.push(...arg.slice(1).split(""));
+      const flags = arg.slice(1);
+      const messageIndex = flags.indexOf("m");
+      orderedFlags.push(
+        ...(messageIndex < 0 ? flags : flags.slice(0, messageIndex)).split(""),
+      );
+      if (messageIndex === flags.length - 1) index++;
     }
   }
   return orderedFlags;
@@ -545,6 +560,9 @@ const normalizeCommitSteps = (rawSteps: TCommitStep[]): TCommitStep[] => {
   }
 
   const changelogIndex = prePushSteps.indexOf("changelog");
+  if (analyzeIndex > changelogIndex) {
+    throw new Error("Commit workflow requires analyze before changelog.");
+  }
   if (changelogIndex === -1 || changelogIndex > commitIndex) {
     throw new Error("Commit workflow requires changelog before commit.");
   }
@@ -633,7 +651,28 @@ const buildReleasePlan = (options: {
 
 export const resolveCommitWorkflow = async (
   argvArg: any,
+  inputMode: "ai" | "manual" = "ai",
 ): Promise<IResolvedCommitWorkflow> => {
+  for (const flag of [
+    "y",
+    "yes",
+    "allow-breaking",
+    "allowBreaking",
+    "plan",
+    "f",
+    "format",
+    "t",
+    "test",
+    "b",
+    "build",
+    "p",
+    "push",
+  ]) {
+    if (argvArg[flag] !== undefined && typeof argvArg[flag] !== "boolean")
+      throw new Error(
+        `Commit option ${flag} must be a bare Boolean flag without a value.`,
+      );
+  }
   const cliConfig = await readCliWorkflowConfig();
   const commitConfig = cliConfig.commit || {};
   const releaseFlagRequested = Boolean(argvArg.r || argvArg.release);
@@ -677,7 +716,9 @@ export const resolveCommitWorkflow = async (
   return {
     confirmation,
     allowBreaking: Boolean(argvArg["allow-breaking"] || argvArg.allowBreaking),
-    steps: normalizeCommitSteps(rawSteps),
+    steps: normalizeCommitSteps(rawSteps).map((step) =>
+      inputMode === "manual" && step === "analyze" ? "manual" : step,
+    ),
     staging: commitConfig.staging || "all",
     testCommand: commitConfig.test?.command || "pnpm test",
     buildCommand: commitConfig.build?.command || "pnpm build",

package/ts/mod_commit/helpers.manual.ts

@@ -0,0 +1,156 @@
+import * as plugins from "./mod.plugins.js";
+import {
+  bucketForCommitType,
+  inferVersionTypeFromPending,
+  validatePendingChangelogMarkdown,
+} from "../helpers.changelog.js";
+
+export interface IManualCommitInput {
+  message: string;
+  type: string;
+  scope: string;
+  summary: string;
+  changelog: string;
+  breaking: boolean;
+}
+
+const maximumInputBytes = 128 * 1024;
+const keys = [
+  "message",
+  "message-file",
+  "changelog",
+  "changelog-file",
+] as const;
+type TInputKey = (typeof keys)[number];
+const readArg = (argv: Record<string, unknown>, key: TInputKey): unknown =>
+  argv[key] ??
+  argv[key.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())];
+
+export const hasManualCommitInput = (argv: Record<string, unknown>): boolean =>
+  keys.some((key) => readArg(argv, key) !== undefined);
+
+const readInput = async (
+  value: unknown,
+  fromFile: boolean,
+  cwd: string,
+): Promise<string> => {
+  if (typeof value !== "string" || !value.trim() || value.includes("\0"))
+    throw new Error(
+      "Manual commit inputs require non-empty text or file paths.",
+    );
+  let text = value;
+  if (fromFile) {
+    const file = await plugins.fs.open(
+      plugins.path.resolve(cwd, value),
+      plugins.fsConstants.O_RDONLY | plugins.fsConstants.O_NONBLOCK,
+    );
+    try {
+      const stat = await file.stat();
+      if (!stat.isFile() || stat.size > maximumInputBytes)
+        throw new Error(
+          "Manual input files must be regular files of at most 128 KiB.",
+        );
+      const bytes = Buffer.alloc(maximumInputBytes + 1);
+      let length = 0;
+      while (length < bytes.length) {
+        const part = await file.read(
+          bytes,
+          length,
+          bytes.length - length,
+          null,
+        );
+        if (!part.bytesRead) break;
+        length += part.bytesRead;
+      }
+      if (length > maximumInputBytes)
+        throw new Error("Manual inputs must be at most 128 KiB.");
+      text = new TextDecoder("utf-8", { fatal: true }).decode(
+        bytes.subarray(0, length),
+      );
+    } finally {
+      await file.close();
+    }
+  }
+  text = text.replace(/\r\n/g, "\n").replace(/\n+$/, "");
+  if (
+    !text.trim() ||
+    Buffer.byteLength(text, "utf8") > maximumInputBytes ||
+    /[\u0000-\u0008\u000b-\u001f\u007f]/.test(text)
+  ) {
+    throw new Error(
+      "Manual inputs must contain non-empty text without control characters, at most 128 KiB.",
+    );
+  }
+  return text;
+};
+
+export const loadManualCommitInput = async (
+  argv: Record<string, unknown>,
+  cwd: string,
+): Promise<IManualCommitInput | undefined> => {
+  if (!hasManualCommitInput(argv)) return undefined;
+  const message = readArg(argv, "message");
+  const messageFile = readArg(argv, "message-file");
+  const changelog = readArg(argv, "changelog");
+  const changelogFile = readArg(argv, "changelog-file");
+  if ((message === undefined) === (messageFile === undefined))
+    throw new Error(
+      "Supply exactly one of --message or --message-file for a manual commit.",
+    );
+  if (changelog !== undefined && changelogFile !== undefined)
+    throw new Error("Supply only one of --changelog or --changelog-file.");
+  const fullMessage = await readInput(
+    message ?? messageFile,
+    messageFile !== undefined,
+    cwd,
+  );
+  const [subject, ...body] = fullMessage.split("\n");
+  const parsed =
+    /^(BREAKING CHANGE|[a-z][a-z0-9-]*)(?:\(([^():\r\n]+)\))?(!)?: (\S.*)$/.exec(
+      subject,
+    );
+  if (!parsed)
+    throw new Error(
+      "Manual messages must start with a semantic subject: type(scope): description, with optional scope and !.",
+    );
+  const [, originalType, scope = "", bang, summary] = parsed;
+  const messageBreaking =
+    originalType === "BREAKING CHANGE" ||
+    Boolean(bang) ||
+    /^BREAKING[ -]CHANGE:\s*\S/m.test(fullMessage);
+  const type = messageBreaking ? "BREAKING CHANGE" : originalType;
+  let markdown: string;
+  if (changelog !== undefined || changelogFile !== undefined) {
+    const text = (
+      await readInput(
+        changelog ?? changelogFile,
+        changelogFile !== undefined,
+        cwd,
+      )
+    ).trim();
+    if (/^#{1,3}\s/m.test(text)) {
+      markdown = text;
+    } else {
+      markdown = `### ${bucketForCommitType(type)}\n\n- ${text.replace(/\n/g, "\n  ")}`;
+    }
+  } else {
+    const details = body
+      .filter((line) => line.trim())
+      .map((line) => `  - ${line.trim()}`);
+    markdown = `### ${bucketForCommitType(type)}\n\n- ${summary}${scope ? ` (${scope})` : ""}${details.length ? "\n" + details.join("\n") : ""}`;
+  }
+  validatePendingChangelogMarkdown(markdown);
+  const changelogBreaking = inferVersionTypeFromPending(markdown) === "major";
+  if (messageBreaking && !changelogBreaking)
+    throw new Error(
+      "A breaking commit requires a Breaking Changes changelog bucket.",
+    );
+  return {
+    message: fullMessage,
+    type,
+    scope,
+    summary,
+    changelog: markdown,
+    breaking: messageBreaking || changelogBreaking,
+  };
+};