@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/deliver-work/scripts/commit-state.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// What a commit would hold, and whose it is, before touching the index: every staged, unstaged and untracked path,
+// marked yours, pre-existing or unknown; staged changes that were already staged before your work (never absorb or
+// unstage them); files with both staged and unstaged changes; sensitive-looking paths and Working Records; and what
+// `git diff --cached --check` finds. Read-only apart from its own snapshot file.
+// Usage: commit-state.mjs snapshot [--root <repository>] [--scratch <dir>]
+//        commit-state.mjs [--mine <path>]... [--root <repository>] [--scratch <dir>] [--json]
+// `snapshot`, taken before your first edit, records the dirty and staged state that is not yours. Without one, --mine
+// names the paths you changed; a path neither names is "unknown". --scratch defaults to a folder under the system
+// temporary directory. Exit code 0 when it reports, 2 on a usage error or outside a Git repository.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { git, repositoryRoot, workingState } from "./lib/git-state.mjs";
+
+const USAGE = [
+  "Usage: commit-state.mjs snapshot [--root <repository>] [--scratch <dir>]",
+  "       commit-state.mjs [--mine <path>]... [--root <repository>] [--scratch <dir>] [--json]",
+].join("\n");
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      root: { type: "string" },
+      scratch: { type: "string" },
+      mine: { type: "string", multiple: true, default: [] },
+      json: { type: "boolean", default: false },
+    },
+  });
+} catch (error) {
+  console.error(`${error.message}\n${USAGE}`);
+  process.exit(2);
+}
+const { values, positionals } = parsed;
+if (positionals.length > 1 || (positionals.length && positionals[0] !== "snapshot")) {
+  console.error(USAGE);
+  process.exit(2);
+}
+const root = repositoryRoot(values.root ?? ".");
+if (!root) {
+  console.error("not inside a Git repository");
+  process.exit(2);
+}
+const scratch = resolve(
+  values.scratch ??
+    join(
+      tmpdir(),
+      "freeflow-commit-state",
+      `${basename(root)}-${createHash("sha256").update(root).digest("hex").slice(0, 8)}`,
+    ),
+);
+const snapshotPath = join(scratch, "commit-state-snapshot.json");
+
+// A path's identity in the index and in the working tree, so a later change to either shows.
+const identity = (path) => ({
+  index: git(root, ["ls-files", "-s", "--", path])?.split(/\s+/)[1] ?? null,
+  tree: existsSync(join(root, path)) ? git(root, ["hash-object", "--", path]) : null,
+});
+const working = workingState(root);
+
+if (positionals[0] === "snapshot") {
+  mkdirSync(scratch, { recursive: true });
+  const paths = Object.fromEntries(working.entries.map((entry) => [entry.path, { ...entry, ...identity(entry.path) }]));
+  writeFileSync(
+    snapshotPath,
+    `${JSON.stringify({ root, head: git(root, ["rev-parse", "HEAD"]), at: new Date().toISOString(), paths }, null, 2)}\n`,
+  );
+  console.log(`Snapshot of ${working.entries.length} pre-existing changed path(s): ${snapshotPath}`);
+  process.exit(0);
+}
+
+const snapshot = existsSync(snapshotPath) ? JSON.parse(readFileSync(snapshotPath, "utf8")) : null;
+const mine = new Set(values.mine.map((path) => relative(root, resolve(path)).split("\\").join("/")));
+function owner(entry) {
+  if (snapshot) {
+    const before = snapshot.paths[entry.path];
+    if (!before) return "yours";
+    const now = identity(entry.path);
+    return now.index === before.index && now.tree === before.tree ? "pre-existing" : "mixed: pre-existing plus yours";
+  }
+  // A --mine path names a file, or a folder holding it.
+  if ([...mine].some((path) => entry.path === path || entry.path.startsWith(`${path}/`))) return "yours";
+  return "unknown";
+}
+const SENSITIVE =
+  /(^|\/)(\.env(\..*)?|\.npmrc|\.pypirc|id_(rsa|ed25519|ecdsa)(\.pub)?|.*\.(pem|key|p12|pfx|keystore)|credentials?(\.json)?|secrets?(\.[a-z]+)?|.*\.tfstate)$/i;
+const flags = (entry) => [
+  ...(/^\.freeflow\/(tasks\/.*)?$/.test(entry.path) ? ["Working Record: never stage"] : []),
+  ...(SENSITIVE.test(entry.path) ? ["sensitive-looking: inspect before staging"] : []),
+];
+const describe = (entry) => ({
+  path: entry.path,
+  ...(entry.from ? { from: entry.from } : {}),
+  index: entry.x,
+  tree: entry.y,
+  owner: owner(entry),
+  partial: entry.x !== " " && entry.x !== "?" && entry.y !== " " && entry.y !== "?",
+  flags: flags(entry),
+});
+const staged = working.staged.map(describe);
+const unstaged = working.unstaged.filter((entry) => entry.x === " ").map(describe);
+const untracked = working.untracked.map(describe);
+const conflicted = working.conflicted.map(describe);
+// Conflict markers and whitespace damage in what is staged; Git exits nonzero when it finds any.
+const cached = spawnSync("git", ["diff", "--cached", "--check"], { cwd: root, encoding: "utf8" });
+const check =
+  cached.status === 0 ? "clean" : (cached.stdout || cached.stderr).trim().split("\n").slice(0, 20).join("\n");
+const report = {
+  command: "commit-state",
+  root,
+  ownership: snapshot ? `snapshot of ${snapshot.at}` : mine.size ? "--mine paths" : "unknown: no snapshot or --mine",
+  staged,
+  stagedNotYours: staged.filter((each) => each.owner !== "yours").map((each) => each.path),
+  unstaged,
+  untracked,
+  conflicted,
+  cachedCheck: check,
+};
+
+if (values.json) console.log(JSON.stringify(report, null, 2));
+else {
+  const line = (each) =>
+    `  ${each.index}${each.tree} ${each.from ? `${each.from} -> ` : ""}${each.path}  [${each.owner}]${each.partial ? " (staged and unstaged changes)" : ""}${each.flags.length ? `  ! ${each.flags.join("; ")}` : ""}`;
+  const out = [`Ownership from: ${report.ownership}`];
+  out.push(`Staged (${staged.length}):`, ...(staged.length ? staged.map(line) : ["  none"]));
+  if (report.stagedNotYours.length)
+    out.push(
+      `  Not yours, or not known to be: ${report.stagedNotYours.join(", ")}. Do not absorb or unstage them; ask which commit the user wants.`,
+    );
+  out.push(`Unstaged only (${unstaged.length}):`, ...(unstaged.length ? unstaged.map(line) : ["  none"]));
+  out.push(`Untracked (${untracked.length}):`, ...(untracked.length ? untracked.map(line) : ["  none"]));
+  if (conflicted.length) out.push(`Conflicted (${conflicted.length}):`, ...conflicted.map(line));
+  out.push(`git diff --cached --check: ${check}`);
+  console.log(out.join("\n"));
+}

package/skills/deliver-work/scripts/delivery-state.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// The delivery state in one read-only call, before any commit, push, merge, cleanup or release: branch or detached
+// HEAD, upstream and ahead/behind from local refs, staged, unstaged, untracked and conflicted counts, a Git operation
+// left in progress, every worktree with the one holding this session's working directory flagged, the latest tag, the
+// declared version and the changelog's Unreleased section. Anything that needs the network is reported unavailable.
+// Usage: delivery-state.mjs [--root <repository>] [--cwd <session directory>] [--json]
+// --cwd defaults to the current directory. Exit code 0 when it reports, 2 outside a Git repository.
+import { parseArgs } from "node:util";
+import {
+  branchState,
+  changelog,
+  inProgress,
+  latestTag,
+  projectVersion,
+  repositoryRoot,
+  workingState,
+  worktrees,
+} from "./lib/git-state.mjs";
+
+const USAGE = "Usage: delivery-state.mjs [--root <repository>] [--cwd <session directory>] [--json]";
+let values;
+try {
+  ({ values } = parseArgs({
+    options: { root: { type: "string" }, cwd: { type: "string" }, json: { type: "boolean", default: false } },
+  }));
+} catch (error) {
+  console.error(`${error.message}\n${USAGE}`);
+  process.exit(2);
+}
+const cwd = values.cwd ?? process.cwd();
+const root = repositoryRoot(values.root ?? cwd);
+if (!root) {
+  console.error("not inside a Git repository");
+  process.exit(2);
+}
+
+const branch = branchState(root);
+const working = workingState(root);
+const operations = inProgress(root);
+const trees = worktrees(root, cwd);
+const tag = latestTag(root);
+const version = projectVersion(root);
+const notes = changelog(root);
+const state = {
+  command: "delivery-state",
+  root,
+  branch,
+  working: {
+    staged: working.staged.length,
+    unstaged: working.unstaged.length,
+    untracked: working.untracked.length,
+    conflicted: working.conflicted.length,
+  },
+  inProgress: operations,
+  worktrees: trees,
+  latestTag: tag,
+  version,
+  versionTagged:
+    version?.version && tag ? [tag.tag, `v${version.version}`].includes(tag.tag) || tag.tag === version.version : false,
+  changelog: notes,
+  unavailable: [
+    "the remote's current state: ahead/behind uses local remote-tracking refs (fetch to refresh them, when that is covered)",
+    "pull requests, CI results, registry versions and deployments",
+  ],
+};
+
+if (values.json) console.log(JSON.stringify(state, null, 2));
+else {
+  const out = [];
+  out.push(
+    branch.branch
+      ? `Branch: ${branch.branch}${branch.upstream ? `, upstream ${branch.upstream} (ahead ${branch.ahead}, behind ${branch.behind}, from local refs)` : ", no upstream"}`
+      : branch.detached
+        ? `Detached HEAD at ${branch.head.slice(0, 12)}`
+        : "No commits yet",
+  );
+  if (branch.head) out.push(`HEAD: ${branch.head.slice(0, 12)} ${branch.subject}`);
+  out.push(
+    `Working tree: ${state.working.staged} staged, ${state.working.unstaged} unstaged, ${state.working.untracked} untracked, ${state.working.conflicted} conflicted`,
+  );
+  out.push(`In progress: ${operations.length ? operations.join(", ") : "no Git operation"}`);
+  out.push(`Worktrees (${trees.length}):`);
+  for (const tree of trees)
+    out.push(
+      `  ${tree.path} ${tree.branch ?? (tree.detached ? "(detached)" : "")} ${tree.head ?? ""}${tree.sessionCwd ? "  <- this session's cwd is inside" : ""}${tree.locked ? " [locked]" : ""}${tree.prunable ? " [prunable]" : ""}`,
+    );
+  out.push(
+    `Latest tag: ${tag ? `${tag.tag} at ${tag.commit}, ${tag.commitsSince} commit(s) since` : "none"}; version: ${version ? `${version.version ?? "unreadable"} (${version.source})` : "none declared"}`,
+  );
+  if (notes)
+    out.push(
+      `Changelog ${notes.file}: ${
+        notes.unreleased
+          ? `Unreleased has ${notes.unreleased.entries} entr${notes.unreleased.entries === 1 ? "y" : "ies"}${
+              Object.keys(notes.unreleased.categories).length
+                ? ` (${Object.entries(notes.unreleased.categories)
+                    .map(([name, count]) => `${name} ${count}`)
+                    .join(", ")})`
+                : ""
+            }`
+          : "no Unreleased section"
+      }`,
+    );
+  else out.push("Changelog: none found");
+  out.push(`Unavailable without the network: ${state.unavailable.join("; ")}.`);
+  console.log(out.join("\n"));
+}

package/skills/deliver-work/scripts/lib/git-state.mjs

@@ -0,0 +1,178 @@
+// Read-only Git and project facts shared by Deliver Work's scripts. Nothing here fetches, writes or changes state:
+// remote facts come from local remote-tracking refs, which are only as fresh as the last fetch.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+export function run(cwd, command, args) {
+  try {
+    return execFileSync(command, args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 256 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+export const git = (cwd, args) => run(cwd, "git", args);
+
+export function repositoryRoot(start) {
+  const root = git(resolve(start), ["rev-parse", "--show-toplevel"]);
+  return root ? resolve(root) : null;
+}
+
+export function branchState(root) {
+  const branch = git(root, ["branch", "--show-current"]) || null;
+  const head = git(root, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+  const subject = head ? git(root, ["log", "-1", "--format=%s"]) : null;
+  const upstream = branch ? git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]) : null;
+  let ahead = null;
+  let behind = null;
+  if (upstream) {
+    const counts = git(root, ["rev-list", "--left-right", "--count", `${upstream}...HEAD`]);
+    if (counts) [behind, ahead] = counts.split(/\s+/).map(Number);
+  }
+  return { branch, detached: !branch && Boolean(head), head, subject, upstream, ahead, behind };
+}
+
+// Porcelain v1 status: staged and unstaged paths, untracked files and conflicts.
+export function workingState(root) {
+  const lines = (git(root, ["-c", "core.quotePath=false", "status", "--porcelain=v1", "-z"]) ?? "")
+    .split("\0")
+    .filter(Boolean);
+  const entries = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const x = line[0];
+    const y = line[1];
+    const path = line.slice(3);
+    const entry = { x, y, path };
+    if (x === "R" || x === "C") entry.from = lines[(index += 1)];
+    entries.push(entry);
+  }
+  const conflict = (entry) =>
+    entry.x === "U" || entry.y === "U" || (entry.x === "A" && entry.y === "A") || (entry.x === "D" && entry.y === "D");
+  return {
+    entries,
+    staged: entries.filter((entry) => entry.x !== " " && entry.x !== "?" && !conflict(entry)),
+    unstaged: entries.filter((entry) => entry.y !== " " && entry.y !== "?" && !conflict(entry)),
+    untracked: entries.filter((entry) => entry.x === "?"),
+    conflicted: entries.filter(conflict),
+  };
+}
+
+// A merge, rebase, cherry-pick, revert, bisect or patch application left in progress.
+export function inProgress(root) {
+  const gitDir = git(root, ["rev-parse", "--absolute-git-dir"]);
+  if (!gitDir) return [];
+  const markers = [
+    ["MERGE_HEAD", "merge"],
+    ["rebase-merge", "rebase"],
+    ["rebase-apply/applying", "am (patch application)"],
+    ["rebase-apply", "rebase"],
+    ["CHERRY_PICK_HEAD", "cherry-pick"],
+    ["REVERT_HEAD", "revert"],
+    ["BISECT_LOG", "bisect"],
+  ];
+  const found = [];
+  for (const [marker, operation] of markers)
+    if (existsSync(join(gitDir, marker)) && !found.includes(operation)) found.push(operation);
+  if (found.includes("am (patch application)")) return found.filter((each) => each !== "rebase");
+  return found;
+}
+
+// Worktrees, flagging the one holding the given directory (the session's working directory).
+export function worktrees(root, cwd) {
+  const text = git(root, ["worktree", "list", "--porcelain"]) ?? "";
+  const here = resolve(cwd);
+  return text
+    .split("\n\n")
+    .filter(Boolean)
+    .map((block) => {
+      const fields = Object.fromEntries(
+        block.split("\n").map((line) => {
+          const space = line.indexOf(" ");
+          return space === -1 ? [line, true] : [line.slice(0, space), line.slice(space + 1)];
+        }),
+      );
+      const path = resolve(fields.worktree);
+      const inside = here === path || here.startsWith(`${path}${sep}`);
+      return {
+        path,
+        branch: typeof fields.branch === "string" ? fields.branch.replace(/^refs\/heads\//, "") : null,
+        head: typeof fields.HEAD === "string" ? fields.HEAD.slice(0, 12) : null,
+        detached: fields.detached === true,
+        locked: fields.locked !== undefined,
+        prunable: fields.prunable !== undefined,
+        sessionCwd: inside,
+      };
+    })
+    .map((tree, _, all) => {
+      // The innermost worktree holding the cwd is the session's; an outer one only contains it on disk.
+      const holders = all.filter((each) => each.sessionCwd);
+      const innermost = holders.sort((a, b) => b.path.length - a.path.length)[0];
+      return { ...tree, sessionCwd: innermost ? innermost.path === tree.path : false };
+    });
+}
+
+export function latestTag(root) {
+  const tag = git(root, ["describe", "--tags", "--abbrev=0"]);
+  if (!tag) return null;
+  const at = git(root, ["rev-list", "-n", "1", tag]);
+  const since = git(root, ["rev-list", "--count", `${tag}..HEAD`]);
+  return { tag, commit: at?.slice(0, 12) ?? null, commitsSince: since === null ? null : Number(since) };
+}
+
+// The project's declared version: package.json, then pyproject.toml, then Cargo.toml.
+export function projectVersion(root) {
+  const packagePath = join(root, "package.json");
+  if (existsSync(packagePath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(packagePath, "utf8"));
+      if (parsed.version) return { version: parsed.version, source: "package.json", name: parsed.name ?? null };
+    } catch {
+      return { version: null, source: "package.json (not valid JSON)", name: null };
+    }
+  }
+  for (const file of ["pyproject.toml", "Cargo.toml"]) {
+    const path = join(root, file);
+    if (!existsSync(path)) continue;
+    const match = /^\s*version\s*=\s*["']([^"']+)["']/m.exec(readFileSync(path, "utf8"));
+    if (match) return { version: match[1], source: file, name: null };
+  }
+  return null;
+}
+
+// The changelog's Unreleased section: its categories and how many entries each holds.
+export function changelog(root) {
+  const file = ["CHANGELOG.md", "CHANGES.md", "HISTORY.md"].find((name) => existsSync(join(root, name)));
+  if (!file) return null;
+  const lines = readFileSync(join(root, file), "utf8").split("\n");
+  const start = lines.findIndex((line) => /^##\s+\[?unreleased\]?/i.test(line));
+  const versions = lines
+    .filter((line) => /^##\s+\[?v?\d+\.\d+/.test(line))
+    .map((line) => /^##\s+\[?v?(\d+\.\d+[^\]\s]*)/.exec(line)[1]);
+  if (start === -1) return { file, unreleased: null, versions };
+  const end = lines.findIndex((line, index) => index > start && /^##\s/.test(line));
+  const section = lines.slice(start + 1, end === -1 ? undefined : end);
+  const categories = {};
+  let category = "(none)";
+  let entries = 0;
+  for (const line of section) {
+    const heading = /^###\s+(.*)$/.exec(line);
+    if (heading) category = heading[1].trim();
+    else if (/^\s*[-*]\s+\S/.test(line) && !/^\s{2,}/.test(line)) {
+      categories[category] = (categories[category] ?? 0) + 1;
+      entries += 1;
+    }
+  }
+  return { file, unreleased: { entries, categories }, versions };
+}
+
+export const show = (root, path) => {
+  const relativePath = relative(root, path);
+  return relativePath.startsWith("..") ? path : relativePath || ".";
+};

package/skills/deliver-work/scripts/push-route.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// The route for a simple push (references/branch-closeout.md, Simple Push): the current branch, its upstream or the remote it would go to, the
+// commits it would send from local refs, and the stop conditions the local state shows. It prints the push command it
+// would use and never runs it.
+// Usage: push-route.mjs [--remote <name>] [--root <repository>] [--json]
+// Exit code 0 when a simple push is possible from what it can see, 1 when a stop condition holds, 2 on a usage error
+// or outside a Git repository.
+import { parseArgs } from "node:util";
+import { branchState, git, inProgress, repositoryRoot, workingState } from "./lib/git-state.mjs";
+
+const USAGE = "Usage: push-route.mjs [--remote <name>] [--root <repository>] [--json]";
+let values;
+try {
+  ({ values } = parseArgs({
+    options: { remote: { type: "string" }, root: { type: "string" }, json: { type: "boolean", default: false } },
+  }));
+} catch (error) {
+  console.error(`${error.message}\n${USAGE}`);
+  process.exit(2);
+}
+const root = repositoryRoot(values.root ?? ".");
+if (!root) {
+  console.error("not inside a Git repository");
+  process.exit(2);
+}
+
+const branch = branchState(root);
+const remotes = (git(root, ["remote"]) ?? "").split("\n").filter(Boolean);
+const urls = Object.fromEntries(remotes.map((name) => [name, git(root, ["remote", "get-url", "--push", name])]));
+const stops = [];
+const notes = [];
+let remote = values.remote ?? null;
+let destination = null;
+let command = null;
+
+if (!branch.head) stops.push("no commits to push");
+if (branch.detached) stops.push("HEAD is detached: push a named branch");
+for (const operation of inProgress(root)) stops.push(`a ${operation} is in progress`);
+if (values.remote && !remotes.includes(values.remote)) stops.push(`no remote named ${values.remote}`);
+
+if (branch.branch && branch.upstream) {
+  const [upstreamRemote, ...rest] = branch.upstream.split("/");
+  destination = { remote: upstreamRemote, branch: rest.join("/") };
+  if (remote && remote !== upstreamRemote)
+    stops.push(`the upstream is on ${upstreamRemote}, not ${remote}: pushing elsewhere changes the route`);
+  remote = upstreamRemote;
+  if (destination.branch !== branch.branch)
+    notes.push(`the upstream branch is named ${destination.branch}, not ${branch.branch}`);
+  if (branch.behind && branch.ahead)
+    stops.push(`local and ${branch.upstream} have diverged (ahead ${branch.ahead}, behind ${branch.behind})`);
+  else if (branch.behind) stops.push(`${branch.upstream} has ${branch.behind} commit(s) this branch lacks`);
+  else if (!branch.ahead) notes.push(`nothing to push: ${branch.upstream} already has HEAD (local refs)`);
+  command = `git push ${remote} ${branch.branch}${destination.branch !== branch.branch ? `:${destination.branch}` : ""}`;
+} else if (branch.branch) {
+  if (!remote) {
+    if (remotes.length === 1) [remote] = remotes;
+    else if (remotes.includes("origin")) {
+      remote = "origin";
+      notes.push(`several remotes (${remotes.join(", ")}); origin assumed: confirm it`);
+    } else
+      stops.push(remotes.length ? `no upstream and several remotes (${remotes.join(", ")}): name one` : "no remote");
+  }
+  if (remote) {
+    destination = { remote, branch: branch.branch };
+    const existing = git(root, ["rev-parse", "--verify", "--quiet", `refs/remotes/${remote}/${branch.branch}`]);
+    if (existing) {
+      const behind = Number(git(root, ["rev-list", "--count", `HEAD..${remote}/${branch.branch}`]) ?? 0);
+      if (behind) stops.push(`${remote}/${branch.branch} exists with ${behind} commit(s) this branch lacks`);
+      notes.push(`${remote}/${branch.branch} exists but is not the upstream: setting it is part of the yes`);
+    }
+    command = `git push --set-upstream ${remote} ${branch.branch}`;
+    notes.push("no upstream yet: this push sets one");
+  }
+}
+
+const commits = destination
+  ? (
+      git(root, ["log", "--oneline", "--no-decorate", `${destination.remote}/${destination.branch}..HEAD`]) ??
+      git(root, ["log", "--oneline", "--no-decorate", "HEAD", "--not", `--remotes=${destination.remote}`]) ??
+      ""
+    )
+      .split("\n")
+      .filter(Boolean)
+  : [];
+const working = workingState(root);
+if (working.staged.length || working.unstaged.length)
+  notes.push(`${working.staged.length + working.unstaged.length} uncommitted change(s) will not be pushed`);
+
+const report = {
+  command: "push-route",
+  root,
+  branch: branch.branch,
+  head: branch.head?.slice(0, 12) ?? null,
+  upstream: branch.upstream,
+  ahead: branch.ahead,
+  behind: branch.behind,
+  remotes: urls,
+  destination,
+  commits: commits.slice(0, 20),
+  commitsCut: Math.max(0, commits.length - 20),
+  pushCommand: stops.length ? null : command,
+  stops,
+  notes,
+  notChecked: [
+    "the remote's current state (counts use local refs)",
+    "branch protection and shared-branch policy",
+    "whether a force push would be needed",
+  ],
+};
+if (values.json) console.log(JSON.stringify(report, null, 2));
+else {
+  console.log(
+    `Branch ${branch.branch ?? "(detached)"} at ${report.head ?? "none"} -> ${destination ? `${destination.remote}/${destination.branch}` : "no destination"}${remote && urls[remote] ? ` (${urls[remote]})` : ""}`,
+  );
+  console.log(`Commits to send (${commits.length}, from local refs):`);
+  for (const commit of report.commits) console.log(`  ${commit}`);
+  if (report.commitsCut) console.log(`  ... ${report.commitsCut} more`);
+  for (const note of notes) console.log(`Note: ${note}`);
+  console.log(stops.length ? `Stop:\n${stops.map((each) => `- ${each}`).join("\n")}` : `Simple push: ${command}`);
+  console.log(`Not checked: ${report.notChecked.join("; ")}.`);
+}
+process.exit(stops.length ? 1 : 0);