filegrc 0.3.2 → 0.3.4

package/src/git.js

@@ -1,7 +1,14 @@
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { isSafeGitName } from "./git-name.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
 import { resolveWorkspaceRoot } from "./paths.js";
 import { validateWorkspace } from "./validate.js";
+import { loadWorkspace } from "./workspace.js";
+
+const lastSuccessfulSynchronizations = new Map();
 
 export function getGitSummary(input = process.cwd()) {
   const root = resolveWorkspaceRoot(input);
@@ -120,6 +127,175 @@ export async function pushWorkspace(input = process.cwd()) {
   return serializeWorkspaceMutation(input, pushWorkspaceUnlocked);
 }
 
+export async function getBrowserRepositoryState(input = process.cwd(), options = {}) {
+  const root = resolveWorkspaceRoot(input);
+  const config = await getRepositoryConfig(root);
+  const gitSummary = getGitSummary(root);
+  if (config.mode !== "trunk") {
+    return {
+      mode: "manual",
+      authoritativeBranch: config.authoritativeBranch,
+      remote: config.remote,
+      developmentOverride: false,
+      status: "manual",
+      label: "Manual Git",
+      writesAllowed: !options.readOnly,
+      currentCommit: gitSummary.commit,
+      upstreamCommit: null,
+      ahead: null,
+      behind: null,
+      pendingCommits: [],
+      pendingCommitsFilegrcOnly: null,
+      lastSuccessfulSynchronization: lastSuccessfulSynchronizations.get(root) ?? null,
+      message: "Browser writes stay local until a user commits and synchronizes them."
+    };
+  }
+
+  const details = inspectTrunkRepository(root, config, gitSummary);
+  const developmentOverride = options.allowNonAuthoritativeWrites === true;
+  if (developmentOverride) {
+    return {
+      ...details,
+      developmentOverride: true,
+      writesAllowed: !options.readOnly,
+      status: "not-synced",
+      label: "Not synced",
+      message: "Development override is active. Browser writes stay local and FileGRC will not commit or push them."
+    };
+  }
+  return {
+    ...details,
+    developmentOverride: false,
+    writesAllowed: !options.readOnly && details.writesAllowed
+  };
+}
+
+export async function runBrowserMutation(input, options, task) {
+  return serializeWorkspaceMutation(input, async (root) => {
+    const config = await getRepositoryConfig(root);
+    if (config.mode !== "trunk" || options?.allowNonAuthoritativeWrites === true) {
+      return task(root);
+    }
+    return runTrunkMutationUnlocked(root, config, options, task);
+  });
+}
+
+export async function retryBrowserSync(input = process.cwd(), options = {}) {
+  return serializeWorkspaceMutation(input, async (root) => {
+    const config = await getRepositoryConfig(root);
+    if (config.mode !== "trunk") throw new Error("Retry sync is available only in trunk repository mode.");
+    if (options.allowNonAuthoritativeWrites === true) {
+      throw new Error("Retry sync is disabled while the development write override is active.");
+    }
+    const before = requireTrunkPreconditions(root, config, { allowAhead: true });
+    fetchConfiguredRemote(root, config.remote);
+    const synchronized = inspectTrunkRepository(root, config, getGitSummary(root));
+    if (synchronized.behind > 0 && synchronized.ahead > 0) {
+      throw new Error("The authoritative branch has diverged from its upstream. FileGRC will not merge or rebase it. Reconcile the repository with Git, then reload.");
+    }
+    if (synchronized.behind > 0) {
+      fastForwardConfiguredBranch(root, synchronized.upstream);
+    }
+    const ready = inspectTrunkRepository(root, config, getGitSummary(root));
+    if (ready.ahead > 0 && !ready.pendingCommitsFilegrcOnly) {
+      throw new Error("At least one commit ahead of upstream changes files outside this FileGRC workspace. FileGRC will not push it. Reconcile the repository with Git.");
+    }
+    if (ready.ahead > 0) pushConfiguredBranch(root, config);
+    const after = inspectTrunkRepository(root, config, getGitSummary(root));
+    if (after.ahead !== 0 || after.behind !== 0) {
+      throw new Error("The authoritative branch is still not synchronized. Reload the repository state before trying again.");
+    }
+    const synchronizedAt = new Date().toISOString();
+    lastSuccessfulSynchronizations.set(root, synchronizedAt);
+    return {
+      commit: after.currentCommit,
+      shortCommit: after.currentCommit?.slice(0, 8) ?? null,
+      branch: config.authoritativeBranch,
+      upstream: after.upstream,
+      synchronizedAt,
+      retriedCommits: before.ahead ?? 0
+    };
+  });
+}
+
+async function runTrunkMutationUnlocked(root, config, options, task) {
+  requireTrunkPreconditions(root, config);
+  fetchConfiguredRemote(root, config.remote);
+  let synchronized = inspectTrunkRepository(root, config, getGitSummary(root));
+  if (synchronized.ahead > 0 && synchronized.behind > 0) {
+    throw new Error("The authoritative branch has diverged from its upstream. FileGRC will not merge or rebase it. Reconcile the repository with Git, then reload.");
+  }
+  if (synchronized.ahead > 0) {
+    throw new Error("The authoritative branch has local commits waiting to be pushed. Use Retry sync before making another browser change.");
+  }
+  if (synchronized.behind > 0) {
+    fastForwardConfiguredBranch(root, synchronized.upstream);
+    synchronized = inspectTrunkRepository(root, config, getGitSummary(root));
+  }
+  if (synchronized.ahead !== 0 || synchronized.behind !== 0) {
+    throw new Error("The authoritative branch is not synchronized with its upstream. Reload after reconciling the repository with Git.");
+  }
+
+  let result;
+  let subject;
+  try {
+    result = await task(root);
+    subject = generatedCommitMessage(typeof options?.message === "function" ? options.message(result) : options?.message);
+    const validation = await validateWorkspace(root);
+    if (!validation.ok) {
+      throw new Error(`The workspace has ${validation.counts.errors} validation ${validation.counts.errors === 1 ? "error" : "errors"}. The browser change was rolled back.`);
+    }
+    assertNoOutsideWorktreeChanges(root);
+  } catch (error) {
+    try {
+      await rollbackWorkspaceChanges(root);
+    } catch (rollbackError) {
+      throw new Error(`${error.message} FileGRC could not roll back the workspace change. ${rollbackError.message} Later browser mutations are blocked until the Git worktree is reconciled.`);
+    }
+    throw error;
+  }
+
+  if (!getGitSummary(root).changes.length) {
+    throw new Error("The browser action did not change any FileGRC workspace files.");
+  }
+  if (!tryGit(root, ["config", "user.name"]) || !tryGit(root, ["config", "user.email"])) {
+    throw new Error("Configure git user.name and git user.email before browser changes can be committed. The saved files remain uncommitted and later browser changes are blocked.");
+  }
+  gitForWrite(root, ["add", "--all", "--", "."], "stage the FileGRC workspace change");
+  assertNoOutsideWorktreeChanges(root, false);
+  assertOnlyWorkspaceFilesStaged(root);
+  try {
+    gitForWrite(root, ["commit", "-m", subject, "--", "."], "create the FileGRC browser commit");
+  } catch (error) {
+    throw new Error(`${error.message} The saved files remain in the Git worktree and later browser changes are blocked.`);
+  }
+
+  const committed = getGitSummary(root);
+  let pushError = null;
+  try {
+    pushConfiguredBranch(root, config);
+  } catch (error) {
+    pushError = `${error.message} The local FileGRC commit was retained. Use Retry sync after the remote is available.`;
+  }
+  const after = inspectTrunkRepository(root, config, getGitSummary(root));
+  let synchronizedAt = null;
+  if (!pushError && after.ahead === 0 && after.behind === 0) {
+    synchronizedAt = new Date().toISOString();
+    lastSuccessfulSynchronizations.set(root, synchronizedAt);
+  }
+  return {
+    ...result,
+    synchronization: {
+      status: pushError ? "not-synced" : "synced",
+      commit: committed.commit,
+      shortCommit: committed.shortCommit,
+      upstream: after.upstream,
+      synchronizedAt,
+      pushError
+    }
+  };
+}
+
 async function commitWorkspaceUnlocked(root, message) {
   const subject = String(message ?? "").trim();
   if (!subject || subject.length > 200 || /[\u0000-\u001f\u007f]/.test(subject)) {
@@ -233,6 +409,299 @@ function syncReadySummary(root, action) {
   return summary;
 }
 
+async function getRepositoryConfig(root) {
+  const loaded = await loadWorkspace(root);
+  const renderer = loaded.resources.find(({ type, id }) => type === "renderer-settings" && id === "renderer-settings");
+  const mode = renderer?.repositoryMode === "trunk" ? "trunk" : "manual";
+  const authoritativeBranch = cleanGitName(renderer?.authoritativeBranch, "main");
+  const remote = cleanGitName(renderer?.repositoryRemote, "origin");
+  return {
+    mode,
+    authoritativeBranch,
+    remote,
+    configurationError: !isSafeGitName(authoritativeBranch)
+      ? "The configured authoritative branch is not a safe Git branch name. Update renderer settings before using browser writes."
+      : !isSafeGitName(remote)
+        ? "The configured repository remote is not a safe Git remote name. Update renderer settings before using browser writes."
+        : null
+  };
+}
+
+function inspectTrunkRepository(root, config, summary = getGitSummary(root)) {
+  const base = {
+    mode: "trunk",
+    authoritativeBranch: config.authoritativeBranch,
+    remote: config.remote,
+    currentCommit: summary.commit,
+    upstreamCommit: null,
+    upstream: summary.upstream,
+    ahead: null,
+    behind: null,
+    pendingCommits: [],
+    pendingCommitsFilegrcOnly: null,
+    lastSuccessfulSynchronization: lastSuccessfulSynchronizations.get(root) ?? null,
+    wholeWorktreeClean: summary.available ? wholeWorktreeClean(root) : null,
+    operationInProgress: summary.available ? repositoryOperation(root) : null,
+    writesAllowed: false
+  };
+  if (config.configurationError) {
+    return {
+      ...base,
+      status: "git-setup-required",
+      label: "Git setup required",
+      message: config.configurationError
+    };
+  }
+  if (!summary.available) {
+    return {
+      ...base,
+      status: "git-setup-required",
+      label: "Git setup required",
+      message: "Git is unavailable. Install Git and open this workspace from its authoritative repository checkout."
+    };
+  }
+  if (summary.branch !== config.authoritativeBranch) {
+    return {
+      ...base,
+      status: "read-only-checkout",
+      label: "Read-only checkout",
+      message: "This checkout is not the authoritative FileGRC branch. You can review the program here, but browser changes are disabled. Run FileGRC from the main checkout or use the explicit development override."
+    };
+  }
+  if (!summary.remotes.includes(config.remote)) {
+    return {
+      ...base,
+      status: "git-setup-required",
+      label: "Git setup required",
+      message: `The configured Git remote "${config.remote}" does not exist. Add it and configure the authoritative branch upstream before using browser writes.`
+    };
+  }
+  const expectedUpstream = `${config.remote}/${config.authoritativeBranch}`;
+  if (summary.upstream !== expectedUpstream) {
+    return {
+      ...base,
+      status: "git-setup-required",
+      label: "Git setup required",
+      message: `The authoritative branch must track ${expectedUpstream}. Configure that upstream with Git before using browser writes.`
+    };
+  }
+  const upstreamCommit = tryGit(root, ["rev-parse", expectedUpstream]) || null;
+  const counts = upstreamCommit ? aheadBehind(root, expectedUpstream) : { ahead: null, behind: null };
+  const pendingCommits = counts.ahead > 0 ? commitsAhead(root, expectedUpstream) : [];
+  const pendingCommitsFilegrcOnly = counts.ahead > 0 ? commitsOnlyTouchWorkspace(root, expectedUpstream) : true;
+  const details = {
+    ...base,
+    upstreamCommit,
+    ahead: counts.ahead,
+    behind: counts.behind,
+    pendingCommits,
+    pendingCommitsFilegrcOnly
+  };
+  if (base.operationInProgress) {
+    return {
+      ...details,
+      status: "not-synced",
+      label: "Not synced",
+      message: `A Git ${base.operationInProgress} is in progress. Finish or abort it with Git before using browser writes.`
+    };
+  }
+  if (!base.wholeWorktreeClean) {
+    return {
+      ...details,
+      status: "not-synced",
+      label: "Not synced",
+      message: "The Git worktree has uncommitted changes. Commit, discard, or move them with Git before using browser writes."
+    };
+  }
+  if (counts.ahead === null || counts.behind === null) {
+    return {
+      ...details,
+      status: "git-setup-required",
+      label: "Git setup required",
+      message: `The upstream ${expectedUpstream} is unavailable locally. Fetch ${config.remote} with Git, then reload.`
+    };
+  }
+  if (counts.ahead > 0 || counts.behind > 0) {
+    const external = counts.ahead > 0 && !pendingCommitsFilegrcOnly;
+    return {
+      ...details,
+      status: "not-synced",
+      label: "Not synced",
+      message: external
+        ? "A commit ahead of upstream changes files outside this FileGRC workspace. Reconcile it with Git. FileGRC will not push it."
+        : counts.ahead > 0 && counts.behind > 0
+          ? "The authoritative branch has diverged from upstream. Reconcile it with Git. FileGRC will not merge or rebase it."
+          : counts.ahead > 0
+            ? "FileGRC-only commits are waiting to be pushed. Use Retry sync."
+            : "The authoritative branch is behind upstream. The next browser mutation will fast-forward before writing.",
+      writesAllowed: counts.ahead === 0 && counts.behind > 0,
+      retrySafe: counts.ahead > 0 && counts.behind === 0 && pendingCommitsFilegrcOnly
+    };
+  }
+  return {
+    ...details,
+    status: "synced",
+    label: "Synced",
+    message: `The authoritative branch is synchronized with ${expectedUpstream}.`,
+    writesAllowed: true,
+    retrySafe: false
+  };
+}
+
+function requireTrunkPreconditions(root, config, options = {}) {
+  const summary = getGitSummary(root);
+  const state = inspectTrunkRepository(root, config, summary);
+  if (config.configurationError) throw new Error(state.message);
+  if (!summary.available) throw new Error(state.message);
+  if (summary.branch !== config.authoritativeBranch) throw new Error(state.message);
+  if (!summary.remotes.includes(config.remote)) throw new Error(state.message);
+  if (summary.upstream !== `${config.remote}/${config.authoritativeBranch}`) throw new Error(state.message);
+  if (state.operationInProgress) throw new Error(state.message);
+  if (!state.wholeWorktreeClean) throw new Error(state.message);
+  if (!options.allowAhead && state.ahead > 0) {
+    throw new Error("The authoritative branch has local commits waiting to be pushed. Use Retry sync before making another browser change.");
+  }
+  return state;
+}
+
+function fetchConfiguredRemote(root, remote) {
+  gitForWrite(root, ["fetch", "--prune", "--", remote], `fetch ${remote}`);
+}
+
+function fastForwardConfiguredBranch(root, upstream) {
+  gitForWrite(root, ["merge", "--ff-only", "--", upstream], `fast-forward from ${upstream}`);
+}
+
+function pushConfiguredBranch(root, config) {
+  gitForWrite(
+    root,
+    ["push", "--porcelain", "--", config.remote, `HEAD:refs/heads/${config.authoritativeBranch}`],
+    `push ${config.authoritativeBranch} to ${config.remote}`
+  );
+}
+
+function wholeWorktreeClean(root) {
+  return git(root, ["status", "--porcelain=v1"]) === "";
+}
+
+function repositoryOperation(root) {
+  for (const [name, gitPath] of [
+    ["merge", "MERGE_HEAD"],
+    ["rebase", "rebase-merge"],
+    ["rebase", "rebase-apply"],
+    ["cherry-pick", "CHERRY_PICK_HEAD"]
+  ]) {
+    const path = tryGit(root, ["rev-parse", "--git-path", gitPath]);
+    if (path && existsSync(resolve(root, path))) return name;
+  }
+  return null;
+}
+
+function aheadBehind(root, upstream) {
+  const output = tryGit(root, ["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+  const [ahead, behind] = output.split(/\s+/).map(Number);
+  return Number.isInteger(ahead) && Number.isInteger(behind)
+    ? { ahead, behind }
+    : { ahead: null, behind: null };
+}
+
+function commitsAhead(root, upstream) {
+  return lines(tryGit(root, ["log", "--format=%H%x1f%s", `${upstream}..HEAD`])).map((line) => {
+    const [commit, subject] = line.split("\x1f");
+    return { commit, shortCommit: commit.slice(0, 8), subject };
+  });
+}
+
+function commitsOnlyTouchWorkspace(root, upstream) {
+  const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
+  const prefix = relative(topLevel, root).split(sep).join("/");
+  const commits = lines(tryGit(root, ["rev-list", `${upstream}..HEAD`]));
+  return commits.every((commit) => {
+    const paths = nulFields(tryGitRaw(topLevel, [
+      "diff-tree",
+      "--no-commit-id",
+      "--name-only",
+      "-z",
+      "-r",
+      "--root",
+      commit
+    ]));
+    return paths.length > 0 && paths.every((path) => pathInsideWorkspace(path, prefix));
+  });
+}
+
+function assertNoOutsideWorktreeChanges(root, rollbackExpected = true) {
+  const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
+  const prefix = relative(topLevel, root).split(sep).join("/");
+  const paths = statusPaths(topLevel);
+  if (paths.some((path) => !pathInsideWorkspace(path, prefix))) {
+    throw new Error(rollbackExpected
+      ? "Files outside this FileGRC workspace changed while the browser action was running. The FileGRC change was rolled back; reconcile the other Git work first."
+      : "Files outside this FileGRC workspace changed while the browser action was being staged. The saved FileGRC files remain uncommitted and later browser mutations are blocked; reconcile the Git worktree.");
+  }
+}
+
+function assertOnlyWorkspaceFilesStaged(root) {
+  const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
+  const prefix = relative(topLevel, root).split(sep).join("/");
+  const staged = nulFields(tryGitRaw(topLevel, [
+    "diff",
+    "--cached",
+    "--name-only",
+    "-z",
+    "--diff-filter=ACDMRTUXB"
+  ]));
+  if (!staged.length) throw new Error("The browser action did not stage any FileGRC workspace files.");
+  if (staged.some((path) => !pathInsideWorkspace(path, prefix))) {
+    throw new Error("Git has staged files outside this FileGRC workspace. FileGRC will not create a browser commit until those files are unstaged.");
+  }
+}
+
+async function rollbackWorkspaceChanges(root) {
+  gitForWrite(root, ["restore", "--staged", "--worktree", "--source=HEAD", "--", "."], "roll back the FileGRC workspace change");
+  const untracked = nulFields(tryGitRaw(root, ["ls-files", "-z", "--others", "--exclude-standard", "--", "."]));
+  for (const path of untracked) {
+    const absolute = resolve(root, path);
+    if (absolute === root || !absolute.startsWith(`${root}${sep}`)) continue;
+    await rm(absolute, { force: true });
+  }
+}
+
+function statusPaths(topLevel) {
+  const output = tryGitRaw(topLevel, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  if (!output) return [];
+  const fields = nulFields(output);
+  const paths = [];
+  for (let index = 0; index < fields.length; index += 1) {
+    const field = fields[index];
+    if (!/^[ MADRCU?!]{2} /.test(field)) {
+      paths.push(field);
+      continue;
+    }
+    const status = field.slice(0, 2);
+    paths.push(field.slice(3));
+    if (/[RC]/.test(status) && fields[index + 1] !== undefined) paths.push(fields[++index]);
+  }
+  return paths;
+}
+
+function pathInsideWorkspace(path, prefix) {
+  return !prefix || path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function generatedCommitMessage(value) {
+  const subject = String(value ?? "")
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return (subject || "Update FileGRC workspace").slice(0, 200);
+}
+
+function cleanGitName(value, fallback) {
+  const normalized = String(value ?? fallback).trim();
+  return normalized || fallback;
+}
+
 function parseLogLine(line) {
   if (!line) return null;
   const [commit, timestamp, author, subject] = line.split("\x1f");
@@ -261,6 +730,28 @@ function tryGit(cwd, args) {
   }
 }
 
+function tryGitRaw(cwd, args) {
+  try {
+    return gitRaw(cwd, args);
+  } catch {
+    return "";
+  }
+}
+
+function gitRaw(cwd, args) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: 10_000,
+    maxBuffer: 20_000_000
+  });
+}
+
+function nulFields(source) {
+  return source ? source.split("\0").filter(Boolean) : [];
+}
+
 function gitForWrite(cwd, args, action = "create the commit") {
   try {
     return execFileSync("git", args, {
@@ -276,11 +767,18 @@ function gitForWrite(cwd, args, action = "create the commit") {
       }
     }).trim();
   } catch (error) {
-    const message = error.stderr?.trim() || error.stdout?.trim() || error.message;
+    const message = sanitizeGitErrorMessage(error.stderr?.trim() || error.stdout?.trim() || error.message);
     throw new Error(`Git could not ${action}. ${message}`);
   }
 }
 
+export function sanitizeGitErrorMessage(value) {
+  return String(value || "Git returned no error detail.")
+    .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^/\s@]+@/gi, "$1[redacted]@")
+    .replace(/([?&](?:access[_-]?token|auth|key|password|secret|token)=)[^&\s]+/gi, "$1[redacted]")
+    .replace(/\b(authorization:\s*)(?:basic|bearer)\s+\S+/gi, "$1[redacted]");
+}
+
 function tryGitForWrite(cwd, args) {
   try {
     gitForWrite(cwd, args);

package/src/index.js

@@ -18,11 +18,14 @@ export {
 export {
   commitAndPushWorkspace,
   commitWorkspace,
+  getBrowserRepositoryState,
   getFileHistory,
   getGitSummary,
   getWorkspaceHistories,
   pullWorkspace,
-  pushWorkspace
+  pushWorkspace,
+  retryBrowserSync,
+  runBrowserMutation
 } from "./git.js";
 export { generateModelDocumentation } from "./model-docs.js";
 export { renderMarkdown } from "./markdown.js";

package/src/mutation.js

@@ -1,11 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { resolveWorkspaceRoot } from "./paths.js";
 
 const mutationQueues = new Map();
+const activeMutation = new AsyncLocalStorage();
 
 export function serializeWorkspaceMutation(input, task) {
   const root = resolveWorkspaceRoot(input);
+  if (activeMutation.getStore() === root) return task(root);
   const previous = mutationQueues.get(root) ?? Promise.resolve();
-  const run = previous.catch(() => {}).then(() => task(root));
+  const run = previous.catch(() => {}).then(() => activeMutation.run(root, () => task(root)));
   let tracked;
   tracked = run.finally(() => {
     if (mutationQueues.get(root) === tracked) mutationQueues.delete(root);