@beignet/cli 0.0.50 → 0.0.52

package/src/git-changes.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Stats } from "node:fs";
 import { createReadStream } from "node:fs";
-import { lstat, readlink } from "node:fs/promises";
+import { lstat, readlink, realpath } from "node:fs/promises";
 import path from "node:path";
 import { spawnCommand } from "./db.js";
 
@@ -58,17 +58,35 @@ export type GitChangeSet = {
   files: GitChangedFile[];
 };
 
+/** One reproducible snapshot of the repository state around an app check. */
+export type GitSourceSnapshot =
+  | {
+      kind: "git";
+      repositoryRoot: string;
+      comparison: GitChangeComparison;
+      repositoryChangeHash: string;
+    }
+  | {
+      kind: "unavailable";
+      reason: "not-a-git-worktree";
+    };
+
 export async function readGitChangeSet(options: {
   cwd: string;
   base?: string;
+  signal?: AbortSignal;
 }): Promise<GitChangeSet> {
   if (options.base !== undefined && options.base.length === 0) {
     throw new Error("Git base must not be empty.");
   }
   const repositoryRoot = path.resolve(
-    await gitText(options.cwd, ["rev-parse", "--show-toplevel"]),
+    await gitText(
+      options.cwd,
+      ["rev-parse", "--show-toplevel"],
+      options.signal,
+    ),
   );
-  const head = await resolveHeadCommit(repositoryRoot);
+  const head = await resolveHeadCommit(repositoryRoot, options.signal);
 
   let comparison: GitChangeComparison;
   let comparisonCommit: string;
@@ -78,21 +96,22 @@ export async function readGitChangeSet(options: {
         `Cannot compare --base ${JSON.stringify(options.base)} because this repository does not have a HEAD commit.`,
       );
     }
-    const baseCommit = await gitText(repositoryRoot, [
-      "rev-parse",
-      "--verify",
-      "--end-of-options",
-      `${options.base}^{commit}`,
-    ]).catch(() => {
+    const baseCommit = await gitText(
+      repositoryRoot,
+      ["rev-parse", "--verify", "--end-of-options", `${options.base}^{commit}`],
+      options.signal,
+    ).catch(() => {
+      options.signal?.throwIfAborted();
       throw new Error(
         `Could not resolve local Git base ${JSON.stringify(options.base)}. Fetch it before running Beignet; changed mapping never accesses the network.`,
       );
     });
-    const mergeBase = await gitText(repositoryRoot, [
-      "merge-base",
-      baseCommit,
-      head,
-    ]).catch(() => {
+    const mergeBase = await gitText(
+      repositoryRoot,
+      ["merge-base", baseCommit, head],
+      options.signal,
+    ).catch(() => {
+      options.signal?.throwIfAborted();
       throw new Error(
         `Could not find a merge base between ${JSON.stringify(options.base)} and HEAD.`,
       );
@@ -106,7 +125,8 @@ export async function readGitChangeSet(options: {
       head,
     };
   } else {
-    comparisonCommit = head ?? (await emptyTreeObjectId(repositoryRoot));
+    comparisonCommit =
+      head ?? (await emptyTreeObjectId(repositoryRoot, options.signal));
     comparison = {
       mode: "worktree",
       comparisonCommit,
@@ -116,22 +136,23 @@ export async function readGitChangeSet(options: {
 
   const committed =
     comparison.mode === "base"
-      ? await gitDiffOutput(repositoryRoot, [
-          comparison.mergeBase,
-          comparison.head,
-        ])
+      ? await gitDiffOutput(
+          repositoryRoot,
+          [comparison.mergeBase, comparison.head],
+          options.signal,
+        )
       : "";
-  const staged = await gitDiffOutput(repositoryRoot, [
-    "--cached",
-    head ?? comparisonCommit,
-  ]);
-  const unstaged = await gitDiffOutput(repositoryRoot, []);
-  const untracked = await gitOutput(repositoryRoot, [
-    "ls-files",
-    "--others",
-    "--exclude-standard",
-    "-z",
-  ]);
+  const staged = await gitDiffOutput(
+    repositoryRoot,
+    ["--cached", head ?? comparisonCommit],
+    options.signal,
+  );
+  const unstaged = await gitDiffOutput(repositoryRoot, [], options.signal);
+  const untracked = await gitOutput(
+    repositoryRoot,
+    ["ls-files", "--others", "--exclude-standard", "-z"],
+    options.signal,
+  );
   const files = mergeChangedFiles(
     parseNameStatus(committed),
     parseNameStatus(staged),
@@ -142,12 +163,43 @@ export async function readGitChangeSet(options: {
   return { repositoryRoot, comparison, files };
 }
 
-async function emptyTreeObjectId(repositoryRoot: string): Promise<string> {
+/** Capture Git-backed source state, or report that no worktree is available. */
+export async function readGitSourceSnapshot(options: {
+  cwd: string;
+  signal?: AbortSignal;
+}): Promise<GitSourceSnapshot> {
+  try {
+    const changeSet = await readGitChangeSet(options);
+    const repositoryChangeHash = await hashGitChanges(
+      changeSet,
+      changeSet.files,
+      options.signal,
+    );
+    options.signal?.throwIfAborted();
+    return {
+      kind: "git",
+      repositoryRoot: changeSet.repositoryRoot,
+      comparison: changeSet.comparison,
+      repositoryChangeHash,
+    };
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    if (await hasGitMetadata(options.cwd, options.signal)) throw error;
+    options.signal?.throwIfAborted();
+    return { kind: "unavailable", reason: "not-a-git-worktree" };
+  }
+}
+
+async function emptyTreeObjectId(
+  repositoryRoot: string,
+  signal?: AbortSignal,
+): Promise<string> {
   const objectFormat =
-    (await tryGitText(repositoryRoot, [
-      "rev-parse",
-      "--show-object-format=storage",
-    ])) ?? "sha1";
+    (await tryGitText(
+      repositoryRoot,
+      ["rev-parse", "--show-object-format=storage"],
+      signal,
+    )) ?? "sha1";
   const objectId =
     emptyTreeObjectIds[objectFormat as keyof typeof emptyTreeObjectIds];
   if (!objectId) {
@@ -161,13 +213,18 @@ async function emptyTreeObjectId(repositoryRoot: string): Promise<string> {
 export async function hashGitChanges(
   changeSet: Pick<GitChangeSet, "comparison" | "files" | "repositoryRoot">,
   files = changeSet.files,
+  signal?: AbortSignal,
 ): Promise<string> {
   const hash = createHash("sha256");
-  const indexEntries = await readGitIndexEntries(changeSet.repositoryRoot);
+  const indexEntries = await readGitIndexEntries(
+    changeSet.repositoryRoot,
+    signal,
+  );
   hash.update(JSON.stringify(changeSet.comparison));
   hash.update("\0");
 
   for (const file of [...files].sort(compareChangedFiles)) {
+    signal?.throwIfAborted();
     hash.update(
       JSON.stringify({
         status: file.status,
@@ -181,7 +238,12 @@ export async function hashGitChanges(
       hash.update("\0index\0");
       hash.update(indexEntries.get(relativePath) ?? "missing");
       hash.update("\0worktree\0");
-      await hashCurrentPath(hash, changeSet.repositoryRoot, relativePath);
+      await hashCurrentPath(
+        hash,
+        changeSet.repositoryRoot,
+        relativePath,
+        signal,
+      );
       hash.update("\0");
     }
   }
@@ -191,8 +253,13 @@ export async function hashGitChanges(
 
 async function readGitIndexEntries(
   repositoryRoot: string,
+  signal?: AbortSignal,
 ): Promise<Map<string, string>> {
-  const output = await gitOutput(repositoryRoot, ["ls-files", "--stage", "-z"]);
+  const output = await gitOutput(
+    repositoryRoot,
+    ["ls-files", "--stage", "-z"],
+    signal,
+  );
   const entries = new Map<string, string[]>();
   for (const field of output.split("\0").filter(Boolean)) {
     const separator = field.indexOf("\t");
@@ -214,39 +281,44 @@ async function hashCurrentPath(
   hash: ReturnType<typeof createHash>,
   repositoryRoot: string,
   relativePath: string,
+  signal?: AbortSignal,
 ): Promise<void> {
+  signal?.throwIfAborted();
   const absolutePath = path.join(repositoryRoot, relativePath);
   let stats: Stats;
   try {
     stats = await lstat(absolutePath);
   } catch (error) {
+    signal?.throwIfAborted();
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       hash.update("missing");
       return;
     }
     throw error;
   }
+  signal?.throwIfAborted();
 
   if (stats.isSymbolicLink()) {
+    const target = await readlink(absolutePath);
+    signal?.throwIfAborted();
     hash.update("symlink\0");
     hash.update(String(stats.mode));
     hash.update("\0");
-    hash.update(await readlink(absolutePath));
+    hash.update(target);
     return;
   }
   if (stats.isDirectory()) {
     hash.update("directory\0");
-    const head = await tryGitText(absolutePath, [
-      "rev-parse",
-      "--verify",
-      "HEAD^{commit}",
-    ]);
-    const status = await tryGitOutput(absolutePath, [
-      "status",
-      "--porcelain=v1",
-      "-z",
-      "--untracked-files=all",
-    ]);
+    const head = await tryGitText(
+      absolutePath,
+      ["rev-parse", "--verify", "HEAD^{commit}"],
+      signal,
+    );
+    const status = await tryGitOutput(
+      absolutePath,
+      ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+      signal,
+    );
     hash.update(head ?? "unknown-head");
     hash.update("\0");
     hash.update(status ?? "unknown-status");
@@ -260,8 +332,47 @@ async function hashCurrentPath(
   hash.update("file\0");
   hash.update(String(stats.mode));
   hash.update("\0");
-  for await (const chunk of createReadStream(absolutePath)) {
-    hash.update(chunk as Buffer);
+  try {
+    for await (const chunk of createReadStream(absolutePath, { signal })) {
+      hash.update(chunk as Buffer);
+    }
+  } catch (error) {
+    signal?.throwIfAborted();
+    throw error;
+  }
+  signal?.throwIfAborted();
+}
+
+async function hasGitMetadata(
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  signal?.throwIfAborted();
+  if (process.env.GIT_DIR || process.env.GIT_WORK_TREE) return true;
+  let root = path.resolve(cwd);
+  try {
+    root = await realpath(root);
+  } catch (error) {
+    signal?.throwIfAborted();
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+  }
+
+  let current = root;
+  while (true) {
+    signal?.throwIfAborted();
+    try {
+      await lstat(path.join(current, ".git"));
+      signal?.throwIfAborted();
+      return true;
+    } catch (error) {
+      signal?.throwIfAborted();
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
   }
 }
 
@@ -397,36 +508,45 @@ function normalizeGitPath(file: string): string {
   return process.platform === "win32" ? file.replaceAll("\\", "/") : file;
 }
 
-async function gitText(cwd: string, args: readonly string[]): Promise<string> {
-  return (await gitOutput(cwd, args)).trim();
+async function gitText(
+  cwd: string,
+  args: readonly string[],
+  signal?: AbortSignal,
+): Promise<string> {
+  return stripFinalLineEnding(await gitOutput(cwd, args, signal));
+}
+
+function stripFinalLineEnding(output: string): string {
+  if (output.endsWith("\n")) return output.slice(0, -1);
+  return output;
 }
 
 async function resolveHeadCommit(
   repositoryRoot: string,
+  signal?: AbortSignal,
 ): Promise<string | undefined> {
-  const head = await runGit(repositoryRoot, [
-    "rev-parse",
-    "--verify",
-    "HEAD^{commit}",
-  ]);
+  const head = await runGit(
+    repositoryRoot,
+    ["rev-parse", "--verify", "HEAD^{commit}"],
+    signal,
+  );
   if (head.exitCode === 0) return head.stdout.trim();
 
-  const symbolicHead = await runGit(repositoryRoot, [
-    "symbolic-ref",
-    "--quiet",
-    "HEAD",
-  ]);
+  const symbolicHead = await runGit(
+    repositoryRoot,
+    ["symbolic-ref", "--quiet", "HEAD"],
+    signal,
+  );
   if (symbolicHead.exitCode !== 0) {
     throw gitCommandError(["rev-parse", "--verify", "HEAD^{commit}"], head);
   }
 
   const ref = symbolicHead.stdout.trim();
-  const refExists = await runGit(repositoryRoot, [
-    "show-ref",
-    "--verify",
-    "--quiet",
-    ref,
-  ]);
+  const refExists = await runGit(
+    repositoryRoot,
+    ["show-ref", "--verify", "--quiet", ref],
+    signal,
+  );
   if (refExists.exitCode === 1) return undefined;
   throw gitCommandError(["rev-parse", "--verify", "HEAD^{commit}"], head);
 }
@@ -434,10 +554,12 @@ async function resolveHeadCommit(
 async function tryGitText(
   cwd: string,
   args: readonly string[],
+  signal?: AbortSignal,
 ): Promise<string | undefined> {
   try {
-    return await gitText(cwd, args);
+    return await gitText(cwd, args, signal);
   } catch {
+    signal?.throwIfAborted();
     return undefined;
   }
 }
@@ -445,10 +567,12 @@ async function tryGitText(
 async function tryGitOutput(
   cwd: string,
   args: readonly string[],
+  signal?: AbortSignal,
 ): Promise<string | undefined> {
   try {
-    return await gitOutput(cwd, args);
+    return await gitOutput(cwd, args, signal);
   } catch {
+    signal?.throwIfAborted();
     return undefined;
   }
 }
@@ -456,8 +580,9 @@ async function tryGitOutput(
 async function gitOutput(
   cwd: string,
   args: readonly string[],
+  signal?: AbortSignal,
 ): Promise<string> {
-  const result = await runGit(cwd, args);
+  const result = await runGit(cwd, args, signal);
   if (result.exitCode !== 0) throw gitCommandError(args, result);
   return result.stdout;
 }
@@ -465,14 +590,16 @@ async function gitOutput(
 async function runGit(
   cwd: string,
   args: readonly string[],
+  signal?: AbortSignal,
 ): Promise<GitCommandResult> {
   const result = await spawnCommand("git", args, cwd, {
     captureOutput: true,
     maxOutputBytes: maxGitOutputBytes,
+    signal,
   });
   if (result.outputTruncated) {
     throw new Error(
-      `Git output exceeded ${maxGitOutputBytes} bytes; changed mapping cannot produce a complete report.`,
+      `Git output exceeded ${maxGitOutputBytes} bytes; source inspection cannot produce a complete report.`,
     );
   }
   return {
@@ -495,17 +622,22 @@ function gitCommandError(
 async function gitDiffOutput(
   repositoryRoot: string,
   comparisonArgs: readonly string[],
+  signal?: AbortSignal,
 ): Promise<string> {
-  return gitOutput(repositoryRoot, [
-    "diff",
-    "--no-ext-diff",
-    "--no-textconv",
-    "--name-status",
-    "-z",
-    "--find-renames=50%",
-    "--find-copies=50%",
-    "--find-copies-harder",
-    ...comparisonArgs,
-    "--",
-  ]);
+  return gitOutput(
+    repositoryRoot,
+    [
+      "diff",
+      "--no-ext-diff",
+      "--no-textconv",
+      "--name-status",
+      "-z",
+      "--find-renames=50%",
+      "--find-copies=50%",
+      "--find-copies-harder",
+      ...comparisonArgs,
+      "--",
+    ],
+    signal,
+  );
 }

package/src/index.ts

@@ -8,6 +8,7 @@ import {
   type CommandContext,
   type FlagParametersForType,
   proposeCompletions,
+  type RouteMap,
   run,
   type StricliDynamicCommandContext,
   type StricliProcess,
@@ -180,6 +181,7 @@ type OutboxDrainFlags = {
   json?: boolean;
   module?: string;
   batchSize?: number;
+  concurrency?: number;
   cwd?: string;
 };
 
@@ -486,7 +488,13 @@ const outboxDrainFlagParameters = {
     kind: "parsed",
     parse: parsePositiveInteger,
     optional: true,
-    brief: "Maximum messages to claim in one drain pass.",
+    brief: "Maximum eligible messages to handle in one drain pass.",
+  },
+  concurrency: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "Maximum concurrent deliveries; values above one are unordered.",
   },
   cwd: cwdFlag,
 } satisfies FlagParametersForType<OutboxDrainFlags, CliContext>;
@@ -1156,7 +1164,7 @@ const checkCommand = buildCommand<CheckFlags, [], CliContext>({
   docs: {
     brief: "Run the full app validation loop as one command.",
     fullDescription:
-      "Runs beignet lint, beignet doctor --strict, optional disconnected or connected preflight, and the app's lint, typecheck, and test package scripts through the detected package manager. Every step runs even when an earlier one fails, so one run reports everything. Missing package scripts are skipped, not failed.",
+      "Runs beignet lint, beignet doctor --strict, optional disconnected or connected preflight, and the app's lint, typecheck, and test package scripts through the detected package manager. Every step runs even when an earlier one fails, so one run reports everything. Missing package scripts are skipped, not failed. Inside Git, the command fingerprints source before and after validation and fails stale results whose ending fingerprint differs from the baseline.",
   },
   parameters: {
     flags: {
@@ -1186,9 +1194,12 @@ const checkCommand = buildCommand<CheckFlags, [], CliContext>({
     } satisfies FlagParametersForType<CheckFlags, CliContext>,
   },
   loader: async () => {
-    const { checkApp, formatCheckStep, formatCheckSummary } = await import(
-      "./check.js"
-    );
+    const {
+      checkApp,
+      formatCheckProvenance,
+      formatCheckStep,
+      formatCheckSummary,
+    } = await import("./check.js");
 
     return async function runCheck(this: CliContext, flags: CheckFlags) {
       const color = useColor();
@@ -1210,7 +1221,7 @@ const checkCommand = buildCommand<CheckFlags, [], CliContext>({
         this,
         flags.json
           ? JSON.stringify(result, null, 2)
-          : `\n${formatCheckSummary(result, { color })}`,
+          : `\n${formatCheckProvenance(result, { color })}\n${formatCheckSummary(result, { color })}`,
       );
       if (!result.ok) {
         this.process.exitCode = 1;
@@ -1597,6 +1608,7 @@ const outboxDrainCommand = buildCommand<OutboxDrainFlags, [], CliContext>({
         cwd: flags.cwd,
         modulePath: flags.module,
         batchSize: flags.batchSize,
+        concurrency: flags.concurrency,
       });
 
       writeOutput(
@@ -1605,6 +1617,9 @@ const outboxDrainCommand = buildCommand<OutboxDrainFlags, [], CliContext>({
           ? JSON.stringify(result, null, 2)
           : outboxDrainNextSteps(result),
       );
+      if (result.result.settlementFailed > 0 || result.result.leaseLost > 0) {
+        this.process.exitCode = 1;
+      }
     };
   },
 });
@@ -2448,6 +2463,27 @@ Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
   },
 });
 
+const completionProposalCommandPath = ["completion", "propose"] as const;
+
+function commandPathsFromRouteMap(
+  routeMap: RouteMap<CliContext>,
+  prefix: readonly string[] = [],
+): string[][] {
+  return routeMap.getAllEntries().flatMap((entry) => {
+    const path = [...prefix, entry.name["convert-camel-to-kebab"]];
+    if ("getAllEntries" in entry.target) {
+      return commandPathsFromRouteMap(entry.target, path);
+    }
+    return [path];
+  });
+}
+
+/** Every canonical CLI command path, derived from runtime routing definitions. */
+export const cliCommandPaths: readonly (readonly string[])[] = [
+  ...commandPathsFromRouteMap(rootRoutes),
+  completionProposalCommandPath,
+].sort((left, right) => left.join(" ").localeCompare(right.join(" ")));
+
 const cli = buildApplication(rootRoutes, {
   name: "beignet",
   versionInfo: {
@@ -2541,6 +2577,9 @@ type OutboxDrainNextStepsResult = {
     delivered: number;
     retried: number;
     deadLettered: number;
+    abandonedDeadLettered: number;
+    settlementFailed: number;
+    leaseLost: number;
   };
 };
 
@@ -2608,7 +2647,10 @@ Result:
   claimed: ${result.result.claimed}
   delivered: ${result.result.delivered}
   retried: ${result.result.retried}
-  deadLettered: ${result.result.deadLettered}`;
+  deadLettered: ${result.result.deadLettered}
+  abandonedDeadLettered: ${result.result.abandonedDeadLettered}
+  settlementFailed: ${result.result.settlementFailed}
+  leaseLost: ${result.result.leaseLost}`;
 }
 
 function formatOutboxDate(value: Date | string | null | undefined): string {
@@ -3053,7 +3095,10 @@ export async function main(
   // Shell completion scripts call `beignet completion propose <words...>`.
   // Handle it before stricli parses the inputs: the trailing words are a
   // partial command line, not flags for this CLI.
-  if (inputs[0] === "completion" && inputs[1] === "propose") {
+  if (
+    inputs[0] === completionProposalCommandPath[0] &&
+    inputs[1] === completionProposalCommandPath[1]
+  ) {
     await writeCompletionProposals(inputs.slice(2), context);
     return;
   }