@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/sessrumnir/src/main/git-conveyor.ts

@@ -0,0 +1,338 @@
+import { access, realpath } from 'fs/promises'
+import { isAbsolute, relative, resolve, sep } from 'path'
+import { spawn } from 'child_process'
+import { inspectGitRepository, isMissingRepositoryError, runGit } from './git-worktree'
+import type {
+  GitConveyorCommitOptions,
+  GitConveyorPullRequestOptions,
+  GitConveyorPullRequestResult,
+  GitConveyorStatus,
+} from '../shared/ipc-contracts'
+import { t } from '../shared/i18n'
+
+const COMMAND_TIMEOUT_MS = 30_000
+const MAX_COMMIT_MESSAGE_LENGTH = 200
+
+/** Status of a workspace folder that Git does not track. */
+const NOT_A_REPOSITORY_STATUS: GitConveyorStatus = Object.freeze({
+  branch: null,
+  head: '',
+  lastCommitMessage: null,
+  dirtyFiles: 0,
+  ahead: 0,
+  behind: 0,
+  hasUpstream: false,
+  pushRemote: null,
+  upstreamBranch: null,
+  baseBranch: null,
+  remoteUrl: null,
+})
+
+const GIT_OPERATION_MARKERS = [
+  ['MERGE_HEAD', 'merge'],
+  ['CHERRY_PICK_HEAD', 'cherry-pick'],
+  ['REVERT_HEAD', 'revert'],
+  ['rebase-merge', 'rebase'],
+  ['rebase-apply', 'rebase'],
+  ['BISECT_LOG', 'bisect'],
+] as const
+
+interface UpstreamConfig {
+  remote: string
+  branch: string
+}
+
+export function countPorcelainFiles(status: string): number {
+  return status.split(/\r?\n/).filter((line) => line.trim().length > 0).length
+}
+
+export function parseAheadBehind(value: string | null): { ahead: number; behind: number } {
+  if (!value) return { ahead: 0, behind: 0 }
+  const [behind, ahead] = value.trim().split(/\s+/).map(Number)
+  return {
+    ahead: Number.isFinite(ahead) ? ahead : 0,
+    behind: Number.isFinite(behind) ? behind : 0,
+  }
+}
+
+export function extractUrl(output: string): string | null {
+  return output.match(/https?:\/\/[^\s]+/)?.[0] ?? null
+}
+
+export function extractGitHubPullRequestUrl(value: string): string | null {
+  return value.match(/https?:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+/i)?.[0] ?? null
+}
+
+export async function resolvePullRequestHeadBranch(cwd: string, url: string): Promise<string | null> {
+  const output = await runCommand('gh', ['pr', 'view', url, '--json', 'headRefName'], cwd)
+  try {
+    const value = JSON.parse(output) as { headRefName?: unknown }
+    return typeof value.headRefName === 'string' && value.headRefName.trim()
+      ? value.headRefName.trim()
+      : null
+  } catch {
+    return null
+  }
+}
+
+export function githubRepoFromRemote(remote: string | null): string | null {
+  if (!remote) return null
+  const match = remote.trim().replace(/\.git$/, '').match(/github\.com[:/]([^/]+\/[^/]+)$/i)
+  return match?.[1] ?? null
+}
+
+function runCommand(file: string, args: readonly string[], cwd: string): Promise<string> {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(file, [...args], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    })
+    let stdout = ''
+    let stderr = ''
+    const command = `${file} ${args.join(' ')}`
+    const timer = setTimeout(() => {
+      child.kill()
+      reject(new Error(t('errors.git.subprocessTimedOut', { command })))
+    }, COMMAND_TIMEOUT_MS)
+    child.stdout?.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8') })
+    child.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') })
+    child.once('error', (error) => {
+      clearTimeout(timer)
+      reject(error)
+    })
+    child.once('close', (code) => {
+      clearTimeout(timer)
+      const output = (stdout || stderr).trim()
+      if (code === 0) resolvePromise(output)
+      else reject(new Error(
+        output
+          ? t('errors.git.commandFailedWithDetail', { command, detail: output })
+          : t('errors.git.commandFailed', { command })
+      ))
+    })
+  })
+}
+
+async function gitConfig(cwd: string, key: string): Promise<string | null> {
+  return runGit(['config', '--get', key], cwd)
+    .then((result) => result.stdout.trim() || null)
+    .catch(() => null)
+}
+
+async function branchRemote(cwd: string, branch: string): Promise<string | null> {
+  return gitConfig(cwd, `branch.${branch}.remote`)
+}
+
+async function resolveUpstream(cwd: string, branch: string): Promise<UpstreamConfig | null> {
+  const [remote, merge] = await Promise.all([
+    branchRemote(cwd, branch),
+    gitConfig(cwd, `branch.${branch}.merge`),
+  ])
+  if (!remote || !merge?.startsWith('refs/heads/')) return null
+  return { remote, branch: merge.slice('refs/heads/'.length) }
+}
+
+async function defaultBranchForRemote(cwd: string, remote: string | null): Promise<string | null> {
+  if (!remote || remote === '.') return null
+  const ref = await runGit(['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`], cwd)
+    .then((result) => result.stdout.trim())
+    .catch(() => '')
+  const prefix = `${remote}/`
+  return ref.startsWith(prefix) ? ref.slice(prefix.length) : null
+}
+
+async function activeGitOperation(cwd: string): Promise<string | null> {
+  const markers = await Promise.all(
+    GIT_OPERATION_MARKERS.map(async ([marker, label]) => {
+      const gitPath = await runGit(['rev-parse', '--git-path', marker], cwd)
+        .then((result) => result.stdout.trim())
+        .catch(() => '')
+      if (!gitPath) return null
+      try {
+        await access(resolve(cwd, gitPath))
+        return label
+      } catch {
+        return null
+      }
+    })
+  )
+  return markers.find((label) => label !== null) ?? null
+}
+
+function isPathWithin(base: string, candidate: string): boolean {
+  const relativePath = relative(resolve(base), resolve(base, candidate))
+  return relativePath === '' ||
+    (!isAbsolute(relativePath) && relativePath !== '..' && !relativePath.startsWith(`..${sep}`))
+}
+
+/**
+ * Absolute paths of every staged entry. `--relative` is deliberately not used:
+ * it drops the paths outside `cwd`, which is exactly the set the workspace
+ * guard has to see, so Git reports repository-root paths that are resolved
+ * against the worktree root here instead. Git prints that root with symlinks
+ * resolved, so the paths are physical and must be compared as such.
+ */
+async function stagedPaths(cwd: string): Promise<string[]> {
+  const [worktreeRoot, output] = await Promise.all([
+    runGit(['rev-parse', '--show-toplevel'], cwd).then((result) => realpath(result.stdout.trim())),
+    runGit(['diff', '--cached', '--name-only', '-z'], cwd).then((result) => result.stdout),
+  ])
+  return output.split('\0').filter(Boolean).map((path) => resolve(worktreeRoot, path))
+}
+
+/**
+ * True when tracked files below `cwd` differ from the index. `git add --update`
+ * fails when its pathspec matches no tracked file at all, so auto-staging asks
+ * this first and can report the untracked-only case in its own words.
+ */
+async function hasUnstagedTrackedChanges(cwd: string): Promise<boolean> {
+  const result = await runGit(['diff', '--name-only', '-z', '--', '.'], cwd)
+  return result.stdout.split('\0').some((path) => path.length > 0)
+}
+
+/** Record the index as a tree object so a failed commit can restore it. */
+async function snapshotIndex(cwd: string): Promise<string> {
+  const result = await runGit(['write-tree'], cwd)
+  return result.stdout.trim()
+}
+
+export async function getGitConveyorStatus(cwd: string): Promise<GitConveyorStatus> {
+  // A workspace does not have to be a repository. Every other probe below
+  // already degrades to a null field, so report the same empty shape instead of
+  // pushing raw Git output into a header the renderer polls every few seconds.
+  // No branch and no dirty file keeps commit, push, and pull request disabled.
+  const repository = await inspectGitRepository(cwd).catch((error: unknown) => {
+    if (isMissingRepositoryError(error)) return null
+    throw error
+  })
+  if (!repository) return NOT_A_REPOSITORY_STATUS
+  const upstream = repository.branch ? await resolveUpstream(cwd, repository.branch) : null
+  const configuredRemote = repository.branch ? await branchRemote(cwd, repository.branch) : null
+  const pushRemote = upstream?.remote ?? configuredRemote ?? (await gitConfig(cwd, 'remote.origin.url') ? 'origin' : null)
+  const baseRemote = (await gitConfig(cwd, 'remote.upstream.url')) ? 'upstream' : upstream?.remote ?? null
+  const [lastCommitMessage, counts, remoteUrl, baseBranch] = await Promise.all([
+    runGit(['log', '-1', '--pretty=%s'], cwd).then((result) => result.stdout.trim()).catch(() => ''),
+    runGit(['rev-list', '--left-right', '--count', '@{upstream}...HEAD'], cwd).then((result) => result.stdout.trim()).catch(() => null),
+    runGit(['config', '--get', 'remote.origin.url'], cwd).then((result) => result.stdout.trim()).catch(() => ''),
+    defaultBranchForRemote(cwd, baseRemote),
+  ])
+  return {
+    branch: repository.branch,
+    head: repository.head,
+    lastCommitMessage: lastCommitMessage || null,
+    dirtyFiles: countPorcelainFiles(repository.status),
+    ...parseAheadBehind(counts),
+    hasUpstream: !!upstream,
+    pushRemote,
+    upstreamBranch: upstream?.branch ?? null,
+    baseBranch,
+    remoteUrl: remoteUrl || null,
+  }
+}
+
+export async function commitAll(cwd: string, options: GitConveyorCommitOptions): Promise<GitConveyorStatus> {
+  const message = options.message.trim()
+  if (!message) throw new Error(t('errors.git.commitMessageRequired'))
+  if (message.length > MAX_COMMIT_MESSAGE_LENGTH) {
+    throw new Error(t('errors.git.commitMessageTooLong', { max: MAX_COMMIT_MESSAGE_LENGTH }))
+  }
+  const repository = await inspectGitRepository(cwd)
+  if (!repository.branch) throw new Error(t('errors.git.detachedHeadCommit'))
+  const operation = await activeGitOperation(cwd)
+  if (operation) throw new Error(t('errors.git.operationInProgressCommit', { operation }))
+  if (!repository.status.trim()) throw new Error(t('errors.git.workingTreeClean'))
+
+  // Preserve an intentionally curated index. Only auto-stage when there is no
+  // staged content at all, and never allow staged paths outside the workspace
+  // to be swept into a commit opened from a monorepo subdirectory.
+  const staged = await stagedPaths(cwd)
+  // Both sides of the comparison must be physical paths: a workspace can be
+  // opened through a symlink while Git always reports the resolved worktree.
+  const workspaceRoot = await realpath(cwd)
+  const outsideWorkspace = staged.filter((path) => !isPathWithin(workspaceRoot, path))
+  if (outsideWorkspace.length > 0) {
+    throw new Error(t('errors.git.stagedOutsideWorkspace'))
+  }
+
+  // Auto-staging covers tracked modifications only. A stray secret, key, or
+  // build artefact sitting untracked in the workspace reaches a commit only
+  // after the user staged it deliberately. The Commit button counts untracked
+  // rows too, so say plainly when that leaves nothing to commit.
+  const autoStage = staged.length === 0
+  if (autoStage && !(await hasUnstagedTrackedChanges(cwd))) {
+    throw new Error(t('errors.git.noTrackedChanges'))
+  }
+  // The snapshot records the index as a tree, so a rejected commit restores
+  // exactly what was staged before. `git reset` would instead unstage the whole
+  // index: equivalent only while auto-staging is gated on an empty index, while
+  // the snapshot stays correct whatever that gate becomes.
+  const indexSnapshot = autoStage ? await snapshotIndex(cwd) : null
+  try {
+    if (autoStage) await runGit(['add', '--update', '--', '.'], cwd)
+    await runGit(['commit', '-m', message], cwd)
+  } catch (error) {
+    if (indexSnapshot) await runGit(['read-tree', indexSnapshot], cwd)
+    throw error
+  }
+  return getGitConveyorStatus(cwd)
+}
+
+export async function pushBranch(cwd: string): Promise<GitConveyorStatus> {
+  const repository = await inspectGitRepository(cwd)
+  if (!repository.branch) throw new Error(t('errors.git.detachedHeadPush'))
+  if (repository.status.trim()) throw new Error(t('errors.git.commitBeforePush'))
+  const operation = await activeGitOperation(cwd)
+  if (operation) throw new Error(t('errors.git.operationInProgressPush', { operation }))
+  const upstream = await resolveUpstream(cwd, repository.branch)
+  const configuredRemote = await branchRemote(cwd, repository.branch)
+  const remote = upstream?.remote ?? configuredRemote ?? 'origin'
+  if (remote === '.') throw new Error(t('errors.git.pushUpstreamIsLocal'))
+  const branch = upstream?.branch ?? repository.branch
+  const args = ['push']
+  if (!upstream) args.push('--set-upstream')
+  args.push(remote, `HEAD:${branch}`)
+  await runGit(args, cwd)
+  return getGitConveyorStatus(cwd)
+}
+
+export async function createPullRequest(
+  cwd: string,
+  options: GitConveyorPullRequestOptions,
+): Promise<GitConveyorPullRequestResult> {
+  const title = options.title.trim()
+  if (!title) throw new Error(t('errors.git.pullRequestTitleRequired'))
+  const body = options.body.trim()
+  const status = await getGitConveyorStatus(cwd)
+  if (status.dirtyFiles > 0) throw new Error(t('errors.git.commitBeforePullRequest'))
+  if (!status.hasUpstream) throw new Error(t('errors.git.pushBeforePullRequest'))
+  if (status.ahead > 0) throw new Error(t('errors.git.pushBeforePullRequest'))
+  const branch = await runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd)
+    .then((result) => result.stdout.trim())
+    .catch(() => '')
+  if (!branch) throw new Error(t('errors.git.namedBranchRequired'))
+  const [upstream, branchRemoteName, upstreamRemote, originRemote] = await Promise.all([
+    resolveUpstream(cwd, branch),
+    branchRemote(cwd, branch),
+    gitConfig(cwd, 'remote.upstream.url'),
+    gitConfig(cwd, 'remote.origin.url'),
+  ])
+  const baseRemoteName = upstreamRemote ? 'upstream' : upstream?.remote ?? null
+  const headRemoteName = branchRemoteName ?? upstream?.remote ?? 'origin'
+  const [baseBranch, baseRemoteUrl, headRemoteUrl] = await Promise.all([
+    options.base?.trim() || defaultBranchForRemote(cwd, baseRemoteName),
+    baseRemoteName ? gitConfig(cwd, `remote.${baseRemoteName}.url`) : Promise.resolve(null),
+    gitConfig(cwd, `remote.${headRemoteName}.url`),
+  ])
+  const baseRepo = githubRepoFromRemote(baseRemoteUrl ?? upstreamRemote)
+  const headRepo = githubRepoFromRemote(headRemoteUrl ?? originRemote)
+  const headBranch = upstream?.branch ?? branch
+  const args = ['pr', 'create']
+  if (baseRepo) args.push('--repo', baseRepo)
+  if (baseBranch) args.push('--base', baseBranch)
+  args.push('--head', headRepo ? `${headRepo.split('/')[0]}:${headBranch}` : headBranch)
+  args.push('--title', title, '--body', body)
+  if (options.draft) args.push('--draft')
+  const output = await runCommand('gh', args, cwd)
+  return { url: extractUrl(output), output }
+}

package/apps/sessrumnir/src/main/git-worktree.test.ts

@@ -0,0 +1,101 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { test } from 'node:test'
+import {
+  describeGitFailure,
+  GIT_FATAL_EXIT_CODE,
+  GitCommandError,
+  isMissingRepositoryError,
+  parseGitWorktrees,
+  runGit,
+  slugifyWorktreePart,
+  worktreeBranchName,
+  worktreeTargetPath,
+} from './git-worktree'
+import { i18n, tEnglish } from '../shared/i18n'
+import { PSEUDO_LANGUAGE, SOURCE_LANGUAGE } from '../shared/i18n/languages'
+
+test('slugifyWorktreePart produces safe readable path and branch segments', () => {
+  assert.equal(slugifyWorktreePart('Feature: Add café tabs'), 'feature-add-cafe-tabs')
+  assert.equal(slugifyWorktreePart('---'), 'tab')
+})
+
+test('parseGitWorktrees preserves paths, branches, and bare markers', () => {
+  assert.deepEqual(parseGitWorktrees([
+    'worktree E:\\repo\\main app',
+    'HEAD abc123',
+    'branch refs/heads/main',
+    '',
+    'worktree E:\\repo\\bare',
+    'bare',
+    '',
+  ].join('\n')), [
+    { path: 'E:\\repo\\main app', head: 'abc123', branch: 'main', bare: false },
+    { path: 'E:\\repo\\bare', head: null, branch: null, bare: true },
+  ])
+})
+
+test('runGit rejects with the exit code and streams of the failed command', async () => {
+  const folder = await mkdtemp(join(tmpdir(), 'pi-git-worktree-'))
+  try {
+    await assert.rejects(
+      () => runGit(['rev-parse', '--show-toplevel'], folder),
+      (error: unknown) => {
+        assert.ok(error instanceof GitCommandError)
+        assert.equal(error.exitCode, GIT_FATAL_EXIT_CODE)
+        assert.match(error.stderr, /not a git repository/i)
+        assert.match(error.message, /^git rev-parse --show-toplevel failed: fatal:/)
+        assert.equal(isMissingRepositoryError(error), true)
+        return true
+      }
+    )
+  } finally {
+    await rm(folder, { recursive: true, force: true })
+  }
+})
+
+test('isMissingRepositoryError classifies only repository discovery failures', () => {
+  const args = ['rev-parse', '--show-toplevel']
+  assert.equal(
+    isMissingRepositoryError(new GitCommandError(args, GIT_FATAL_EXIT_CODE, '', 'fatal: this operation must be run in a work tree\n')),
+    true
+  )
+  assert.equal(
+    isMissingRepositoryError(new GitCommandError(args, GIT_FATAL_EXIT_CODE, '', 'fatal: Needed a single revision\n')),
+    false
+  )
+  assert.equal(
+    isMissingRepositoryError(new GitCommandError(args, 1, '', 'fatal: not a git repository\n')),
+    false
+  )
+  assert.equal(isMissingRepositoryError(new Error('spawn git ENOENT')), false)
+})
+
+test('describeGitFailure renders English for the log and marked text for the UI', async () => {
+  const args = ['worktree', 'remove', '/repo/worktrees/x']
+  await i18n.changeLanguage(PSEUDO_LANGUAGE)
+  try {
+    assert.equal(
+      describeGitFailure(args, '', 'fatal: worktree is dirty\n', tEnglish),
+      'git worktree remove /repo/worktrees/x failed: fatal: worktree is dirty',
+    )
+    // Only the app's own words are marked; the command and Git's text are not.
+    assert.match(
+      describeGitFailure(args, '', 'fatal: worktree is dirty\n'),
+      /^\[git worktree remove \/repo\/worktrees\/x ƒáîļéð: fatal: worktree is dirty ~+\]$/,
+    )
+  } finally {
+    await i18n.changeLanguage(SOURCE_LANGUAGE)
+  }
+})
+
+test('worktree names are deterministic and isolated by workspace id', () => {
+  assert.equal(
+    worktreeBranchName('Sessrúmnir', 'ws-123-abc'),
+    'pi/pi-desktop-123-abc'
+  )
+  const target = worktreeTargetPath('/tmp/gui/worktrees', '/repo/My App', 'ws-123-abc')
+  assert.match(target.replaceAll('\\', '/'), /\/tmp\/gui\/worktrees\/my-app\/my-app-ws-123-abc$/)
+})

package/apps/sessrumnir/src/main/git-worktree.ts

@@ -0,0 +1,201 @@
+import { spawn } from 'child_process'
+import { mkdir } from 'fs/promises'
+import { basename, dirname, join, resolve } from 'path'
+import { i18n, type Translate } from '../shared/i18n'
+
+/** Exit status Git uses for fatal errors, repository discovery included. */
+export const GIT_FATAL_EXIT_CODE = 128
+
+/** Git wordings that mean `cwd` is not inside a usable working tree. */
+const MISSING_REPOSITORY_PATTERN = /not a git repository|this operation must be run in a work tree/i
+
+export interface GitCommandResult {
+  stdout: string
+  stderr: string
+}
+
+/**
+ * Compact failure text for a git command. `t` defaults to the interface
+ * language; a caller that logs the failure passes `tEnglish` (ruling R16).
+ */
+export function describeGitFailure(
+  args: readonly string[], stdout: string, stderr: string, t: Translate = i18n.t,
+): string {
+  const detail = (stderr || stdout).trim()
+  const command = `git ${args.join(' ')}`
+  return detail
+    ? t('errors.git.commandFailedWithDetail', { command, detail })
+    : t('errors.git.commandFailed', { command })
+}
+
+/**
+ * Rejection raised when Git ran but exited non-zero. The exit code and both
+ * streams are kept so callers can classify a failure instead of matching the
+ * formatted message, which changes with the Git version and locale.
+ */
+export class GitCommandError extends Error {
+  constructor(
+    readonly args: readonly string[],
+    readonly exitCode: number | null,
+    readonly stdout: string,
+    readonly stderr: string,
+  ) {
+    super(describeGitFailure(args, stdout, stderr))
+    this.name = 'GitCommandError'
+  }
+}
+
+/**
+ * True only when Git refused a command because the directory is outside any
+ * working tree. A missing `git` binary, a missing folder, or any other fatal
+ * error stays unclassified so callers still surface it.
+ */
+export function isMissingRepositoryError(error: unknown): boolean {
+  return error instanceof GitCommandError &&
+    error.exitCode === GIT_FATAL_EXIT_CODE &&
+    MISSING_REPOSITORY_PATTERN.test(error.stderr)
+}
+
+export interface GitRepositoryInfo {
+  /** The main repository root, shared by linked worktrees. */
+  repoRoot: string
+  /** The commit checked out by the inspected worktree. */
+  head: string
+  branch: string | null
+  /** Porcelain status; empty means the worktree is clean. */
+  status: string
+}
+
+export interface GitWorktreeEntry {
+  path: string
+  head: string | null
+  branch: string | null
+  bare: boolean
+}
+
+export function runGit(args: readonly string[], cwd: string): Promise<GitCommandResult> {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn('git', [...args], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8') })
+    child.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') })
+    child.once('error', reject)
+    child.once('close', (code) => {
+      if (code === 0) {
+        resolvePromise({ stdout, stderr })
+        return
+      }
+      reject(new GitCommandError(args, code, stdout, stderr))
+    })
+  })
+}
+
+async function gitValue(args: readonly string[], cwd: string): Promise<string> {
+  return (await runGit(args, cwd)).stdout.trim()
+}
+
+/** Parse `git worktree list --porcelain` without losing Windows paths. */
+export function parseGitWorktrees(output: string): GitWorktreeEntry[] {
+  const entries: GitWorktreeEntry[] = []
+  let current: GitWorktreeEntry | null = null
+
+  const flush = (): void => {
+    if (current) entries.push(current)
+    current = null
+  }
+
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim()) {
+      flush()
+      continue
+    }
+    const separator = line.indexOf(' ')
+    const key = separator === -1 ? line : line.slice(0, separator)
+    const value = separator === -1 ? '' : line.slice(separator + 1)
+    if (key === 'worktree') {
+      flush()
+      current = { path: value, head: null, branch: null, bare: false }
+    } else if (!current) {
+      continue
+    } else if (key === 'HEAD') {
+      current.head = value || null
+    } else if (key === 'branch') {
+      current.branch = value.replace(/^refs\/heads\//, '') || null
+    } else if (key === 'bare') {
+      current.bare = true
+    }
+  }
+  flush()
+  return entries
+}
+
+export async function listGitWorktrees(cwd: string): Promise<GitWorktreeEntry[]> {
+  return parseGitWorktrees(await gitValue(['worktree', 'list', '--porcelain'], cwd))
+}
+
+/**
+ * Return the main repository root and the current worktree state. Calling this
+ * from a linked worktree is intentional: HEAD and dirty files must come from
+ * the worktree the user is cloning, not from the main checkout.
+ */
+export async function inspectGitRepository(cwd: string): Promise<GitRepositoryInfo> {
+  const worktreeRoot = await gitValue(['rev-parse', '--show-toplevel'], cwd)
+  const commonDirRaw = await gitValue(['rev-parse', '--git-common-dir'], cwd)
+  const commonDir = resolve(cwd, commonDirRaw)
+  const repoRoot = dirname(commonDir)
+  const [head, branch, status] = await Promise.all([
+    // An unborn branch has no HEAD yet, but its worktree is still valid and
+    // must be able to reach the first commit through the conveyor.
+    gitValue(['rev-parse', '--verify', 'HEAD'], cwd).catch(() => ''),
+    gitValue(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd).catch(() => null),
+    gitValue(['status', '--porcelain=v1', '--untracked-files=all'], cwd),
+  ])
+
+  // `--show-toplevel` also validates that the path is a usable checkout. Keep
+  // the variable read above so a future Git implementation cannot accidentally
+  // accept a bare repository without noticing the worktree requirement.
+  if (!worktreeRoot) throw new Error('Git returned an empty worktree root')
+  return { repoRoot, head, branch, status }
+}
+
+export function slugifyWorktreePart(value: string): string {
+  const slug = value
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || 'tab'
+}
+
+export function worktreeTargetPath(
+  guiWorktreesDir: string,
+  repoRoot: string,
+  workspaceId: string,
+): string {
+  const repoName = slugifyWorktreePart(basename(repoRoot))
+  return join(guiWorktreesDir, repoName, `${repoName}-${workspaceId}`)
+}
+
+export function worktreeBranchName(label: string, workspaceId: string): string {
+  return `pi/${slugifyWorktreePart(label)}-${workspaceId.replace(/^ws-/, '')}`
+}
+
+export async function createGitWorktree(options: {
+  sourceCwd: string
+  targetPath: string
+  branch: string
+}): Promise<void> {
+  await mkdir(dirname(options.targetPath), { recursive: true })
+  await runGit(['worktree', 'add', '-b', options.branch, options.targetPath, 'HEAD'], options.sourceCwd)
+}
+
+/** Remove only a clean worktree. Git refuses dirty worktrees, preserving edits. */
+export async function removeGitWorktree(repoRoot: string, worktreePath: string): Promise<void> {
+  await runGit(['worktree', 'remove', worktreePath], repoRoot)
+}

package/apps/sessrumnir/src/main/i18n.ts

@@ -0,0 +1,31 @@
+import { app } from 'electron'
+import { availableLanguages, i18n } from '../shared/i18n'
+import { PSEUDO_LANGUAGE_ENV, PSEUDO_LANGUAGE_ENV_ON } from '../shared/i18n/languages'
+import { resolveLanguage } from '../shared/i18n/resolve'
+import type { I18nEnvironment } from '../shared/ipc-contracts'
+
+export function isPseudoLanguageEnabled(): boolean {
+  return process.env[PSEUDO_LANGUAGE_ENV] === PSEUDO_LANGUAGE_ENV_ON
+}
+
+/** Only valid after `app.whenReady()`: the OS language list comes from Electron. */
+export function getI18nEnvironment(): I18nEnvironment {
+  return {
+    systemLanguages: app.getPreferredSystemLanguages(),
+    pseudoLanguageEnabled: isPseudoLanguageEnabled(),
+  }
+}
+
+/**
+ * Switch the main process to the language a setting resolves to. The app
+ * menu and the tray listen to i18next's `languageChanged` event and rebuild.
+ */
+export function applyLanguageSetting(setting: string): void {
+  const environment = getI18nEnvironment()
+  const language = resolveLanguage(
+    setting,
+    environment.systemLanguages,
+    availableLanguages(environment.pseudoLanguageEnabled),
+  )
+  if (language !== i18n.language) void i18n.changeLanguage(language)
+}