@joshuafolkken/kit 1.3099.0 → 1.3125.0

package/dist/commands/chunk-TNPFVNKX.js

@@ -0,0 +1,585 @@
+import {
+  git_pr_merge_checked
+} from "./chunk-V37AWEYE.js";
+import {
+  main_sync
+} from "./chunk-HF52YP56.js";
+import {
+  lane_install
+} from "./chunk-LAQZJX5C.js";
+import {
+  observation_ledger_prepare
+} from "./chunk-ZHEUK3ZX.js";
+import {
+  review_comment_carry
+} from "./chunk-QDUWBRQC.js";
+import {
+  observation_ledger_archive
+} from "./chunk-5SOU366I.js";
+import {
+  git_gh_command,
+  git_pr_checks
+} from "./chunk-VJNE7W7O.js";
+import {
+  OBSERVATION_LEDGER_DIRECTORY,
+  observation_ledger
+} from "./chunk-SV4FZR24.js";
+import {
+  git_worktree
+} from "./chunk-2AH73ZTW.js";
+import {
+  repository_lock
+} from "./chunk-GC73YEU7.js";
+import {
+  IGNORE_FOR_RELEASE_LABEL
+} from "./chunk-QQBMVC5W.js";
+import {
+  issue_cite
+} from "./chunk-HQ2HSZBN.js";
+import {
+  poll
+} from "./chunk-SBGTCT2C.js";
+import {
+  error_text
+} from "./chunk-CDY4NFQG.js";
+import {
+  git_command
+} from "./chunk-KMED24C4.js";
+import {
+  git_spawn
+} from "./chunk-LZNACCHR.js";
+import {
+  git_spawn_sync
+} from "./chunk-B77ZMVHS.js";
+import {
+  SUITE_TIMEOUT_MS
+} from "./chunk-WPAQUMHC.js";
+
+// scripts/observations/observations-flush-landing.ts
+var AUTO_MERGE_WARNING = "Could not enable auto-merge on the flush pull request, so it merges only if this command stays alive to merge it:";
+var MERGE_TIMEOUT_REASON = "auto-merge is enabled, but the pull request did not merge within the checks budget";
+var MERGE_FAILED_REASON = "a required check failed or the branch conflicts, so auto-merge will not land the pull request";
+async function request_auto_merge(branch_name) {
+  try {
+    await git_gh_command.pr_enable_auto_merge(branch_name, await git_command.head_commit());
+    return true;
+  } catch (error) {
+    console.warn(AUTO_MERGE_WARNING, error_text.message_of(error));
+    return false;
+  }
+}
+async function wait_for_landing(branch_name, is_auto_merge) {
+  if (!is_auto_merge) {
+    await git_pr_merge_checked.merge_when_green(branch_name);
+    return;
+  }
+  const progress = await git_pr_checks.wait_for_pr_merged(branch_name);
+  if (progress === "failed") throw new Error(MERGE_FAILED_REASON);
+  if (progress === "waiting") throw new Error(MERGE_TIMEOUT_REASON);
+}
+function describe_pull(pull) {
+  return `${issue_cite.plain_for("github", pull.number)} (\`${pull.head_ref}\`)`;
+}
+async function is_landing(pull) {
+  if (!pull.has_auto_merge) return false;
+  return await git_pr_checks.read_merge_progress(pull.head_ref) !== "failed";
+}
+function landing_flush_message(pulls) {
+  return `deferred \u2014 an earlier flush pull request is still landing with auto-merge on: ${pulls.map((pull) => describe_pull(pull)).join(", ")}. A new flush branch would conflict with it at the ledger's tail, so the appended observations stay in this working tree for the next flush.`;
+}
+function stuck_flush_message(pulls) {
+  return `An earlier \`pnpm josh observations:flush\` left a pull request open that nothing will merge \u2014 unless a flush in another checkout is still waiting on it: ${pulls.map((pull) => describe_pull(pull)).join(", ")}. Its appended observations exist only on that branch \u2014 land it (resolve the ledger conflict if there is one, then merge) before flushing again, or a new flush would conflict with it.`;
+}
+async function refuse_open_flush(branch_prefix) {
+  const pulls = await git_gh_command.pr_list_open_with_head_prefix(branch_prefix);
+  if (pulls.length === 0) return void 0;
+  const verdicts = await Promise.all(pulls.map(async (pull) => await is_landing(pull)));
+  const stuck = pulls.filter((_pull, index) => verdicts[index] !== true);
+  if (stuck.length > 0) throw new Error(stuck_flush_message(stuck));
+  return landing_flush_message(pulls);
+}
+var observations_flush_landing = {
+  landing_flush_message,
+  MERGE_FAILED_REASON,
+  MERGE_TIMEOUT_REASON,
+  refuse_open_flush,
+  request_auto_merge,
+  stuck_flush_message,
+  wait_for_landing
+};
+
+// scripts/observations/observations-flush-transaction.ts
+import { randomUUID } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+var LOCK_WAIT_MS = 3e4;
+var COMMIT_MESSAGE = "Record observation ledger entries";
+var ATTEMPTS = 5;
+var INTERVAL_MS = 250;
+var snapshot_schema = z.object({
+  name: z.string(),
+  content: z.string().optional(),
+  base: z.string().optional()
+});
+var state_schema = z.object({
+  branch: z.string(),
+  base: z.string(),
+  tree: z.string(),
+  archived: z.number().optional(),
+  landed: z.boolean().optional(),
+  initialized: z.boolean().optional(),
+  committed: z.boolean().optional(),
+  installed: z.boolean().optional(),
+  index: z.string(),
+  files: z.array(snapshot_schema),
+  reconciled: z.array(snapshot_schema).optional()
+});
+function lock_failure(error) {
+  if (!/index\.lock.*(?:File exists|exists)/su.test(error_text.message_of(error))) throw error;
+}
+async function retry(work) {
+  const state = {};
+  const is_complete = await poll.poll_for(
+    async () => {
+      try {
+        await work();
+        delete state.failure;
+      } catch (error) {
+        lock_failure(error);
+        state.failure = error;
+      }
+      return state.failure === void 0 ? true : void 0;
+    },
+    { attempts: ATTEMPTS, interval_ms: INTERVAL_MS }
+  );
+  if (is_complete === void 0) throw state.failure;
+}
+function read(root, name) {
+  const target = path.join(root, name);
+  if (!existsSync(target)) return void 0;
+  if (!lstatSync(target).isFile()) throw new Error(`Not a regular ledger file: ${target}`);
+  return readFileSync(target, "utf8");
+}
+function write(root, name, content) {
+  const target = path.join(root, name);
+  if (content === void 0) {
+    rmSync(target, { force: true });
+    return;
+  }
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(target, content, "utf8");
+}
+async function capture(root) {
+  const output = await git_spawn.read([
+    "-C",
+    root,
+    "ls-files",
+    "-z",
+    "--cached",
+    "--others",
+    "--exclude-standard"
+  ]);
+  const names = new Set(
+    output.split("\0").filter((name) => observation_ledger.is_ledger_path(name))
+  );
+  return [...names].map((name) => ({
+    name,
+    content: read(root, name)
+  }));
+}
+function apply(root, files) {
+  for (const file of files) write(root, file.name, file.content);
+}
+function reconciled_content(file, suffix) {
+  if (suffix === "" && file.base === void 0) return void 0;
+  return (file.base ?? "") + suffix;
+}
+function reconciled_file(root, file) {
+  const current = read(root, file.name) ?? "";
+  const original = file.content ?? "";
+  if (!current.startsWith(original)) {
+    throw new Error(`Ledger changed beyond an append: ${file.name}; recovery retained`);
+  }
+  return { ...file, content: reconciled_content(file, current.slice(original.length)) };
+}
+function starts_with(current = "", expected = "") {
+  return current.startsWith(expected);
+}
+function restore_file(root, file, before) {
+  const current = read(root, file.name);
+  if (current === file.content) return;
+  if (before !== void 0 && starts_with(current, before.content)) {
+    write(root, file.name, reconciled_file(root, before).content);
+    return;
+  }
+  if (!starts_with(current, file.content)) throw new Error(`Recovery conflict: ${file.name}`);
+}
+function restore(root, before, after) {
+  for (const file of after) {
+    restore_file(
+      root,
+      file,
+      before.find((entry) => entry.name === file.name)
+    );
+  }
+}
+function save(target, state) {
+  writeFileSync(`${target}.tmp`, JSON.stringify(state), "utf8");
+  renameSync(`${target}.tmp`, target);
+}
+async function location(root) {
+  const own = await git_spawn.read(["-C", root, "rev-parse", "--absolute-git-dir"]);
+  const directory = path.join(own, "josh", "observation-flush");
+  mkdirSync(directory, { recursive: true });
+  return path.join(directory, "state.json");
+}
+async function create(root, branch, target) {
+  const existing = git_spawn_sync.read(
+    ["show-ref", "--verify", `refs/heads/${branch}`],
+    git_spawn_sync.located(root)
+  );
+  const state = {
+    branch: existing === void 0 ? branch : `${branch}-${randomUUID()}`,
+    base: await git_command.head_commit(),
+    index: await git_spawn.read(["-C", root, "diff", "--cached", "--binary"]),
+    tree: `${path.dirname(target)}/tree`,
+    files: await capture(root)
+  };
+  save(target, state);
+  return state;
+}
+async function initialize(root, state, target) {
+  if (state.initialized === true) return;
+  const existing = git_spawn_sync.read(
+    ["show-ref", "--verify", `refs/heads/${state.branch}`],
+    git_spawn_sync.located(root)
+  );
+  if (!existsSync(state.tree)) {
+    await git_worktree.worktree_add(
+      state.tree,
+      state.branch,
+      existing === void 0 ? state.base : void 0
+    );
+  }
+  Object.assign(state, {
+    files: state.files.map((file) => ({ ...file, base: read(state.tree, file.name) })),
+    initialized: true
+  });
+  save(target, state);
+}
+async function load(root, branch, target) {
+  const state = existsSync(target) ? state_schema.parse(JSON.parse(readFileSync(target, "utf8"))) : await create(root, branch, target);
+  await initialize(root, state, target);
+  return state;
+}
+async function pending(root) {
+  return existsSync(await location(root));
+}
+async function reset_preparation(state, target) {
+  const ledger = path.join(state.tree, OBSERVATION_LEDGER_DIRECTORY);
+  if (existsSync(ledger)) {
+    cpSync(ledger, `${path.dirname(target)}/attempt-${String(Date.now())}`, { recursive: true });
+  }
+  await git_spawn.read(["reset", "--hard", state.base]);
+  await git_spawn.read(["clean", "-fd", "--", OBSERVATION_LEDGER_DIRECTORY]);
+  apply(state.tree, state.files);
+}
+async function stage() {
+  const status = await git_command.status();
+  const unstaged = status.split("\n").filter((line) => line[1] !== " ").join("\n");
+  const names = observation_ledger.ledger_paths(unstaged);
+  for (const name of names) {
+    await retry(async () => await git_spawn.read(["add", "--", name]));
+  }
+}
+async function prepare(state, target, steps) {
+  if (await git_command.head_commit() !== state.base) return;
+  if (state.archived === void 0) {
+    await reset_preparation(state, target);
+    Object.assign(state, { archived: await steps.prepare() });
+    save(target, state);
+  }
+  await stage();
+  if (!observation_ledger.has_pending_append(await git_command.status())) return;
+  await retry(async () => await git_spawn.read(["commit", "-m", COMMIT_MESSAGE], SUITE_TIMEOUT_MS));
+}
+async function publish(state, target, steps) {
+  const is_committed = await git_command.head_commit() !== state.base;
+  Object.assign(state, { committed: is_committed });
+  save(target, state);
+  if (is_committed) await steps.publish(state.branch, state.archived ?? 0);
+  Object.assign(state, { landed: true });
+  save(target, state);
+}
+async function install(state, target) {
+  if (state.installed === true) return;
+  const result = await lane_install.install_dependencies(state.tree);
+  if (!result.is_installed) {
+    throw new Error(`Flush worktree dependency installation failed: ${result.output}`);
+  }
+  Object.assign(state, { installed: true });
+  save(target, state);
+}
+async function inside(state, target, steps) {
+  if (state.landed === true) return;
+  const previous = process.cwd();
+  try {
+    process.chdir(state.tree);
+    await install(state, target);
+    await prepare(state, target, steps);
+    await publish(state, target, steps);
+  } finally {
+    process.chdir(previous);
+  }
+}
+async function finish(root, state, target) {
+  const index = await git_spawn.read(["-C", root, "diff", "--cached", "--binary"]);
+  if (index !== state.index) throw new Error("Source index changed during flush; recovery retained");
+  state.reconciled ??= state.files.map((file) => reconciled_file(root, file));
+  save(target, state);
+  restore(root, state.files, state.reconciled);
+  if (existsSync(state.tree)) await git_worktree.worktree_remove(state.tree);
+  renameSync(target, `${target}.completed-${path.basename(state.branch)}`);
+}
+async function transact(root, branch, steps) {
+  const target = await location(root);
+  try {
+    const state = await load(root, branch, target);
+    await inside(state, target, steps);
+    await finish(root, state, target);
+    return state.committed === true ? state.branch : "";
+  } catch (error) {
+    throw new Error(
+      `${error_text.message_of(error)} \u2014 observations recovery: ${target}; rerun observations:flush; do not remove the recovery tree`,
+      { cause: error }
+    );
+  }
+}
+async function run(root, branch, steps) {
+  const lock = repository_lock.lock_path("josh-observation-flush-", root);
+  const result = await repository_lock.with_lock(
+    async () => await transact(root, branch, steps),
+    lock,
+    LOCK_WAIT_MS
+  );
+  if (result === void 0) throw new Error("Observation flush is already running; retry later");
+  return result;
+}
+var observations_flush_transaction = { pending, run };
+
+// scripts/observations/observations-flush.ts
+var COMMIT_MESSAGE2 = "Record observation ledger entries";
+var CLEAN_MESSAGE = `clean \u2014 ${OBSERVATION_LEDGER_DIRECTORY} matches the commit it sits on, so there is nothing to flush`;
+var BRANCH_PREFIX = "observations/";
+var SUCCESS_EXIT_CODE = 0;
+var RETURN_FAILURE_MESSAGE = "Could not return this checkout to the default branch; `pnpm josh ms` printed the reason above.";
+var DATE_END = 10;
+var TIME_START = 11;
+var TIME_END = 19;
+var COLON = ":";
+var NO_COMMITS = 0;
+var NO_ARCHIVED_FILES = 0;
+var UNKNOWN_COMMIT_COUNT = 1;
+function timestamp_for(now) {
+  const iso = now.toISOString();
+  return `${iso.slice(0, DATE_END)}-${iso.slice(TIME_START, TIME_END).replaceAll(COLON, "")}`;
+}
+function branch_name_for(stamp) {
+  return `${BRANCH_PREFIX}${stamp}`;
+}
+function ledger_change_sentence(archived_files) {
+  if (archived_files === NO_ARCHIVED_FILES) {
+    return "so this pull request adds lines and changes none.";
+  }
+  return `so this pull request drops none: it adds lines, and moves ${String(archived_files)} closed issues' file(s) verbatim into the monthly \`archive-YYYY-MM.md\` files.`;
+}
+function pull_request_body(archived_files) {
+  return [
+    `Appended observations from \`${OBSERVATION_LEDGER_DIRECTORY}\` that no run's own commit carried.`,
+    "",
+    `The ledger is append-only, and a second line under one key is what promotes an observation to an issue \u2014 ${ledger_change_sentence(archived_files)}`,
+    "",
+    "Opened by `pnpm josh observations:flush` (joshuafolkken/kit#1756)."
+  ].join("\n");
+}
+function status_paths(status_output) {
+  return status_output.split("\n").filter((line) => line.trim().length > 0).map((line) => observation_ledger.status_path(line));
+}
+function has_ledger_change(status_output) {
+  return observation_ledger.has_pending_append(status_output);
+}
+function other_changed_paths(status_output) {
+  return status_paths(status_output).filter(
+    (file_path) => !observation_ledger.is_ledger_path(file_path)
+  );
+}
+function stranded_flush_message(current) {
+  return `\`${current}\` is a flush branch an earlier \`pnpm josh observations:flush\` left behind, and its appended observations are committed only there. Land it before flushing again \u2014 \`git push -u origin ${current}\`, then open and merge its pull request; \`pnpm josh ms\` here would leave the only copy of those lines behind.`;
+}
+function empty_flush_message(current) {
+  return `\`${current}\` is a flush branch an earlier \`pnpm josh observations:flush\` left behind with no commit on it, so nothing is stranded: the appended observations are still in this working tree. Run \`pnpm josh ms\` and flush again \u2014 that cuts a fresh branch and loses no line, leaving \`${current}\` as an empty branch to clear whenever it suits you.`;
+}
+function flush_branch_message(current, commit_count) {
+  return commit_count === NO_COMMITS ? empty_flush_message(current) : stranded_flush_message(current);
+}
+function off_default_message(current, default_branch) {
+  return `\`pnpm josh observations:flush\` opens a branch of its own, so it starts from \`${default_branch}\` \u2014 this checkout is on \`${current}\`. Run \`pnpm josh ms\` first.`;
+}
+function behind_default_message(default_branch, reason) {
+  return `\`pnpm josh observations:flush\` cuts its branch from \`${default_branch}\`, which is behind \`origin/${default_branch}\` and could not be fast-forwarded (${reason}) \u2014 a branch cut here would open a pull request that cannot merge. Run \`pnpm josh ms\` first.`;
+}
+function is_flush_branch(current) {
+  return current.startsWith(BRANCH_PREFIX);
+}
+function rejected_commit_message(branch_name, reason) {
+  return `The ledger's commit was rejected, so \`${branch_name}\` was removed and this checkout is back on the default branch: ${reason} \u2014 the appended observations are still in the working tree. Fix what was rejected and run \`pnpm josh observations:flush\` again.`;
+}
+function roll_back_failure_message(branch_name, reason, roll_back_reason) {
+  return `The ledger's commit was rejected and \`${branch_name}\` could not be cleaned up afterwards. The commit was rejected by: ${reason}. The cleanup failed with: ${roll_back_reason}. Nothing was committed to that branch and the appended observations are still in the working tree, so \`pnpm josh ms\` followed by another flush loses no line.`;
+}
+function other_changes_message(paths) {
+  return `The working tree holds changes besides the ledger, so \`pnpm josh observations:flush\` stops rather than committing them: ${paths.join(", ")}`;
+}
+function stranded_branch_message(branch_name, reason) {
+  return `The ledger is committed on \`${branch_name}\` and the flush then failed: ${reason} \u2014 those lines now exist only on that branch, and this checkout is still on it. Finish that branch's pull request before running \`pnpm josh ms\` here.`;
+}
+async function commits_beyond(base, tip) {
+  try {
+    return await git_command.commit_count_beyond(base, tip);
+  } catch {
+    return UNKNOWN_COMMIT_COUNT;
+  }
+}
+async function refuse_off_default(current, default_branch) {
+  if (!is_flush_branch(current)) throw new Error(off_default_message(current, default_branch));
+  throw new Error(flush_branch_message(current, await commits_beyond(default_branch, current)));
+}
+async function commits_behind_default(default_branch) {
+  await git_command.fetch_branch(default_branch);
+  return await git_command.commit_count_beyond("HEAD", `origin/${default_branch}`);
+}
+async function catch_up_default(default_branch) {
+  if (await commits_behind_default(default_branch) === NO_COMMITS) return;
+  try {
+    await git_command.merge_fast_forward(default_branch);
+  } catch (error) {
+    throw new Error(behind_default_message(default_branch, error_text.message_of(error)), {
+      cause: error
+    });
+  }
+}
+async function refuse_unsafe_flush(status_output) {
+  const current = await git_command.branch();
+  const default_branch = await git_command.get_default_branch();
+  if (current !== default_branch) await refuse_off_default(current, default_branch);
+  const others = other_changed_paths(status_output);
+  if (others.length > 0) throw new Error(other_changes_message(others));
+  return default_branch;
+}
+async function return_to_default_branch(default_branch) {
+  if (await git_command.branch() !== default_branch) throw new Error(RETURN_FAILURE_MESSAGE);
+  const exit_code = await main_sync.run([]);
+  if (exit_code !== SUCCESS_EXIT_CODE) throw new Error(RETURN_FAILURE_MESSAGE);
+}
+async function push_and_open(branch_name, body) {
+  try {
+    await git_command.push();
+    return await git_gh_command.pr_create(COMMIT_MESSAGE2, body, IGNORE_FOR_RELEASE_LABEL);
+  } catch (error) {
+    throw new Error(
+      `The ledger is committed on \`${branch_name}\` in the recovery worktree; publication failed: ${error_text.message_of(error)}. The source checkout and original records are preserved. Rerun \`pnpm josh observations:flush\` from the source checkout to resume.`,
+      { cause: error }
+    );
+  }
+}
+function merged_message(branch_name) {
+  return `merged \`${branch_name}\` \u2014 the appended observations are on the default branch`;
+}
+function broken_lines_message(broken) {
+  const rows = broken.map((entry) => `  ${entry.line}
+    \u21B3 ${entry.reason}`).join("\n");
+  return `\`${OBSERVATION_LEDGER_DIRECTORY}\` has ${String(broken.length)} line(s) that break the ledger grammar, so the ledger commit stops rather than carrying them:
+${rows}`;
+}
+async function prepare_ledger() {
+  const broken = await observation_ledger_prepare.prepare(process.cwd());
+  if (broken.length > 0) throw new Error(broken_lines_message(broken));
+}
+async function ready_default_branch(status_output) {
+  const default_branch = await refuse_unsafe_flush(status_output);
+  if (status_output.split("\n").some((line) => /^[^ ?]/u.test(line))) {
+    throw new Error(
+      "Staged changes must be committed or unstaged before observations:flush; index left untouched"
+    );
+  }
+  if (!await observations_flush_transaction.pending(process.cwd())) {
+    await catch_up_default(default_branch);
+  }
+  return default_branch;
+}
+async function carried_status() {
+  await review_comment_carry.carry_reported(process.cwd());
+  const archived_files = await observation_ledger_archive.archive(process.cwd());
+  return { status_output: await git_command.status(), archived_files };
+}
+async function prepare_isolated() {
+  const { archived_files } = await carried_status();
+  await prepare_ledger();
+  return archived_files;
+}
+async function publish_isolated(branch_name, archived_files) {
+  if (await git_pr_checks.read_merge_progress(branch_name) === "merged") return;
+  const open = await git_gh_command.pr_list_open_with_head_prefix(branch_name);
+  if (open.length === 0) {
+    console.info(await push_and_open(branch_name, pull_request_body(archived_files)));
+  }
+  const is_auto_merge = await observations_flush_landing.request_auto_merge(branch_name);
+  await observations_flush_landing.wait_for_landing(branch_name, is_auto_merge);
+}
+async function flush(now) {
+  const default_branch = await ready_default_branch(await git_command.status());
+  const is_pending = await observations_flush_transaction.pending(process.cwd());
+  const deferred = is_pending ? void 0 : await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX);
+  if (deferred !== void 0) return deferred;
+  const branch_name = branch_name_for(timestamp_for(now));
+  const committed_branch = await observations_flush_transaction.run(process.cwd(), branch_name, {
+    prepare: prepare_isolated,
+    publish: publish_isolated
+  });
+  if (committed_branch === "") return CLEAN_MESSAGE;
+  await return_to_default_branch(default_branch);
+  return merged_message(committed_branch);
+}
+var observations_flush = {
+  behind_default_message,
+  branch_name_for,
+  broken_lines_message,
+  CLEAN_MESSAGE,
+  COMMIT_MESSAGE: COMMIT_MESSAGE2,
+  flush,
+  flush_branch_message,
+  has_ledger_change,
+  merged_message,
+  off_default_message,
+  other_changed_paths,
+  other_changes_message,
+  pull_request_body,
+  rejected_commit_message,
+  roll_back_failure_message,
+  stranded_branch_message,
+  timestamp_for
+};
+
+export {
+  observations_flush
+};