@magnusekdahl/parallix 1.2.0 → 1.2.1

package/lib/core/git.js

@@ -1,121 +1,140 @@
-const childProcess = require('child_process');
-
-/** @param {string[]} args @param {object} options */
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.git = git;
+exports.run = run;
+exports.getCurrentBranch = getCurrentBranch;
+exports.getWorktreeStatus = getWorktreeStatus;
+exports.isDirty = isDirty;
+exports.getUncommittedCount = getUncommittedCount;
+exports.parseUnmergedFiles = parseUnmergedFiles;
+exports.detectRebaseState = detectRebaseState;
+exports.getLastCommit = getLastCommit;
+exports.getLastThreeCommits = getLastThreeCommits;
+const node_child_process_1 = require("node:child_process");
+const fsMod = __importStar(require("node:fs"));
+const pathMod = __importStar(require("node:path"));
 function git(args, options = {}) {
-  const spawnOptions = {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    ...options
-  };
-  const result = childProcess.spawnSync('git', args, /** @type {import('child_process').SpawnSyncOptionsWithStringEncoding} */(spawnOptions));
-  if (result.error && result.status === null) {
-    throw result.error;
-  }
-  return result;
+    const spawnOptions = {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...options
+    };
+    const result = (0, node_child_process_1.spawnSync)('git', args, spawnOptions);
+    if (result.error && result.status === null) {
+        throw result.error;
+    }
+    return { status: result.status, signal: result.signal, stdout: String(result.stdout ?? ''), stderr: String(result.stderr ?? ''), error: result.error };
 }
-
-/** @param {string} command @param {string[]} args @param {object} options */
 function run(command, args, options = {}) {
-  const spawnOptions = {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    ...options
-  };
-  const result = childProcess.spawnSync(command, args, /** @type {import('child_process').SpawnSyncOptionsWithStringEncoding} */(spawnOptions));
-  if (result.error && result.status === null) {
-    throw result.error;
-  }
-  return result;
+    const spawnOptions = {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...options
+    };
+    const result = (0, node_child_process_1.spawnSync)(command, args, spawnOptions);
+    if (result.error && result.status === null) {
+        throw result.error;
+    }
+    return { status: result.status, signal: result.signal, stdout: String(result.stdout ?? ''), stderr: String(result.stderr ?? ''), error: result.error };
 }
-
 function getCurrentBranch(cwd = process.cwd()) {
-  const result = git(['-C', cwd, 'branch', '--show-current']);
-  return result.stdout.trim();
+    const result = git(['-C', cwd, 'branch', '--show-current']);
+    return result.stdout.trim();
 }
-
 function getWorktreeStatus(cwd = process.cwd()) {
-  const result = git(['-C', cwd, 'status', '--porcelain']);
-  return result.stdout
-    .split('\n')
-    .map(line => line.trimEnd())
-    .filter(Boolean);
+    const result = git(['-C', cwd, 'status', '--porcelain']);
+    return result.stdout
+        .split('\n')
+        .map(line => line.trimEnd())
+        .filter(Boolean);
 }
-
 function isDirty(cwd = process.cwd()) {
-  const result = git(['-C', cwd, 'status', '--porcelain']);
-  return result.stdout.trim().length > 0;
+    const result = git(['-C', cwd, 'status', '--porcelain']);
+    return result.stdout.trim().length > 0;
 }
-
 function getUncommittedCount(cwd = process.cwd()) {
-  const result = git(['-C', cwd, 'status', '--porcelain']);
-  if (!result.stdout.trim()) {return 0;}
-  return result.stdout.trim().split('\n').length;
+    const result = git(['-C', cwd, 'status', '--porcelain']);
+    if (!result.stdout.trim()) {
+        return 0;
+    }
+    return result.stdout.trim().split('\n').length;
 }
-
 function parseUnmergedFiles(output = '') {
-  return Array.from(new Set(
-    output
-      .split('\n')
-      .map(line => line.trim())
-      .filter(Boolean)
-      .map(line => line.split('\t')[1])
-      .filter(Boolean)
-  ));
+    return Array.from(new Set(output
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => line.split('\t')[1])
+        .filter(Boolean)));
 }
-
-function detectRebaseState(cwd = process.cwd(), { gitRunner = git, fsModule = require('fs'), pathModule = require('path') } = {}) {
-  const gitDirResult = gitRunner(['-C', cwd, 'rev-parse', '--git-dir']);
-  const resolvedGitDir = gitDirResult.status === 0
-    ? gitDirResult.stdout.trim()
-    : '.git';
-  const gitDir = pathModule.isAbsolute(resolvedGitDir)
-    ? resolvedGitDir
-    : pathModule.join(cwd, resolvedGitDir);
-  const rebaseMergeDir = pathModule.join(gitDir, 'rebase-merge');
-  const rebaseApplyDir = pathModule.join(gitDir, 'rebase-apply');
-  const rebaseDir = fsModule.existsSync(rebaseMergeDir)
-    ? rebaseMergeDir
-    : (fsModule.existsSync(rebaseApplyDir) ? rebaseApplyDir : null);
-
-  const headResult = gitRunner(['-C', cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD']);
-  const detached = headResult.status !== 0;
-
-  const showCurrentResult = gitRunner(['-C', cwd, 'rebase', '--show-current']);
-  const rebaseHead = showCurrentResult.status === 0 ? showCurrentResult.stdout.trim() : '';
-
-  const unmergedResult = gitRunner(['-C', cwd, 'ls-files', '-u']);
-  const unmergedFiles = unmergedResult.status === 0 ? parseUnmergedFiles(unmergedResult.stdout) : [];
-
-  const inProgress = Boolean(rebaseDir || rebaseHead || unmergedFiles.length > 0);
-
-  return {
-    inProgress,
-    rebaseHead,
-    detached,
-    unmergedFiles,
-    rebaseDir
-  };
+function detectRebaseState(cwd = process.cwd(), options = {}) {
+    const { gitRunner = git, fsModule = fsMod, pathModule = pathMod } = options;
+    const gitDirResult = gitRunner(['-C', cwd, 'rev-parse', '--git-dir']);
+    const resolvedGitDir = gitDirResult.status === 0
+        ? gitDirResult.stdout.trim()
+        : '.git';
+    const gitDir = pathModule.isAbsolute(resolvedGitDir)
+        ? resolvedGitDir
+        : pathModule.join(cwd, resolvedGitDir);
+    const rebaseMergeDir = pathModule.join(gitDir, 'rebase-merge');
+    const rebaseApplyDir = pathModule.join(gitDir, 'rebase-apply');
+    const rebaseDir = fsModule.existsSync(rebaseMergeDir)
+        ? rebaseMergeDir
+        : (fsModule.existsSync(rebaseApplyDir) ? rebaseApplyDir : null);
+    const headResult = gitRunner(['-C', cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD']);
+    const detached = headResult.status !== 0;
+    const showCurrentResult = gitRunner(['-C', cwd, 'rebase', '--show-current']);
+    const rebaseHead = showCurrentResult.status === 0 ? showCurrentResult.stdout.trim() : '';
+    const unmergedResult = gitRunner(['-C', cwd, 'ls-files', '-u']);
+    const unmergedFiles = unmergedResult.status === 0 ? parseUnmergedFiles(unmergedResult.stdout) : [];
+    const inProgress = Boolean(rebaseDir || rebaseHead || unmergedFiles.length > 0);
+    return {
+        inProgress,
+        rebaseHead,
+        detached,
+        unmergedFiles,
+        rebaseDir
+    };
 }
-
 function getLastCommit() {
-  const result = git(['log', '-1', '--format=%H|%ad|%s']);
-  const [sha, date, subject] = result.stdout.trim().split('|');
-  return { sha, date, subject };
+    const result = git(['log', '-1', '--format=%H|%ad|%s']);
+    const [sha, date, subject] = result.stdout.trim().split('|');
+    return { sha, date, subject };
 }
-
 function getLastThreeCommits() {
-  const result = git(['log', '-3', '--format=%s']);
-  return result.stdout.trim().split('\n');
+    const result = git(['log', '-3', '--format=%s']);
+    return result.stdout.trim().split('\n');
 }
-
-module.exports = {
-  git,
-  run,
-  getCurrentBranch,
-  getWorktreeStatus,
-  isDirty,
-  getUncommittedCount,
-  detectRebaseState,
-  getLastCommit,
-  getLastThreeCommits
-};

package/lib/core/git.ts

@@ -0,0 +1,146 @@
+import childProcess, { spawnSync } from 'node:child_process';
+import type { SpawnSyncOptions } from 'node:child_process';
+import * as fsMod from 'node:fs';
+import * as pathMod from 'node:path';
+
+interface GitOptions {
+  encoding?: BufferEncoding;
+  stdio?: import('node:child_process').StdioOptions;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  maxBuffer?: number;
+  [key: string]: unknown;
+}
+
+interface GitResult {
+  status: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+  error?: Error | null;
+}
+
+export function git(args: string[], options: GitOptions = {}): GitResult {
+  const spawnOptions: SpawnSyncOptions = {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'] as const,
+    ...options
+  };
+  const result = spawnSync('git', args, spawnOptions);
+  if (result.error && result.status === null) {
+    throw result.error;
+  }
+  return { status: result.status, signal: result.signal, stdout: String(result.stdout ?? ''), stderr: String(result.stderr ?? ''), error: result.error };
+}
+
+export function run(command: string, args: string[], options: GitOptions = {}): GitResult {
+  const spawnOptions: SpawnSyncOptions = {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'] as const,
+    ...options
+  };
+  const result = spawnSync(command, args, spawnOptions);
+  if (result.error && result.status === null) {
+    throw result.error;
+  }
+  return { status: result.status, signal: result.signal, stdout: String(result.stdout ?? ''), stderr: String(result.stderr ?? ''), error: result.error };
+}
+
+export function getCurrentBranch(cwd: string = process.cwd()): string {
+  const result = git(['-C', cwd, 'branch', '--show-current']);
+  return result.stdout.trim();
+}
+
+export function getWorktreeStatus(cwd: string = process.cwd()): string[] {
+  const result = git(['-C', cwd, 'status', '--porcelain']);
+  return result.stdout
+    .split('\n')
+    .map(line => line.trimEnd())
+    .filter(Boolean);
+}
+
+export function isDirty(cwd: string = process.cwd()): boolean {
+  const result = git(['-C', cwd, 'status', '--porcelain']);
+  return result.stdout.trim().length > 0;
+}
+
+export function getUncommittedCount(cwd: string = process.cwd()): number {
+  const result = git(['-C', cwd, 'status', '--porcelain']);
+  if (!result.stdout.trim()) {return 0;}
+  return result.stdout.trim().split('\n').length;
+}
+
+export function parseUnmergedFiles(output: string = ''): string[] {
+  return Array.from(new Set(
+    output
+      .split('\n')
+      .map(line => line.trim())
+      .filter(Boolean)
+      .map(line => line.split('\t')[1])
+      .filter(Boolean)
+  ));
+}
+
+interface RebaseStateResult {
+  inProgress: boolean;
+  rebaseHead: string;
+  detached: boolean;
+  unmergedFiles: string[];
+  rebaseDir: string | null;
+}
+
+interface GitRunner {
+  (args: string[]): GitResult;
+}
+
+interface DetectRebaseOptions {
+  gitRunner?: GitRunner;
+  fsModule?: typeof fsMod;
+  pathModule?: typeof pathMod;
+}
+
+export function detectRebaseState(cwd: string = process.cwd(), options: DetectRebaseOptions = {}): RebaseStateResult {
+  const { gitRunner = git, fsModule = fsMod, pathModule = pathMod } = options;
+  const gitDirResult = gitRunner(['-C', cwd, 'rev-parse', '--git-dir']);
+  const resolvedGitDir = gitDirResult.status === 0
+    ? gitDirResult.stdout.trim()
+    : '.git';
+  const gitDir = pathModule.isAbsolute(resolvedGitDir)
+    ? resolvedGitDir
+    : pathModule.join(cwd, resolvedGitDir);
+  const rebaseMergeDir = pathModule.join(gitDir, 'rebase-merge');
+  const rebaseApplyDir = pathModule.join(gitDir, 'rebase-apply');
+  const rebaseDir = fsModule.existsSync(rebaseMergeDir)
+    ? rebaseMergeDir
+    : (fsModule.existsSync(rebaseApplyDir) ? rebaseApplyDir : null);
+
+  const headResult = gitRunner(['-C', cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const detached = headResult.status !== 0;
+
+  const showCurrentResult = gitRunner(['-C', cwd, 'rebase', '--show-current']);
+  const rebaseHead = showCurrentResult.status === 0 ? showCurrentResult.stdout.trim() : '';
+
+  const unmergedResult = gitRunner(['-C', cwd, 'ls-files', '-u']);
+  const unmergedFiles = unmergedResult.status === 0 ? parseUnmergedFiles(unmergedResult.stdout) : [];
+
+  const inProgress = Boolean(rebaseDir || rebaseHead || unmergedFiles.length > 0);
+
+  return {
+    inProgress,
+    rebaseHead,
+    detached,
+    unmergedFiles,
+    rebaseDir
+  };
+}
+
+export function getLastCommit(): { sha: string; date: string; subject: string } {
+  const result = git(['log', '-1', '--format=%H|%ad|%s']);
+  const [sha, date, subject] = result.stdout.trim().split('|');
+  return { sha, date, subject };
+}
+
+export function getLastThreeCommits(): string[] {
+  const result = git(['log', '-3', '--format=%s']);
+  return result.stdout.trim().split('\n');
+}

package/lib/core/gitignore.js

@@ -1,112 +1,65 @@
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Workflow-generated paths that must be gitignored in enterprise repositories.
- * These are paths created by the px workflow toolkit that should never be
- * committed to version control.
- */
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const WORKFLOW_ENTRIES = [
-  '.workflow/',
-  '.sessions/',
-  '.forgejo-local/',
-  'workflow/.cache/',
-  'workflow/.sessions/',
-  'workflow/config/agents.local.json',
-  'agents.local.json',
+    '.workflow/',
+    '.sessions/',
+    '.forgejo-local/',
+    'workflow/.cache/',
+    'workflow/.sessions/',
+    'workflow/config/agents.local.json',
+    'agents.local.json',
 ];
-
-/**
- * Ensure that a repository's .gitignore contains all workflow-generated paths.
- *
- * Handles:
- * - Missing .gitignore: creates one with all 7 entries
- * - Existing .gitignore: appends only missing entries, skips duplicates
- * - Symlinked .gitignore: skips modification, logs warning
- * - Non-git directories: skips gracefully without crashing
- *
- * @param {string} rootDir - Path to the repository root
- * @param {object} options - Injected dependencies
- * @param {Function} [options.existsSyncFn] - fs.existsSync replacement
- * @param {Function} [options.lstatSyncFn] - fs.lstatSync replacement
- * @param {Function} [options.readFileSyncFn] - fs.readFileSync replacement
- * @param {Function} [options.writeFileSyncFn] - fs.writeFileSync replacement
- * @param {Function} [options.logFn] - Logger function
- * @returns {{ ok: boolean, created: boolean, appended: number, skipped: boolean, reason?: string }}
- */
 function ensureWorkflowGitignore(rootDir, options = {}) {
-  const {
-    existsSyncFn = fs.existsSync,
-    lstatSyncFn = fs.lstatSync,
-    readFileSyncFn = fs.readFileSync,
-    writeFileSyncFn = fs.writeFileSync,
-    logFn = () => {},
-  } = options;
-
-  const gitignorePath = path.join(rootDir, '.gitignore');
-  const gitDirPath = path.join(rootDir, '.git');
-
-  // Check if this is a git repository
-  if (!existsSyncFn(gitDirPath)) {
-    logFn(`[gitignore] Skipping ${rootDir}: not a git repository (no .git directory)`);
-    return { ok: true, created: false, appended: 0, skipped: true, reason: 'not-a-git-repo' };
-  }
-
-  // Check if .gitignore exists
-  if (!existsSyncFn(gitignorePath)) {
-    // Create new .gitignore with all entries
-    const content = WORKFLOW_ENTRIES.join('\n') + '\n';
-    writeFileSyncFn(gitignorePath, content, 'utf8');
-    logFn(`[gitignore] Created ${gitignorePath} with ${WORKFLOW_ENTRIES.length} entries`);
-    return { ok: true, created: true, appended: WORKFLOW_ENTRIES.length, skipped: false };
-  }
-
-  // .gitignore exists - check for symlink
-  try {
-    const stat = lstatSyncFn(gitignorePath);
-    if (stat.isSymbolicLink()) {
-      logFn(`[gitignore] Skipping ${gitignorePath}: symbolic link, not modifying`);
-      return { ok: true, created: false, appended: 0, skipped: true, reason: 'symlink' };
+    const { existsSyncFn = node_fs_1.default.existsSync, lstatSyncFn = node_fs_1.default.lstatSync, readFileSyncFn = node_fs_1.default.readFileSync, writeFileSyncFn = node_fs_1.default.writeFileSync, logFn = () => { }, } = options;
+    const gitignorePath = node_path_1.default.join(rootDir, '.gitignore');
+    const gitDirPath = node_path_1.default.join(rootDir, '.git');
+    if (!existsSyncFn(gitDirPath)) {
+        logFn(`[gitignore] Skipping ${rootDir}: not a git repository (no .git directory)`);
+        return { ok: true, created: false, appended: 0, skipped: true, reason: 'not-a-git-repo' };
     }
-  } catch (_) {
-    // If we can't stat, fall through to read - it might exist but be inaccessible
-  }
-
-  // Read existing .gitignore
-  let existingContent;
-  try {
-    existingContent = readFileSyncFn(gitignorePath, 'utf8');
-  } catch (err) {
-    logFn(`[gitignore] Could not read ${gitignorePath}: ${/** @type{Error} */(err).message}`);
-    return { ok: false, created: false, appended: 0, skipped: false, reason: `read-error: ${/** @type{Error} */(err).message}` };
-  }
-
-  // Parse existing entries
-  const existingLines = existingContent.split(/\r?\n/);
-  const existingEntries = new Set(
-    existingLines
-      /** @param {string} line */
-      .map(/** @param {string} line */(line) => line.trim())
-      /** @param {string} line */
-      .filter(/** @param {string} line */(line) => line.length > 0 && !line.startsWith('#'))
-  );
-
-  // Find missing entries
-  const missingEntries = WORKFLOW_ENTRIES.filter(entry => !existingEntries.has(entry));
-
-  if (missingEntries.length === 0) {
-    logFn(`[gitignore] ${gitignorePath} already contains all ${WORKFLOW_ENTRIES.length} workflow entries`);
-    return { ok: true, created: false, appended: 0, skipped: false };
-  }
-
-  // Append missing entries
-  const newContent = existingContent + '\n' + missingEntries.join('\n') + '\n';
-  writeFileSyncFn(gitignorePath, newContent, 'utf8');
-  logFn(`[gitignore] Appended ${missingEntries.length} missing entries to ${gitignorePath}`);
-
-  return { ok: true, created: false, appended: missingEntries.length, skipped: false };
+    if (!existsSyncFn(gitignorePath)) {
+        const content = [...WORKFLOW_ENTRIES].join('\n') + '\n';
+        writeFileSyncFn(gitignorePath, content, 'utf8');
+        logFn(`[gitignore] Created ${gitignorePath} with ${WORKFLOW_ENTRIES.length} entries`);
+        return { ok: true, created: true, appended: WORKFLOW_ENTRIES.length, skipped: false };
+    }
+    try {
+        const stat = lstatSyncFn(gitignorePath);
+        if (stat.isSymbolicLink()) {
+            logFn(`[gitignore] Skipping ${gitignorePath}: symbolic link, not modifying`);
+            return { ok: true, created: false, appended: 0, skipped: true, reason: 'symlink' };
+        }
+    }
+    catch (_err) {
+        // If we can't stat, fall through to read
+    }
+    let existingContent;
+    try {
+        existingContent = readFileSyncFn(gitignorePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logFn(`[gitignore] Could not read ${gitignorePath}: ${message}`);
+        return { ok: false, created: false, appended: 0, skipped: false, reason: `read-error: ${message}` };
+    }
+    const existingLines = existingContent.split(/\r?\n/);
+    const existingEntries = new Set(existingLines
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#')));
+    const missingEntries = WORKFLOW_ENTRIES.filter(entry => !existingEntries.has(entry));
+    if (missingEntries.length === 0) {
+        logFn(`[gitignore] ${gitignorePath} already contains all ${WORKFLOW_ENTRIES.length} workflow entries`);
+        return { ok: true, created: false, appended: 0, skipped: false };
+    }
+    const newContent = existingContent + '\n' + [...missingEntries].join('\n') + '\n';
+    writeFileSyncFn(gitignorePath, newContent, 'utf8');
+    logFn(`[gitignore] Appended ${missingEntries.length} missing entries to ${gitignorePath}`);
+    return { ok: true, created: false, appended: missingEntries.length, skipped: false };
 }
-
+ensureWorkflowGitignore.WORKFLOW_ENTRIES = WORKFLOW_ENTRIES;
+ensureWorkflowGitignore.ensureWorkflowGitignore = ensureWorkflowGitignore;
 module.exports = ensureWorkflowGitignore;
-module.exports.ensureWorkflowGitignore = ensureWorkflowGitignore;
-module.exports.WORKFLOW_ENTRIES = WORKFLOW_ENTRIES;

package/lib/core/gitignore.ts

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WORKFLOW_ENTRIES = [
+  '.workflow/',
+  '.sessions/',
+  '.forgejo-local/',
+  'workflow/.cache/',
+  'workflow/.sessions/',
+  'workflow/config/agents.local.json',
+  'agents.local.json',
+] as const;
+
+interface GitignoreResult {
+  ok: boolean;
+  created: boolean;
+  appended: number;
+  skipped: boolean;
+  reason?: string;
+}
+
+interface EnsureOptions {
+  existsSyncFn?: typeof fs.existsSync;
+  lstatSyncFn?: typeof fs.lstatSync;
+  readFileSyncFn?: typeof fs.readFileSync;
+  writeFileSyncFn?: typeof fs.writeFileSync;
+  logFn?: (msg: string) => void;
+}
+
+type EnsureWorkflowGitignoreFn = {
+  (rootDir: string, options?: EnsureOptions): GitignoreResult;
+  WORKFLOW_ENTRIES: typeof WORKFLOW_ENTRIES;
+  ensureWorkflowGitignore: EnsureWorkflowGitignoreFn;
+};
+
+function ensureWorkflowGitignore(rootDir: string, options: EnsureOptions = {}): GitignoreResult {
+  const {
+    existsSyncFn = fs.existsSync,
+    lstatSyncFn = fs.lstatSync,
+    readFileSyncFn = fs.readFileSync,
+    writeFileSyncFn = fs.writeFileSync,
+    logFn = () => {},
+  } = options;
+
+  const gitignorePath = path.join(rootDir, '.gitignore');
+  const gitDirPath = path.join(rootDir, '.git');
+
+  if (!existsSyncFn(gitDirPath)) {
+    logFn(`[gitignore] Skipping ${rootDir}: not a git repository (no .git directory)`);
+    return { ok: true, created: false, appended: 0, skipped: true, reason: 'not-a-git-repo' };
+  }
+
+  if (!existsSyncFn(gitignorePath)) {
+    const content = [...WORKFLOW_ENTRIES].join('\n') + '\n';
+    writeFileSyncFn(gitignorePath, content, 'utf8');
+    logFn(`[gitignore] Created ${gitignorePath} with ${WORKFLOW_ENTRIES.length} entries`);
+    return { ok: true, created: true, appended: WORKFLOW_ENTRIES.length, skipped: false };
+  }
+
+  try {
+    const stat = lstatSyncFn(gitignorePath);
+    if (stat.isSymbolicLink()) {
+      logFn(`[gitignore] Skipping ${gitignorePath}: symbolic link, not modifying`);
+      return { ok: true, created: false, appended: 0, skipped: true, reason: 'symlink' };
+    }
+  } catch (_err: unknown) {
+    // If we can't stat, fall through to read
+  }
+
+  let existingContent: string;
+  try {
+    existingContent = readFileSyncFn(gitignorePath, 'utf8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    logFn(`[gitignore] Could not read ${gitignorePath}: ${message}`);
+    return { ok: false, created: false, appended: 0, skipped: false, reason: `read-error: ${message}` };
+  }
+
+  const existingLines = existingContent.split(/\r?\n/);
+  const existingEntries = new Set(
+    existingLines
+      .map((line: string) => line.trim())
+      .filter((line: string) => line.length > 0 && !line.startsWith('#'))
+  );
+
+  const missingEntries = WORKFLOW_ENTRIES.filter(entry => !existingEntries.has(entry));
+
+  if (missingEntries.length === 0) {
+    logFn(`[gitignore] ${gitignorePath} already contains all ${WORKFLOW_ENTRIES.length} workflow entries`);
+    return { ok: true, created: false, appended: 0, skipped: false };
+  }
+
+  const newContent = existingContent + '\n' + [...missingEntries].join('\n') + '\n';
+  writeFileSyncFn(gitignorePath, newContent, 'utf8');
+  logFn(`[gitignore] Appended ${missingEntries.length} missing entries to ${gitignorePath}`);
+
+  return { ok: true, created: false, appended: missingEntries.length, skipped: false };
+}
+
+(ensureWorkflowGitignore as EnsureWorkflowGitignoreFn).WORKFLOW_ENTRIES = WORKFLOW_ENTRIES;
+(ensureWorkflowGitignore as EnsureWorkflowGitignoreFn).ensureWorkflowGitignore = ensureWorkflowGitignore as EnsureWorkflowGitignoreFn;
+
+export = ensureWorkflowGitignore;