@mnemonik/shared 7.97.2 → 7.98.1

package/src/repositoryFingerprint.ts

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto';
+import { domainToASCII } from 'node:url';
+
+/** Only this hash/version pair may be sent to or stored by the server. */
+export interface RepositoryFingerprint {
+  algorithmVersion: 1;
+  hash: string;
+}
+export type RemoteRejectionReason =
+  | 'invalid_remote'
+  | 'unsupported_transport'
+  | 'local_remote'
+  | 'scp_unreviewed_remote'
+  | 'https_userinfo'
+  | 'ssh_password'
+  | 'ssh_user_required'
+  | 'invalid_ssh_user'
+  | 'invalid_host'
+  | 'invalid_port'
+  | 'invalid_encoding'
+  | 'escaped_separator'
+  | 'control_character'
+  | 'backslash'
+  | 'empty_segment'
+  | 'dot_segment';
+export type RemoteResult =
+  | (RepositoryFingerprint & { canonical: string })
+  | { status: 'rejected'; reason: RemoteRejectionReason };
+
+interface ParsedRemote {
+  transport: 'https' | 'ssh';
+  host: string;
+  user: string;
+  port: string;
+  path: string;
+}
+export interface RepositoryProviderRule {
+  readonly name: string;
+  readonly host: string;
+  readonly sshUser: string;
+  readonly removeTerminalDotGit: boolean;
+}
+/** Registry changes require review and golden cases; changed v1 outputs require v2. */
+export const REPOSITORY_PROVIDER_RULES: readonly RepositoryProviderRule[] = Object.freeze([
+  Object.freeze({ name: 'github', host: 'github.com', sshUser: 'git', removeTerminalDotGit: true }),
+]);
+const controls = /\p{Cc}/u;
+const reject = (reason: RemoteRejectionReason): RemoteResult => ({ status: 'rejected', reason });
+const encodeSegment = (segment: string): string =>
+  encodeURIComponent(segment).replace(
+    /[!'()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+
+/** Parse the raw path ourselves: WHATWG URL would silently resolve dot segments. */
+export function canonicalizeRemote(
+  url: string,
+  {
+    providerRules = REPOSITORY_PROVIDER_RULES,
+  }: { providerRules?: readonly RepositoryProviderRule[] } = {}
+): RemoteResult {
+  if (controls.test(url)) return reject('control_character');
+  if (url.includes('\\')) return reject('backslash');
+  if (/^file:/i.test(url)) return reject('local_remote');
+  const input = url.split(/[?#]/, 1)[0] ?? '';
+  const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(input);
+  let transport: 'https' | 'ssh';
+  let authority: string;
+  let path: string;
+  if (scheme) {
+    const protocol = (scheme[1] ?? '').toLowerCase();
+    if (protocol !== 'https' && protocol !== 'ssh') return reject('unsupported_transport');
+    transport = protocol;
+    const parts = /^([^/]*)(?:\/(.*))?$/.exec(input.slice(scheme[0].length));
+    if (!parts) return reject('invalid_remote');
+    authority = parts[1] ?? '';
+    path = parts[2] ?? '';
+  } else {
+    const scp = /^((?:[^@/:]+@)?(?:\[[^\]]+\]|[^/:]+)):(.*)$/.exec(input);
+    if (!scp) return reject('invalid_remote');
+    transport = 'ssh';
+    authority = scp[1] ?? '';
+    path = scp[2] ?? '';
+  }
+  const at = authority.lastIndexOf('@');
+  let user = '';
+  if (at >= 0) {
+    if (transport === 'https') return reject('https_userinfo');
+    user = authority.slice(0, at);
+    if (user.includes(':')) return reject('ssh_password');
+    if (!/^[A-Za-z0-9._~!$&'()*+,;=-]+$/.test(user)) return reject('invalid_ssh_user');
+    authority = authority.slice(at + 1);
+  }
+  if (transport === 'ssh' && !user) return reject('ssh_user_required');
+  const hostPort = /^(\[[^\]]+\]|[^:[\]]+)(?::([0-9]+))?$/.exec(authority);
+  if (!hostPort) return reject(authority.includes(':') ? 'invalid_port' : 'invalid_host');
+  let host = hostPort[1] ?? '';
+  let port = hostPort[2] ?? '';
+  if (port && (Number(port) < 1 || Number(port) > 65535)) return reject('invalid_port');
+  if (port) port = String(Number(port));
+  if (port === (transport === 'https' ? '443' : '22')) port = '';
+  if (/[\s%/@?#]/u.test(host)) return reject('invalid_host');
+  try {
+    // Node's WHATWG host parser supplies UTS 46 ToASCII and IPv6 zero compression.
+    host = host.startsWith('[')
+      ? new URL(`https://${host}/`).hostname
+      : domainToASCII(host).toLowerCase();
+    if (!host) return reject('invalid_host');
+  } catch {
+    return reject('invalid_host');
+  }
+  const rule = providerRules.find(
+    (rule) => rule.host === host && !port && (transport === 'https' || user === rule.sshUser)
+  );
+  // Generic scp paths are home-relative; ssh:// paths are absolute. Only a
+  // reviewed provider rule can establish that both name the same repository.
+  if (!scheme && !rule) return reject('scp_unreviewed_remote');
+  if (!scheme && path.startsWith('/')) path = path.slice(1);
+  if (path.endsWith('/')) path = path.slice(0, -1);
+  const segments: string[] = [];
+  for (const raw of path.split('/')) {
+    if (/%(?:2f|5c)/i.test(raw)) return reject('escaped_separator');
+    let segment: string;
+    try {
+      segment = decodeURIComponent(raw).normalize('NFC');
+    } catch {
+      return reject('invalid_encoding');
+    }
+    if (controls.test(segment)) return reject('control_character');
+    if (segment.includes('\\')) return reject('backslash');
+    if (!segment) return reject('empty_segment');
+    if (segment === '.' || segment === '..') return reject('dot_segment');
+    try {
+      segments.push(encodeSegment(segment));
+    } catch {
+      return reject('invalid_encoding');
+    }
+  }
+  const parsed: ParsedRemote = { transport, host, user, port, path: segments.join('/') };
+  if (rule?.removeTerminalDotGit) {
+    parsed.path = parsed.path.replace(/\.git$/, '');
+    const last = parsed.path.split('/').at(-1);
+    if (!last) return reject('empty_segment');
+    if (last === '.' || last === '..') return reject('dot_segment');
+  }
+  const prefix = rule
+    ? `${rule.name}:${host}`
+    : `${transport}:${transport === 'ssh' ? `${user}@` : ''}${host}${port ? `:${port}` : ''}`;
+  const canonical = `repo-v1:${prefix}/${parsed.path}`;
+  return {
+    canonical,
+    hash: createHash('sha256').update(canonical, 'utf8').digest('hex'),
+    algorithmVersion: 1,
+  };
+}
+
+export interface RepositoryRemote {
+  name: string;
+  fetchUrls: readonly string[];
+  pushUrls?: readonly string[];
+}
+export type RemoteSelection =
+  | {
+      status: 'fingerprint';
+      remote: string;
+      fingerprint: RepositoryFingerprint & { canonical: string };
+    }
+  | { status: 'none'; reason: 'no_remote' | 'no_fetch_url' }
+  | { status: 'rejected'; remote: string; reason: RemoteRejectionReason }
+  | { status: 'choice_required'; reason: 'multiple_remotes' | 'different_urls'; remotes: string[] };
+
+/** Choice results carry names, never credential-bearing URLs. No URL is guessed. */
+export function selectRemote(remotes: readonly RepositoryRemote[]): RemoteSelection {
+  if (!remotes.length) return { status: 'none', reason: 'no_remote' };
+  const origins = remotes.filter((remote) => remote.name === 'origin');
+  const selected =
+    origins.length === 1 ? origins[0] : remotes.length === 1 ? remotes[0] : undefined;
+  if (!selected)
+    return {
+      status: 'choice_required',
+      reason: 'multiple_remotes',
+      remotes: remotes.map((r) => r.name),
+    };
+  if (!selected.fetchUrls.length) return { status: 'none', reason: 'no_fetch_url' };
+  const results = [...selected.fetchUrls, ...(selected.pushUrls ?? [])].map((url) =>
+    canonicalizeRemote(url)
+  );
+  const first = results[0];
+  if (!first) return { status: 'none', reason: 'no_fetch_url' };
+  if (results.length === 1 && 'reason' in first)
+    return { status: 'rejected', remote: selected.name, reason: first.reason };
+  if (
+    'reason' in first ||
+    results.some((result) => 'reason' in result || result.canonical !== first.canonical)
+  ) {
+    return { status: 'choice_required', reason: 'different_urls', remotes: [selected.name] };
+  }
+  return { status: 'fingerprint', remote: selected.name, fingerprint: first };
+}

package/src/repositoryRoot.ts

@@ -0,0 +1,261 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { readIdentityFile, type ProjectIdentityFile } from './projectIdentityFile.js';
+
+export interface RepositoryBoundary {
+  path: string;
+  kind: 'directory' | 'file';
+}
+
+export type RepositoryRootResult =
+  | {
+      kind: 'git';
+      root: string;
+      commonDir: string;
+      isLinkedWorktree: boolean;
+      nested: RepositoryBoundary[];
+    }
+  | { kind: 'plain'; root: string }
+  | { kind: 'git_unavailable'; detail: string };
+
+type ResolvedRepository = Exclude<RepositoryRootResult, { kind: 'git_unavailable' }>;
+
+type ResolvedBase = {
+  root: string;
+  repository: ResolvedRepository;
+  nested: RepositoryBoundary[];
+};
+
+export type ProjectIdentityResolution =
+  | (ResolvedBase & { kind: 'ok'; identity: ProjectIdentityFile })
+  | (ResolvedBase & { kind: 'absent' })
+  | (ResolvedBase & { kind: 'unknown_version'; version: unknown; path: string })
+  | (ResolvedBase & { kind: 'malformed'; detail: string; path: string })
+  | (ResolvedBase & { kind: 'nested'; parentIdentity?: ProjectIdentityFile })
+  | (ResolvedBase & {
+      kind: 'conflict';
+      rootIdentity: ProjectIdentityFile;
+      nestedIdentity: ProjectIdentityFile;
+    })
+  | { kind: 'git_unavailable'; detail: string };
+
+const GIT_TIMEOUT_MS = 2_000;
+const GIT_ENV_KEYS = [
+  'PATH',
+  'HOME',
+  'LANG',
+  'LC_ALL',
+  'SYSTEMROOT',
+  'TEMP',
+  'TMP',
+  'USERPROFILE',
+] as const;
+
+function gitEnvironment(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of GIT_ENV_KEYS) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  env.LC_ALL = 'C';
+  return env;
+}
+
+function runGit(cwd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolvePromise, reject) => {
+    execFile(
+      'git',
+      args,
+      { cwd, timeout: GIT_TIMEOUT_MS, encoding: 'utf8', env: gitEnvironment() },
+      (error, stdout, stderr) => {
+        if (error) reject(Object.assign(error, { stdout, stderr }));
+        else resolvePromise({ stdout, stderr });
+      }
+    );
+  });
+}
+
+async function boundaryAt(path: string): Promise<RepositoryBoundary | undefined> {
+  try {
+    const stat = await lstat(join(path, '.git'));
+    if (stat.isDirectory()) return { path, kind: 'directory' };
+    if (stat.isFile()) return { path, kind: 'file' };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT' && code !== 'ENOTDIR') throw error;
+  }
+  return undefined;
+}
+
+async function confirmedBoundaryAt(path: string): Promise<RepositoryBoundary | undefined> {
+  const boundary = await boundaryAt(path);
+  if (!boundary) return undefined;
+  try {
+    const { stdout } = await runGit(path, ['rev-parse', '--git-dir']);
+    return stdout.trim() ? boundary : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function boundariesBetween(cwd: string, root: string): Promise<RepositoryBoundary[]> {
+  const boundaries: RepositoryBoundary[] = [];
+  let directory = cwd;
+  while (directory !== root) {
+    const boundary = await confirmedBoundaryAt(directory);
+    if (boundary) boundaries.push(boundary);
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return boundaries;
+}
+
+async function containingRepository(root: string): Promise<RepositoryBoundary | undefined> {
+  let directory = dirname(root);
+  while (true) {
+    const boundary = await confirmedBoundaryAt(directory);
+    if (boundary) return boundary;
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+async function canonicalBoundaryRoot(boundary: RepositoryBoundary): Promise<string> {
+  if (boundary.kind === 'directory') return boundary.path;
+  const pointer = /^gitdir:\s*(.+)\s*$/im.exec(
+    await readFile(join(boundary.path, '.git'), 'utf8')
+  )?.[1];
+  if (!pointer) return boundary.path;
+  const gitDir = resolve(boundary.path, pointer);
+  try {
+    const commonDir = resolve(gitDir, (await readFile(join(gitDir, 'commondir'), 'utf8')).trim());
+    return dirname(commonDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return boundary.path;
+    throw error;
+  }
+}
+
+export async function resolveRepositoryRoot(cwd: string): Promise<RepositoryRootResult> {
+  const absoluteCwd = resolve(cwd);
+  try {
+    const { stdout } = await runGit(absoluteCwd, [
+      'rev-parse',
+      '--show-toplevel',
+      '--git-common-dir',
+    ]);
+    const [rootLine, commonLine, ...extra] = stdout.trim().split(/\r?\n/);
+    if (!rootLine || !commonLine || extra.length) {
+      return { kind: 'git_unavailable', detail: 'git rev-parse returned an unexpected response' };
+    }
+    const root = resolve(rootLine);
+    const commonDir = resolve(root, commonLine);
+    const isLinkedWorktree = commonDir !== join(root, '.git');
+    const nested = await boundariesBetween(absoluteCwd, root);
+    if (!isLinkedWorktree && (await containingRepository(root))) {
+      const boundary = await boundaryAt(root);
+      if (boundary) nested.push(boundary);
+    }
+    return {
+      kind: 'git',
+      root,
+      commonDir,
+      isLinkedWorktree,
+      nested,
+    };
+  } catch (error) {
+    const failure = error as Error & { code?: string | number; stderr?: string };
+    if (failure.code === 128 && /not a git repository/i.test(failure.stderr ?? failure.message)) {
+      return { kind: 'plain', root: absoluteCwd };
+    }
+    return { kind: 'git_unavailable', detail: failure.message };
+  }
+}
+
+async function readPlainIdentity(start: string): Promise<{
+  root: string;
+  result: Awaited<ReturnType<typeof readIdentityFile>>;
+}> {
+  const home = resolve(homedir());
+  let directory = start;
+  while (true) {
+    const result = await readIdentityFile(directory);
+    if (result.kind !== 'absent') return { root: directory, result };
+    if (directory === home) break;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return { root: start, result: { kind: 'absent' } };
+}
+
+function withBase(
+  repository: ResolvedRepository,
+  root: string,
+  nested: RepositoryBoundary[]
+): ResolvedBase {
+  return { root, repository, nested };
+}
+
+export async function resolveProjectIdentity(
+  cwd: string,
+  options: { allowNestedInherit?: boolean } = {}
+): Promise<ProjectIdentityResolution> {
+  const repository = await resolveRepositoryRoot(cwd);
+  if (repository.kind === 'git_unavailable') return repository;
+
+  if (repository.kind === 'plain') {
+    const { root, result } = await readPlainIdentity(repository.root);
+    const base = withBase(repository, root, []);
+    if (result.kind === 'ok') return { ...base, ...result };
+    if (result.kind === 'unknown_version') return { ...base, ...result, path: root };
+    if (result.kind === 'malformed') return { ...base, ...result, path: root };
+    return { ...base, kind: 'absent' };
+  }
+
+  const ownRoot = repository.isLinkedWorktree ? dirname(repository.commonDir) : repository.root;
+  const outer = repository.isLinkedWorktree
+    ? undefined
+    : await containingRepository(repository.root);
+  const own = await readIdentityFile(ownRoot);
+  if (!outer) {
+    const base = withBase(repository, ownRoot, repository.nested);
+    if (own.kind === 'ok') return { ...base, ...own };
+    if (own.kind === 'unknown_version') return { ...base, ...own, path: ownRoot };
+    if (own.kind === 'malformed') return { ...base, ...own, path: ownRoot };
+    return { ...base, kind: 'absent' };
+  }
+
+  const nested = repository.nested;
+  const parentRoot = await canonicalBoundaryRoot(outer);
+  const parent = await readIdentityFile(parentRoot);
+  const base = withBase(repository, parentRoot, nested);
+
+  if (own.kind === 'unknown_version') return { ...base, ...own, path: ownRoot };
+  if (own.kind === 'malformed') return { ...base, ...own, path: ownRoot };
+  if (parent.kind === 'unknown_version') return { ...base, ...parent, path: parentRoot };
+  if (parent.kind === 'malformed') return { ...base, ...parent, path: parentRoot };
+  if (own.kind === 'ok' && parent.kind === 'ok') {
+    return {
+      ...base,
+      kind: 'conflict',
+      rootIdentity: parent.identity,
+      nestedIdentity: own.identity,
+    };
+  }
+  if (own.kind === 'ok') {
+    return { ...withBase(repository, ownRoot, nested), kind: 'ok', identity: own.identity };
+  }
+  if (!options.allowNestedInherit) {
+    return {
+      ...base,
+      kind: 'nested',
+      ...(parent.kind === 'ok' ? { parentIdentity: parent.identity } : {}),
+    };
+  }
+  if (parent.kind === 'ok') return { ...base, kind: 'ok', identity: parent.identity };
+  return { ...base, kind: 'absent' };
+}