@git.zone/cli 6.11.0 → 6.12.0

package/ts/mod_commit/index.ts

@@ -5,15 +5,27 @@ import * as paths from "../paths.js";
 import { logger } from "../gitzone.logging.js";
 import * as ui from "./mod.ui.js";
 import type { ICliMode } from "../helpers.climode.js";
-import { getCliMode, printJson, runWithSuppressedOutput } from "../helpers.climode.js";
-import { appendPendingChangelogEntry } from "../helpers.changelog.js";
-import { resolveCommitWorkflow, type IResolvedCommitWorkflow } from "../helpers.workflow.js";
+import {
+  getCliMode,
+  printJson,
+  runWithSuppressedOutput,
+} from "../helpers.climode.js";
+import {
+  appendPendingChangelogEntry,
+  appendPendingChangelogMarkdown,
+} from "../helpers.changelog.js";
+import {
+  resolveCommitWorkflow,
+  type IResolvedCommitWorkflow,
+} from "../helpers.workflow.js";
+import {
+  hasManualCommitInput,
+  loadManualCommitInput,
+  type IManualCommitInput,
+} from "./helpers.manual.js";
 
 const isNoChangesError = (error: unknown): boolean => {
-  return (
-    error instanceof plugins.tsdoc.NoChangesError ||
-    (error instanceof Error && error.name === "NoChangesError")
-  );
+  return error instanceof Error && error.name === "NoChangesError";
 };
 
 export const run = async (argvArg: any) => {
@@ -26,6 +38,8 @@ export const run = async (argvArg: any) => {
   }
 
   if (subcommand === "recommend") {
+    if (hasManualCommitInput(argvArg))
+      throw new Error("Manual input cannot be combined with commit recommend.");
     await handleRecommend(mode);
     return;
   }
@@ -39,7 +53,11 @@ export const run = async (argvArg: any) => {
     return;
   }
 
-  const workflow = await resolveCommitWorkflow(argvArg);
+  const manual = await loadManualCommitInput(argvArg, paths.cwd);
+  const workflow = await resolveCommitWorkflow(
+    argvArg,
+    manual ? "manual" : "ai",
+  );
   if (workflow.releaseFlagRequested) {
     logger.log(
       "warn",
@@ -47,7 +65,7 @@ export const run = async (argvArg: any) => {
     );
   }
 
-  printCommitExecutionPlan(workflow);
+  printCommitExecutionPlan(workflow, manual);
   if (workflow.confirmation === "plan") {
     return;
   }
@@ -59,6 +77,8 @@ export const run = async (argvArg: any) => {
 
   let nextCommitObject: any;
   let answerBucket: plugins.smartinteract.AnswerBucket | undefined;
+  if (manual && !(await hasManualCommitChanges(smartshellInstance))) return;
+  if (manual && !(await confirmManualCommit(manual, workflow, mode))) return;
 
   for (const step of workflow.steps) {
     switch (step) {
@@ -66,30 +86,69 @@ export const run = async (argvArg: any) => {
         await runFormatStep();
         break;
       case "test":
-        await runCommandStep(smartshellInstance, "Running tests", workflow.testCommand);
+        await runCommandStep(
+          smartshellInstance,
+          "Running tests",
+          workflow.testCommand,
+        );
         break;
       case "build":
-        await runCommandStep(smartshellInstance, "Running build", workflow.buildCommand);
+        await runCommandStep(
+          smartshellInstance,
+          "Running build",
+          workflow.buildCommand,
+        );
         break;
       case "analyze":
         try {
           nextCommitObject = await runAnalyzeStep();
         } catch (error) {
           if (isNoChangesError(error)) {
-            logger.log("info", "No uncommitted changes found. Nothing to commit.");
+            logger.log(
+              "info",
+              "No uncommitted changes found. Nothing to commit.",
+            );
             return;
           }
           throw error;
         }
-        answerBucket = await buildAnswerBucket(nextCommitObject, workflow, mode, argvArg);
+        answerBucket = await buildAnswerBucket(
+          nextCommitObject,
+          workflow,
+          mode,
+          argvArg,
+        );
+        break;
+      case "manual": {
+        if (!manual) throw new Error("Manual commit input is required.");
+        if (!(await hasManualCommitChanges(smartshellInstance))) return;
+        nextCommitObject = { manual: true };
+        answerBucket = createAnswerBucket({
+          commitType: manual.type,
+          commitScope: manual.scope,
+          commitDescription: manual.summary,
+        });
         break;
+      }
       case "changelog":
         assertAnalysisComplete(answerBucket, nextCommitObject);
-        await runChangelogStep(workflow, answerBucket!, nextCommitObject);
+        if (manual) {
+          await appendPendingChangelogMarkdown(
+            plugins.path.join(paths.cwd, workflow.changelogFile),
+            workflow.changelogSection,
+            manual.changelog,
+          );
+          logger.log(
+            "success",
+            `Updated ${workflow.changelogFile} pending section.`,
+          );
+        } else {
+          await runChangelogStep(workflow, answerBucket!, nextCommitObject);
+        }
         break;
       case "commit":
         assertAnalysisComplete(answerBucket, nextCommitObject);
-        await runCommitStep(smartshellInstance, answerBucket!);
+        await runCommitStep(smartshellInstance, answerBucket!, manual?.message);
         break;
       case "push":
         await runPushStep(smartshellInstance, workflow);
@@ -97,7 +156,9 @@ export const run = async (argvArg: any) => {
     }
   }
 
-  const commitShaResult = await smartshellInstance.exec("git rev-parse --short HEAD");
+  const commitShaResult = await smartshellInstance.exec(
+    "git rev-parse --short HEAD",
+  );
   const currentBranch = await detectCurrentBranch(smartshellInstance);
   ui.printSummary({
     projectType: "source",
@@ -110,6 +171,46 @@ export const run = async (argvArg: any) => {
   });
 };
 
+async function hasManualCommitChanges(
+  smartshellInstance: plugins.smartshell.Smartshell,
+): Promise<boolean> {
+  const status = await smartshellInstance.execSpawn(
+    "git",
+    ["status", "--porcelain=v1", "--untracked-files=all"],
+    { cwd: paths.cwd, silent: true },
+  );
+  if (status.exitCode !== 0)
+    throw new Error("Cannot inspect the repository for a manual commit.");
+  if (status.stdout.trim()) return true;
+  logger.log("info", "No uncommitted changes found. Nothing to commit.");
+  return false;
+}
+
+async function confirmManualCommit(
+  manual: IManualCommitInput,
+  workflow: IResolvedCommitWorkflow,
+  mode: ICliMode,
+): Promise<boolean> {
+  if (
+    workflow.confirmation === "auto" &&
+    (!manual.breaking || workflow.allowBreaking)
+  )
+    return true;
+  if (!mode.interactive) {
+    throw new Error(
+      manual.breaking
+        ? "BREAKING CHANGE confirmation requires an interactive terminal. Use `-y --allow-breaking` to auto-accept it."
+        : "Commit confirmation requires an interactive terminal. Use `-y` or set commit.confirmation to `auto`.",
+    );
+  }
+  return plugins.smartinteract.SmartInteract.getCliConfirmation(
+    manual.breaking
+      ? "Create this breaking commit and changelog entry?"
+      : "Create this commit and changelog entry?",
+    false,
+  );
+}
+
 async function runFormatStep(): Promise<void> {
   ui.printHeader("Formatting project files");
   const formatMod = await import("../mod_format/index.js");
@@ -132,7 +233,8 @@ async function runCommandStep(
 
 async function runAnalyzeStep(): Promise<any> {
   ui.printHeader("Analyzing repository changes");
-  const aidoc = new plugins.tsdoc.AiDoc();
+  const tsdoc = await plugins.loadTsdoc();
+  const aidoc = new tsdoc.AiDoc();
   await aidoc.start();
   try {
     const nextCommitObject = await aidoc.buildNextCommitObject(paths.cwd);
@@ -140,7 +242,8 @@ async function runAnalyzeStep(): Promise<any> {
       recommendedNextVersion: nextCommitObject.recommendedNextVersion,
       recommendedNextVersionLevel: nextCommitObject.recommendedNextVersionLevel,
       recommendedNextVersionScope: nextCommitObject.recommendedNextVersionScope,
-      recommendedNextVersionMessage: nextCommitObject.recommendedNextVersionMessage,
+      recommendedNextVersionMessage:
+        nextCommitObject.recommendedNextVersionMessage,
     });
     return nextCommitObject;
   } finally {
@@ -154,8 +257,11 @@ async function buildAnswerBucket(
   mode: ICliMode,
   argvArg: any,
 ): Promise<plugins.smartinteract.AnswerBucket> {
-  const isBreakingChange = nextCommitObject.recommendedNextVersionLevel === "BREAKING CHANGE";
-  const canAutoAccept = workflow.confirmation === "auto" && (!isBreakingChange || workflow.allowBreaking);
+  const isBreakingChange =
+    nextCommitObject.recommendedNextVersionLevel === "BREAKING CHANGE";
+  const canAutoAccept =
+    workflow.confirmation === "auto" &&
+    (!isBreakingChange || workflow.allowBreaking);
 
   if (canAutoAccept) {
     logger.log(
@@ -171,15 +277,25 @@ async function buildAnswerBucket(
     });
   }
 
-  if (isBreakingChange && (workflow.confirmation === "auto" || argvArg.y || argvArg.yes)) {
-    logger.log("warn", "BREAKING CHANGE detected - manual confirmation required");
+  if (
+    isBreakingChange &&
+    (workflow.confirmation === "auto" || argvArg.y || argvArg.yes)
+  ) {
+    logger.log(
+      "warn",
+      "BREAKING CHANGE detected - manual confirmation required",
+    );
   }
 
   if (!mode.interactive) {
     if (isBreakingChange) {
-      throw new Error("BREAKING CHANGE confirmation requires an interactive terminal. Use `-y --allow-breaking` to auto-accept it.");
+      throw new Error(
+        "BREAKING CHANGE confirmation requires an interactive terminal. Use `-y --allow-breaking` to auto-accept it.",
+      );
     }
-    throw new Error("Commit confirmation requires an interactive terminal. Use `-y` or set commit.confirmation to `auto`.");
+    throw new Error(
+      "Commit confirmation requires an interactive terminal. Use `-y` or set commit.confirmation to `auto`.",
+    );
   }
 
   const commitInteract = new plugins.smartinteract.SmartInteract();
@@ -240,15 +356,39 @@ async function runChangelogStep(
 async function runCommitStep(
   smartshellInstance: plugins.smartshell.Smartshell,
   answerBucket: plugins.smartinteract.AnswerBucket,
+  manualMessage?: string,
 ): Promise<void> {
   ui.printHeader("Creating Semantic Commit");
-  const commitString = createCommitStringFromAnswerBucket(answerBucket);
+  const commitString =
+    manualMessage ?? createCommitStringFromAnswerBucket(answerBucket);
   ui.printCommitMessage(commitString);
-  await smartshellInstance.exec("git add -A");
-  const result = await smartshellInstance.exec(`git commit -m ${shellQuote(commitString)}`);
-  if (result.exitCode !== 0) {
-    logger.log("error", "git commit failed.");
-    process.exit(1);
+  let messageDirectory: string | undefined;
+  try {
+    let commitArgs = ["commit", "-m", commitString];
+    if (manualMessage !== undefined) {
+      messageDirectory = await plugins.fs.mkdtemp(
+        plugins.path.join(plugins.os.tmpdir(), "gitzone-commit-message-"),
+      );
+      const messagePath = plugins.path.join(messageDirectory, "message.txt");
+      await plugins.fs.writeFile(messagePath, `${commitString}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+      });
+      commitArgs = ["commit", "--cleanup=verbatim", "--file", messagePath];
+    }
+    const staged = await smartshellInstance.execSpawn("git", ["add", "-A"], {
+      cwd: paths.cwd,
+    });
+    if (staged.exitCode !== 0)
+      throw new Error("git add failed; no commit was attempted.");
+    const result = await smartshellInstance.execSpawn("git", commitArgs, {
+      cwd: paths.cwd,
+    });
+    if (result.exitCode !== 0) throw new Error("git commit failed.");
+  } finally {
+    if (messageDirectory)
+      await plugins.fs.rm(messageDirectory, { recursive: true, force: true });
   }
 }
 
@@ -270,7 +410,9 @@ async function runPushStep(
 async function detectCurrentBranch(
   smartshellInstance: plugins.smartshell.Smartshell,
 ): Promise<string> {
-  const branchResult = await smartshellInstance.exec("git branch --show-current");
+  const branchResult = await smartshellInstance.exec(
+    "git branch --show-current",
+  );
   return branchResult.stdout.trim() || "master";
 }
 
@@ -279,26 +421,35 @@ function assertAnalysisComplete(
   nextCommitObject: any,
 ): void {
   if (!answerBucket || !nextCommitObject) {
-    throw new Error("Commit workflow requires analyze before changelog and commit steps.");
+    throw new Error(
+      "Commit workflow requires analyze before changelog and commit steps.",
+    );
   }
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}
-
-function printCommitExecutionPlan(workflow: IResolvedCommitWorkflow): void {
+function printCommitExecutionPlan(
+  workflow: IResolvedCommitWorkflow,
+  manual?: IManualCommitInput,
+): void {
   console.log("");
   console.log("gitzone commit - resolved workflow");
   console.log(`confirmation: ${workflow.confirmation}`);
+  console.log(`input: ${manual ? "manual" : "ai"}`);
   console.log(`steps: ${workflow.steps.join(" -> ")}`);
-  console.log(`changelog: ${workflow.changelogFile}#${workflow.changelogSection}`);
+  console.log(
+    `changelog: ${workflow.changelogFile}#${workflow.changelogSection}`,
+  );
+  if (manual) {
+    ui.printCommitMessage(manual.message);
+    console.log(manual.changelog);
+  }
   console.log("");
 }
 
 async function handleRecommend(mode: ICliMode): Promise<void> {
   const recommendationBuilder = async () => {
-    const aidoc = new plugins.tsdoc.AiDoc();
+    const tsdoc = await plugins.loadTsdoc();
+    const aidoc = new tsdoc.AiDoc();
     await aidoc.start();
     try {
       return await aidoc.buildNextCommitObject(paths.cwd);
@@ -355,24 +506,66 @@ export function showHelp(mode?: ICliMode): void {
     printJson({
       command: "commit",
       usage: "gitzone commit [recommend] [options]",
-      description: "Analyzes changes and creates one semantic source commit.",
+      description:
+        "Creates one semantic source commit from AI recommendations or explicit manual input.",
       commands: [
         {
           name: "recommend",
-          description: "Generate a commit recommendation without mutating the repository",
+          description:
+            "Generate a commit recommendation without mutating the repository",
         },
       ],
       flags: [
-        { flag: "-y, --yes", description: "Auto-accept safe AI recommendations" },
-        { flag: "--allow-breaking", description: "Allow -y/--yes to accept BREAKING CHANGE recommendations" },
+        {
+          flag: "-m, --message <text>",
+          description: "Use a complete semantic commit message without AI",
+        },
+        {
+          flag: "--message-file <path>",
+          description: "Read the complete semantic message from a UTF-8 file",
+        },
+        {
+          flag: "--changelog <text>",
+          description:
+            "Use custom Pending entry text or Markdown with a manual message",
+        },
+        {
+          flag: "--changelog-file <path>",
+          description: "Read custom Pending text or Markdown from a UTF-8 file",
+        },
+        {
+          flag: "-y, --yes",
+          description: "Confirm safe AI or manual commit input",
+        },
+        {
+          flag: "--allow-breaking",
+          description: "Allow -y/--yes to accept breaking AI or manual input",
+        },
         { flag: "-p, --push", description: "Push to origin after committing" },
-        { flag: "-t, --test", description: "Run tests as part of the commit workflow" },
-        { flag: "-b, --build", description: "Run build as part of the commit workflow" },
-        { flag: "-f, --format", description: "Run gitzone format before committing" },
-        { flag: "--plan", description: "Show resolved workflow without mutating files" },
-        { flag: "--json", description: "Emit JSON for `commit recommend` only" },
+        {
+          flag: "-t, --test",
+          description: "Run tests as part of the commit workflow",
+        },
+        {
+          flag: "-b, --build",
+          description: "Run build as part of the commit workflow",
+        },
+        {
+          flag: "-f, --format",
+          description: "Run gitzone format before committing",
+        },
+        {
+          flag: "--plan",
+          description: "Show resolved workflow without mutating files",
+        },
+        {
+          flag: "--json",
+          description: "Emit JSON for `commit recommend` only",
+        },
       ],
       examples: [
+        "gitzone commit -y --message 'fix(cache): expire stale entries'",
+        "gitzone commit -y --message-file /tmp/commit.txt --changelog-file /tmp/pending.md",
         "gitzone commit recommend --json",
         "gitzone commit -y",
         "gitzone commit -ytbp",
@@ -385,22 +578,48 @@ export function showHelp(mode?: ICliMode): void {
   console.log("");
   console.log("Usage: gitzone commit [recommend] [options]");
   console.log("");
-  console.log("Creates one semantic source commit. It does not version, tag, or publish.");
+  console.log(
+    "Creates one semantic source commit. It does not version, tag, or publish.",
+  );
   console.log("");
   console.log("Commands:");
-  console.log("  recommend           Generate a commit recommendation without mutating the repository");
+  console.log(
+    "  recommend           Generate a commit recommendation without mutating the repository",
+  );
   console.log("");
   console.log("Flags:");
-  console.log("  -y, --yes           Auto-accept safe AI recommendations");
-  console.log("  --allow-breaking    Allow -y/--yes to accept BREAKING CHANGE recommendations");
+  console.log(
+    "  -m, --message TEXT  Use a complete semantic message without AI",
+  );
+  console.log(
+    "  --message-file PATH Read the complete message from a UTF-8 file",
+  );
+  console.log(
+    "  --changelog TEXT    Custom Pending entry text or Markdown (requires a manual message)",
+  );
+  console.log(
+    "  --changelog-file PATH Read custom Pending text or Markdown from a UTF-8 file",
+  );
+  console.log("  -y, --yes           Confirm safe AI or manual commit input");
+  console.log(
+    "  --allow-breaking    Allow -y/--yes to accept breaking AI or manual input",
+  );
   console.log("  -p, --push          Push after commit");
   console.log("  -t, --test          Run tests in the configured order");
   console.log("  -b, --build         Run build in the configured order");
   console.log("  -f, --format        Run gitzone format before committing");
-  console.log("  --plan              Show resolved workflow without mutating files");
+  console.log(
+    "  --plan              Show resolved workflow without mutating files",
+  );
   console.log("  --json              Emit JSON for `commit recommend` only");
   console.log("");
   console.log("Examples:");
+  console.log(
+    "  gitzone commit -y --message 'fix(cache): expire stale entries'",
+  );
+  console.log(
+    "  gitzone commit -y --message-file /tmp/commit.txt --changelog-file /tmp/pending.md",
+  );
   console.log("  gitzone commit recommend --json");
   console.log("  gitzone commit -y");
   console.log("  gitzone commit -ytbp");

package/ts/mod_commit/mod.plugins.ts

@@ -1,10 +1,11 @@
-export * from '../plugins.js';
+export * from "../plugins.js";
 
-import * as commitinfo from '@push.rocks/commitinfo';
-import * as smartfile from '@push.rocks/smartfile';
-import * as smartinteract from '@push.rocks/smartinteract';
-import * as smartshell from '@push.rocks/smartshell';
+import * as commitinfo from "@push.rocks/commitinfo";
+import * as smartfile from "@push.rocks/smartfile";
+import * as smartinteract from "@push.rocks/smartinteract";
+import * as smartshell from "@push.rocks/smartshell";
 
-import * as tsdoc from '@git.zone/tsdoc';
+// Manual commits must not load or initialize the AI dependency chain.
+export const loadTsdoc = () => import("@git.zone/tsdoc");
 
-export { commitinfo, smartfile, smartinteract, smartshell, tsdoc };
+export { commitinfo, smartfile, smartinteract, smartshell };

package/ts/mod_standard/index.ts

@@ -17,7 +17,7 @@ const commandSummaries: ICommandHelpSummary[] = [
   {
     name: "commit",
     description:
-      "Analyze changes and create semantic source commits",
+      "Create semantic source commits from AI or manual input",
   },
   { name: "release", description: "Create versioned releases from pending changelog entries" },
   { name: "format", description: "Plan or apply project formatting changes" },