@infinisys/is-devops 0.0.0-stage → 0.1.0

package/lib/bot-identity.js

@@ -0,0 +1,115 @@
+/**
+ * Stable `infinsys-*` identity used for machine-authored GitFox and Git data.
+ *
+ * GitFox attributes an issue or merge request to `<bot_name>@<token owner>`
+ * when `bot_name` is sent with a PAT or OAuth2 token. Git commits have no
+ * server-side bot field, so the same codename becomes the author and committer
+ * name. Both surfaces deliberately share one naming scheme so a reviewer can
+ * correlate an issue, a commit and a push.
+ */
+
+/** Bot namespace reserved for the Infinity System. */
+export const BOT_PREFIX = 'infinsys';
+
+/** Actor used when no live team role can be resolved. */
+export const DEFAULT_AGENT_ACTOR = 'agent';
+
+/** GitFox rejects bot names longer than a username. */
+const MAX_BOT_NAME_LENGTH = 50;
+
+/** Fallback used when an actor has no usable characters left. */
+const FALLBACK_ACTOR = 'agent';
+
+/**
+ * Turn an arbitrary role/member label into the suffix of a bot name.
+ *
+ * GitFox requires the first character to be alphanumeric and allows only
+ * letters, digits, `-`, `_` and `.`. A trailing/leading separator is trimmed so
+ * the public name never looks like `infinsys--dev`.
+ *
+ * @param {unknown} value - role id, member name or explicit actor.
+ * @returns {string} normalized actor suffix.
+ */
+export function normalizeActor(value) {
+  const text = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  const replaced = text.replaceAll(/[^a-z0-9._-]+/g, '-').replaceAll(/^[-._]+|[-._]+$/g, '');
+  if (replaced === '') return FALLBACK_ACTOR;
+  const room = MAX_BOT_NAME_LENGTH - BOT_PREFIX.length - 1;
+  return replaced.slice(0, room).replaceAll(/[-._]+$/g, '') || FALLBACK_ACTOR;
+}
+
+/**
+ * Build the public bot codename for one actor.
+ *
+ * @param {unknown} actor - role id, member name or explicit actor.
+ * @returns {string} `infinsys-<actor>` accepted by GitFox `bot_name`.
+ */
+export function botNameFor(actor) {
+  return `${BOT_PREFIX}-${normalizeActor(actor)}`;
+}
+
+/**
+ * Git author/committer identity for one actor.
+ *
+ * The email domain is deliberately local and stable: GitFox does not resolve
+ * bot emails to user accounts, and a fake public domain would invite mail
+ * misdelivery.
+ *
+ * @param {unknown} actor - role id, member name or explicit actor.
+ * @returns {{ name: string, email: string }} git identity fields.
+ */
+export function commitIdentityFor(actor) {
+  const botName = botNameFor(actor);
+  return { name: botName, email: `${botName}@infinity.bot` };
+}
+
+/**
+ * Normalize a resolver result into the actor record the tools consume.
+ *
+ * Resolvers are optional: `is-fabric-team` registers one to expose the live
+ * team role, its file boundary and the pinned project. A plain Agent session
+ * gets the unrestricted `infinsys-agent` actor, which preserves the previous
+ * behaviour of `bash`-driven Git outside Team Collaboration Mode.
+ *
+ * @param {{ actor?: unknown, canWriteGit?: unknown, isPathAllowed?: unknown, isProjectAllowed?: unknown }} [input] - resolver output.
+ * @returns {{ actor: string, botName: string, canWriteGit: boolean, isPathAllowed?: Function, isProjectAllowed?: Function }} normalized actor.
+ */
+export function normalizeActorRecord(input = {}) {
+  const actor = normalizeActor(input.actor);
+  const record = {
+    actor,
+    botName: botNameFor(actor),
+    canWriteGit: input.canWriteGit !== false,
+  };
+  if (typeof input.isPathAllowed === 'function') record.isPathAllowed = input.isPathAllowed;
+  if (typeof input.isProjectAllowed === 'function') {
+    record.isProjectAllowed = input.isProjectAllowed;
+  }
+  return record;
+}
+
+/**
+ * Add the automatic bot identity to an issue/merge-request payload.
+ *
+ * @param {Record<string, unknown>} body - API request body.
+ * @param {unknown} actor - actor to attribute, or empty to leave unattributed.
+ * @returns {Record<string, unknown>} a copy with `bot_name` when requested.
+ */
+export function withBotName(body, actor) {
+  const payload = { ...body };
+  if (actor === undefined || actor === null || actor === '') return payload;
+  const botName = typeof actor === 'string' && actor.startsWith(`${BOT_PREFIX}-`)
+    ? actor
+    : botNameFor(actor);
+  payload.bot_name = botName;
+  return payload;
+}
+
+/**
+ * The default actor used when no live team member can be resolved.
+ *
+ * @returns {ReturnType<typeof normalizeActorRecord>} default actor record.
+ */
+export function defaultActorRecord() {
+  return normalizeActorRecord({ actor: DEFAULT_AGENT_ACTOR });
+}

package/lib/commit-scope.js

@@ -0,0 +1,249 @@
+/**
+ * Per-seat staging ledger and scoped commits.
+ *
+ * Git has one index per working tree, so `git commit` commits whatever any
+ * seat staged there. In a shared checkout that makes one seat's commit depend
+ * on another seat's staging; the recorded incident named one path in the
+ * commit call and produced a commit with two files.
+ *
+ * This module keeps the truth per seat instead:
+ * - `stage` records the blob each seat put into the index;
+ * - `commit` builds a throwaway index from HEAD plus exactly those blobs and
+ *   commits that tree, so an unrelated staged file, or an edit made after the
+ *   seat staged, cannot enter the commit;
+ * - `unstage` forgets the path for that seat.
+ *
+ * The ledger lives next to the repository's Git directory, one JSON file per
+ * seat. It never touches the tracked tree, it survives a Host restart, and it
+ * needs no lock on the shared index: the only mutable step is the commit
+ * itself, which is serialised per repository.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { GitFoxError } from './gitfox-api.js';
+
+/** Ledger format version; a future reader may migrate older files. */
+const LEDGER_VERSION = 1;
+
+/** Directory under the Git directory that holds ledgers and the commit index. */
+const LEDGER_DIRECTORY = 'infinity-git';
+
+/** File name of the throwaway index a scoped commit is built in. */
+const COMMIT_INDEX = 'commit.index';
+
+/** Serialised commits, keyed by Git directory. */
+const commitQueues = new Map();
+
+/**
+ * @param {unknown} actor - actor id.
+ * @returns {string} file name safe for one seat's ledger.
+ */
+function ledgerFileName(actor) {
+  const text = typeof actor === 'string' ? actor.trim() : '';
+  return `${(text === '' ? 'agent' : text).replaceAll(/[^a-zA-Z0-9._-]+/g, '_')}.json`;
+}
+
+/**
+ * @param {string} gitDir - absolute Git directory.
+ * @param {unknown} actor - actor id.
+ * @returns {string} ledger path.
+ */
+function ledgerPath(gitDir, actor) {
+  return join(gitDir, LEDGER_DIRECTORY, 'staged', ledgerFileName(actor));
+}
+
+/**
+ * @param {unknown} entry - candidate ledger row.
+ * @returns {boolean} whether the row can drive a commit.
+ */
+function isUsableEntry(entry) {
+  if (entry === null || typeof entry !== 'object') return false;
+  if (typeof entry.path !== 'string' || entry.path === '') return false;
+  if (entry.deleted === true) return true;
+  return typeof entry.mode === 'string' && entry.mode !== ''
+    && typeof entry.sha === 'string' && entry.sha !== '';
+}
+
+/**
+ * Read one seat's staged entries.
+ *
+ * A missing or unreadable ledger is empty, not an error: the next `stage`
+ * writes a fresh one, and a commit with nothing in it reports that plainly.
+ *
+ * @param {string} gitDir - absolute Git directory.
+ * @param {unknown} actor - actor id.
+ * @returns {Promise<{ path: string, mode?: string, sha?: string, deleted?: boolean }[]>} entries.
+ */
+export async function readStagedEntries(gitDir, actor) {
+  let text;
+  try {
+    text = await readFile(ledgerPath(gitDir, actor), 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
+  return entries.filter(isUsableEntry).map((entry) => entry);
+}
+
+/**
+ * Replace one seat's ledger atomically; an empty ledger removes the file.
+ *
+ * @param {string} gitDir - absolute Git directory.
+ * @param {unknown} actor - actor id.
+ * @param {{ path: string, mode?: string, sha?: string, deleted?: boolean }[]} entries - entries to store.
+ * @returns {Promise<void>} written.
+ */
+async function writeStagedEntries(gitDir, actor, entries) {
+  const file = ledgerPath(gitDir, actor);
+  if (entries.length === 0) {
+    await rm(file, { force: true });
+    return;
+  }
+  await mkdir(dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  const body = { version: LEDGER_VERSION, updatedAt: new Date().toISOString(), entries };
+  await writeFile(temporary, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+  await rename(temporary, file);
+}
+
+/**
+ * Record (or replace) the entries one seat just staged.
+ *
+ * @param {string} gitDir - absolute Git directory.
+ * @param {unknown} actor - actor id.
+ * @param {{ path: string, mode?: string, sha?: string, deleted?: boolean }[]} entries - freshly staged entries.
+ * @returns {Promise<void>} recorded.
+ */
+export async function recordStagedEntries(gitDir, actor, entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return;
+  const byPath = new Map();
+  for (const entry of await readStagedEntries(gitDir, actor)) byPath.set(entry.path, entry);
+  for (const entry of entries) {
+    if (isUsableEntry(entry)) byPath.set(entry.path, entry);
+  }
+  const merged = [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+  await writeStagedEntries(gitDir, actor, merged);
+}
+
+/**
+ * Drop paths from one seat's ledger after `unstage` or a commit.
+ *
+ * @param {string} gitDir - absolute Git directory.
+ * @param {unknown} actor - actor id.
+ * @param {string[]} paths - repo-relative paths.
+ * @returns {Promise<void>} forgotten.
+ */
+export async function forgetStagedEntries(gitDir, actor, paths) {
+  const drop = new Set(Array.isArray(paths) ? paths : []);
+  if (drop.size === 0) return;
+  const kept = (await readStagedEntries(gitDir, actor)).filter((entry) => !drop.has(entry.path));
+  await writeStagedEntries(gitDir, actor, kept);
+}
+
+/**
+ * Run one task at a time for a key.
+ *
+ * Two seats committing at the same moment would otherwise read the same HEAD
+ * and race on the branch ref. Serialising the read-tree/commit pair keeps each
+ * commit based on the commit that landed before it.
+ *
+ * @template T
+ * @param {string} key - queue key.
+ * @param {() => Promise<T>} task - work to serialise.
+ * @returns {Promise<T>} task result.
+ */
+export function withCommitLock(key, task) {
+  const previous = commitQueues.get(key) ?? Promise.resolve();
+  const run = previous.then(task, task);
+  const tail = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  commitQueues.set(key, tail);
+  void tail.then(() => {
+    if (commitQueues.get(key) === tail) commitQueues.delete(key);
+  });
+  return run;
+}
+
+/**
+ * Parse `git diff --cached --name-status -z` records.
+ *
+ * @param {string} raw - NUL-separated name/status records.
+ * @returns {{ path: string, status: string }[]} entries in index order.
+ */
+function parseNameStatus(raw) {
+  const tokens = raw.split('\0').filter((token) => token !== '');
+  const entries = [];
+  for (let index = 0; index + 1 < tokens.length; index += 2) {
+    entries.push({ status: tokens[index].slice(0, 1), path: tokens[index + 1] });
+  }
+  return entries;
+}
+
+/**
+ * Commit exactly the recorded entries.
+ *
+ * The throwaway index starts as HEAD's tree, gets the recorded blobs (or their
+ * removal), and is committed. A file another seat staged stays out because it
+ * is not in this index; an edit made after staging stays out because the
+ * recorded blob is committed instead of the worktree file.
+ *
+ * @param {object} options - commit inputs.
+ * @param {(args: string[], env?: Record<string, string>) => Promise<{ stdout: string, stderr: string }>} options.runGit - Git runner bound to the repository.
+ * @param {string} options.gitDir - absolute Git directory.
+ * @param {string | null} options.head - current HEAD, or null before the first commit.
+ * @param {{ path: string, mode?: string, sha?: string, deleted?: boolean }[]} options.entries - entries to commit.
+ * @param {string} options.message - commit message.
+ * @param {{ name: string, email: string }} options.identity - author/committer identity.
+ * @returns {Promise<{ commit: string, files: string[] }>} created commit and the paths it contains.
+ */
+export async function commitStagedEntries({ runGit, gitDir, head, entries, message, identity }) {
+  const directory = join(gitDir, LEDGER_DIRECTORY);
+  const indexPath = join(directory, COMMIT_INDEX);
+  await mkdir(directory, { recursive: true });
+  await rm(indexPath, { force: true });
+  const env = { GIT_INDEX_FILE: indexPath };
+  try {
+    await runGit(head === null ? ['read-tree', '--empty'] : ['read-tree', head], env);
+    for (const entry of entries) {
+      const staged = entry.deleted === true
+        ? ['update-index', '--force-remove', '--', entry.path]
+        : ['update-index', '--add', '--cacheinfo', entry.mode, entry.sha, entry.path];
+      await runGit(staged, env);
+    }
+    const changes = head === null
+      ? entries.map((entry) => ({ path: entry.path, status: 'A' }))
+      : parseNameStatus(
+        (await runGit(['diff', '--cached', '--name-status', '-z', '--no-renames'], env)).stdout,
+      );
+    if (changes.length === 0) {
+      throw new GitFoxError(
+        'the staged paths already match the newest commit; unstage them or stage a change',
+        { code: 'nothing-staged' },
+      );
+    }
+    await runGit(
+      ['-c', 'commit.gpgsign=false', 'commit', '--no-verify', '--quiet', '-m', message],
+      {
+        ...env,
+        GIT_AUTHOR_NAME: identity.name,
+        GIT_AUTHOR_EMAIL: identity.email,
+        GIT_COMMITTER_NAME: identity.name,
+        GIT_COMMITTER_EMAIL: identity.email,
+      },
+    );
+    const { stdout } = await runGit(['rev-parse', 'HEAD'], env);
+    return { commit: stdout.trim(), files: changes.map((change) => change.path) };
+  } finally {
+    await rm(indexPath, { force: true });
+  }
+}

package/lib/git-exec.js

@@ -0,0 +1,135 @@
+/**
+ * One audited Git process execution path.
+ *
+ * Every invocation is argument-array based (never a shell), has a timeout and
+ * an output budget, and maps failures to stable `GitFoxError` codes. The token
+ * is supplied through the child environment only for the push invocation; it
+ * never appears in argv or in an error message.
+ */
+import { execFile } from 'node:child_process';
+
+import { GitFoxError } from './gitfox-api.js';
+
+/** Default budget for local repository operations. */
+export const DEFAULT_GIT_TIMEOUT_MS = 120_000;
+
+/** Push may need to transfer a large pack. */
+export const PUSH_TIMEOUT_MS = 300_000;
+
+/** Upper bound on captured stdout/stderr per invocation. */
+const MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Resolve the Git executable without a shell lookup.
+ *
+ * @returns {string} executable path or `git` from PATH.
+ */
+function gitBinary() {
+  const override = process.env.INFINITY_GIT_BIN;
+  return typeof override === 'string' && override.trim() !== '' ? override.trim() : 'git';
+}
+
+/**
+ * @param {string | Buffer | undefined} value - captured stream content.
+ * @param {number} [limit] - maximum characters retained.
+ * @returns {string} text for a model/error message.
+ */
+function textOf(value, limit = 4000) {
+  let text = '';
+  if (typeof value === 'string') text = value;
+  else if (Buffer.isBuffer(value)) text = value.toString('utf8');
+  return text.trim().slice(0, limit);
+}
+
+/**
+ * @param {any} error - failed child process result.
+ * @param {AbortSignal | undefined} signal - caller cancellation.
+ * @returns {boolean} whether the operation was cancelled.
+ */
+function isAbort(error, signal) {
+  return signal?.aborted === true || error?.name === 'AbortError';
+}
+
+/**
+ * @param {any} error - failed child process result.
+ * @returns {boolean} whether the executable is missing.
+ */
+function isMissingBinary(error) {
+  return error?.code === 'ENOENT';
+}
+
+/**
+ * @param {any} error - failed child process result.
+ * @returns {boolean} whether the child exceeded its budget.
+ */
+function isTimeout(error) {
+  return error?.killed === true || error?.code === 'ETIMEDOUT';
+}
+
+/**
+ * Map a Node child-process failure onto a stable GitFoxError.
+ *
+ * @param {any} error - execFile failure.
+ * @param {AbortSignal | undefined} signal - caller cancellation.
+ * @param {string} stderr - captured standard error, which the error object may omit.
+ * @returns {GitFoxError} mapped error.
+ */
+function mapExecFailure(error, signal, stderr = '') {
+  if (isAbort(error, signal)) {
+    return new GitFoxError('git operation was cancelled', { status: 499, code: 'git-aborted' });
+  }
+  if (isMissingBinary(error)) {
+    return new GitFoxError('git is not installed or not on PATH', {
+      status: 503,
+      code: 'git-unavailable',
+    });
+  }
+  if (isTimeout(error)) {
+    return new GitFoxError('git operation timed out', { status: 504, code: 'git-timeout' });
+  }
+  const detail = textOf(stderr) || textOf(error?.stderr) || textOf(error?.stdout) || textOf(error?.message);
+  return new GitFoxError(detail === '' ? 'git failed' : `git failed: ${detail}`, {
+    status: 400,
+    code: 'git-failed',
+  });
+}
+
+/**
+ * Run one Git command in a fixed working directory.
+ *
+ * @param {{ args: string[], cwd: string, env?: Record<string, string>, signal?: AbortSignal, timeoutMs?: number, execFileImpl?: typeof execFile }} options - invocation.
+ * @returns {Promise<{ stdout: string, stderr: string }>} captured output.
+ * @throws {GitFoxError} when Git cannot be started, times out or exits non-zero.
+ */
+export function runGit(options) {
+  const {
+    args,
+    cwd,
+    env = {},
+    signal,
+    timeoutMs = DEFAULT_GIT_TIMEOUT_MS,
+    execFileImpl = execFile,
+  } = options;
+  return new Promise((resolve, reject) => {
+    execFileImpl(
+      gitBinary(),
+      args,
+      {
+        cwd,
+        env: { ...process.env, ...env },
+        encoding: 'utf8',
+        maxBuffer: MAX_BUFFER_BYTES,
+        timeout: timeoutMs,
+        windowsHide: true,
+        signal,
+      },
+      (error, stdout, stderr) => {
+        if (error !== null && error !== undefined) {
+          reject(mapExecFailure(error, signal, stderr));
+          return;
+        }
+        resolve({ stdout, stderr });
+      },
+    );
+  });
+}

package/lib/git-parse.js

@@ -0,0 +1,176 @@
+/**
+ * Pure parsers and validators for the local Git tool.
+ *
+ * Kept free of child-process and credential code so the rules can be tested
+ * without a repository or a GitFox connection.
+ */
+import { GitFoxError } from './gitfox-api.js';
+
+/** Maximum accepted branch name length (Git's own practical limit is looser). */
+const MAX_BRANCH_LENGTH = 200;
+
+/** Characters Git rejects in a branch name. */
+const INVALID_BRANCH = /[~^:?*[\\]/;
+
+/**
+ * Parse `git status --porcelain=v1 -z` output.
+ *
+ * A rename/copy record is followed by the original path, so the parser must
+ * consume two NUL-terminated records for one entry.
+ *
+ * @param {string} raw - NUL-separated porcelain output.
+ * @returns {Array<{ status: string, path: string, from?: string }>} entries in Git order.
+ */
+export function parsePorcelainZ(raw) {
+  const records = raw.split('\0');
+  const entries = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    if (record === '' || record.length < 4) continue;
+    const status = record.slice(0, 2);
+    const path = record.slice(3);
+    /** @type {{ status: string, path: string, from?: string }} */
+    const entry = { status, path };
+    if (status.includes('R') || status.includes('C')) {
+      index += 1;
+      const from = records[index];
+      if (from !== undefined && from !== '') entry.from = from;
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Parse `git log` output produced with the `LOG_FORMAT` placeholders.
+ *
+ * @param {string} raw - record-separated log output.
+ * @returns {Array<{ sha: string, author: string, email: string, date: string, subject: string }>} commits.
+ */
+export function parseLogRecords(raw) {
+  return raw
+    .split('\x1e')
+    .map((record) => record.trimStart())
+    .filter((record) => record !== '')
+    .map((record) => {
+      const [sha, author, email, date, subject = ''] = record.split('\x1f');
+      return { sha, author, email, date, subject };
+    })
+    .filter((commit) => typeof commit.sha === 'string' && commit.sha !== '');
+}
+
+/** The pretty format shared by the service and its tests. */
+export const LOG_FORMAT = '%H%x1f%an%x1f%ae%x1f%at%x1f%s%x1e';
+
+/**
+ * Validate one branch name before it reaches a Git refspec.
+ *
+ * The check is intentionally conservative: it also rejects Git pathspec/refspec
+ * magic (`:`, `@{`, `..`, a leading `-`) so a branch value can never become an
+ * option or address another ref.
+ *
+ * @param {unknown} value - user-supplied branch.
+ * @returns {string} trimmed branch name.
+ * @throws {GitFoxError} when the name is missing or unsafe.
+ */
+export function validateBranchName(value) {
+  const branch = typeof value === 'string' ? value.trim() : '';
+  const hasControl = [...branch].some((character) => character.charCodeAt(0) <= 0x20);
+  const invalid =
+    branch === '' ||
+    hasControl ||
+    branch.length > MAX_BRANCH_LENGTH ||
+    branch === 'HEAD' ||
+    branch.startsWith('-') ||
+    branch.startsWith('/') ||
+    branch.endsWith('/') ||
+    branch.endsWith('.') ||
+    branch.endsWith('.lock') ||
+    branch.includes('..') ||
+    branch.includes('//') ||
+    branch.includes('@{') ||
+    INVALID_BRANCH.test(branch);
+  if (invalid) {
+    throw new GitFoxError(`invalid branch name "${String(value)}"`, { code: 'invalid-branch' });
+  }
+  return branch;
+}
+
+/**
+ * Normalize a workspace-relative path accepted by `stage`/`commit`.
+ *
+ * Rejects absolute paths, traversal, NUL/newline injection, `.git` internals and
+ * Git pathspec magic. Every path is passed after `--`, but rejecting magic here
+ * keeps one malicious path from addressing files outside the declared scope.
+ *
+ * @param {unknown} value - user-supplied path.
+ * @returns {string} normalized forward-slash path.
+ * @throws {GitFoxError} when the path is not a safe relative path.
+ */
+export function normalizeRepoPath(value) {
+  if (typeof value !== 'string') {
+    throw new GitFoxError('path must be a string', { code: 'invalid-path' });
+  }
+  let text = value.trim().replaceAll('\\', '/');
+  while (text.startsWith('./')) text = text.slice(2);
+  text = text.replace(/\/+$/, '');
+  const invalid =
+    text === '' ||
+    text.startsWith('/') ||
+    text.startsWith(':') ||
+    text.includes('\0') ||
+    text.includes('\n') ||
+    text.includes('\r') ||
+    /^[A-Za-z]:\//.test(text);
+  const segments = text.split('/');
+  const unsafe =
+    invalid ||
+    segments.includes('..') ||
+    segments.includes('.') ||
+    segments.includes('.git') ||
+    segments.includes('');
+  if (unsafe) {
+    throw new GitFoxError(`invalid repository path "${value}"`, { code: 'invalid-path' });
+  }
+  return text;
+}
+
+/**
+ * Normalize and de-duplicate a list of repository paths.
+ *
+ * @param {unknown} value - `paths` tool argument.
+ * @param {{ required?: boolean }} [options] - whether an empty list is an error.
+ * @returns {string[]} normalized unique paths.
+ * @throws {GitFoxError} when required and absent/empty.
+ */
+export function normalizeRepoPaths(value, options = {}) {
+  if (value === undefined || value === null) {
+    if (options.required === true) {
+      throw new GitFoxError('paths are required for this action', { code: 'invalid-arguments' });
+    }
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new GitFoxError('paths must be an array of strings', { code: 'invalid-arguments' });
+  }
+  const paths = [...new Set(value.map((path) => normalizeRepoPath(path)))];
+  if (paths.length === 0 && options.required === true) {
+    throw new GitFoxError('paths must not be empty', { code: 'invalid-arguments' });
+  }
+  return paths;
+}
+
+/**
+ * Build the tokenless Git HTTP remote URL of one GitFox project.
+ *
+ * The namespace/name pair comes from `parseProject`, so a caller cannot smuggle
+ * a host or a path traversal into the URL.
+ *
+ * @param {string} baseUrl - normalized GitFox base URL.
+ * @param {{ namespace: string, name: string }} project - decoded project parts.
+ * @returns {string} HTTPS Git remote URL.
+ */
+export function projectRemoteUrl(baseUrl, project) {
+  const root = baseUrl.replace(/\/+$/, '');
+  return `${root}/${encodeURIComponent(project.namespace)}/${encodeURIComponent(project.name)}.git`;
+}