@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/commands/status.js

@@ -3,12 +3,13 @@ const { findTaskFile, getTaskStatus } = require('../tools/backlog');
 const { findMissionDir, findCheckpoints, getFirstLine, inferSlug, missionBranchPrefix, missionBranchName } = require('../core/mission-utils');
 const { WORKFLOW_AGENT_NAMES, eligibleAgentsForStep, readAgentConfigOrExit, workflowLauncherStatus } = require('../agents/agents');
 const { getPrStatus } = require('../tools/forgejo');
-const fs = require('fs');
 const path = require('path');
 const fmt = require('../core/fmt');
 
+/** @param {string} porcelain */
 function parseWorktreeList(porcelain) {
   const entries = [];
+  /** @type{{path: string, branch: string | null} | null} */
   let current = null;
 
   for (const line of porcelain.split('\n')) {
@@ -21,7 +22,7 @@ function parseWorktreeList(porcelain) {
     }
 
     if (line.startsWith('worktree ')) {
-      if (current) entries.push(current);
+      if (current) {entries.push(current);}
       current = { path: line.slice('worktree '.length).trim(), branch: null };
       continue;
     }
@@ -31,7 +32,7 @@ function parseWorktreeList(porcelain) {
     }
   }
 
-  if (current) entries.push(current);
+  if (current) {entries.push(current);}
   return entries;
 }
 
@@ -46,6 +47,7 @@ function findStaleMissionWorktrees({
     return [];
   }
 
+  /** @type {string | null} */
   let resolvedPrimary = primaryWorktree;
   if (!resolvedPrimary) {
     try {
@@ -65,7 +67,7 @@ function findStaleMissionWorktrees({
       const match = branchRef.startsWith(normalizedRefPrefix)
         ? [branchRef, branchRef.slice(normalizedRefPrefix.length)]
         : null;
-      if (!match) return null;
+      if (!match) {return null;}
 
       const slug = match[1];
       const taskFile = findTaskFileFn(slug);
@@ -87,11 +89,13 @@ function findStaleMissionWorktrees({
     .filter(Boolean);
 }
 
+/** @param {string} ref */
 function formatWorktreeBranch(ref) {
-  if (!ref) return '(detached HEAD)';
+  if (!ref) {return '(detached HEAD)';}
   return ref.replace(/^refs\/heads\//, '');
 }
 
+/** @param {Function} log @param {string} label @param {{detached?: boolean, unmergedFiles: string[]}} rebaseState */
 function logRebaseDiagnostics(log, label, rebaseState) {
   const detachedText = rebaseState.detached ? 'detached HEAD, ' : '';
   log(`${label}: ${detachedText}${rebaseState.unmergedFiles.length} unmerged file(s)`);
@@ -100,25 +104,26 @@ function logRebaseDiagnostics(log, label, rebaseState) {
   });
 }
 
-function status(args, options = {}) {
-  const exit = options.exit || process.exit;
-  const log = options.log || fmt.log.plain;
-  const inferSlugFn = options.inferSlugFn || inferSlug;
-  const getCurrentBranchFn = options.getCurrentBranchFn || getCurrentBranch;
-  const findTaskFileFn = options.findTaskFileFn || findTaskFile;
-  const getTaskStatusFn = options.getTaskStatusFn || getTaskStatus;
-  const findMissionDirFn = options.findMissionDirFn || findMissionDir;
-  const findCheckpointsFn = options.findCheckpointsFn || findCheckpoints;
-  const getFirstLineFn = options.getFirstLineFn || getFirstLine;
-  const getPrStatusFn = options.getPrStatusFn || getPrStatus;
-  const findStaleMissionWorktreesFn = options.findStaleMissionWorktreesFn || findStaleMissionWorktrees;
-  const readAgentConfigOrExitFn = options.readAgentConfigOrExitFn || readAgentConfigOrExit;
-  const eligibleAgentsForStepFn = options.eligibleAgentsForStepFn || eligibleAgentsForStep;
-  const allWorkflowAgentNamesFn = options.allWorkflowAgentNamesFn || (() => WORKFLOW_AGENT_NAMES);
-  const workflowLauncherStatusFn = options.workflowLauncherStatusFn || workflowLauncherStatus;
-  const getLastThreeCommitsFn = options.getLastThreeCommitsFn || getLastThreeCommits;
-  const getUncommittedCountFn = options.getUncommittedCountFn || getUncommittedCount;
-  const detectRebaseStateFn = options.detectRebaseStateFn || detectRebaseState;
+/** @param {string[]} args @param {{exit?: Function, log?: Function, inferSlugFn?: Function, getCurrentBranchFn?: Function, findTaskFileFn?: Function, getTaskStatusFn?: Function, findMissionDirFn?: Function, findCheckpointsFn?: Function, getFirstLineFn?: Function, getPrStatusFn?: Function, findStaleMissionWorktreesFn?: Function, readAgentConfigOrExitFn?: Function, eligibleAgentsForStepFn?: Function, allWorkflowAgentNamesFn?: Function, workflowLauncherStatusFn?: Function, getLastThreeCommitsFn?: Function, getUncommittedCountFn?: Function, detectRebaseStateFn?: Function}} opts */
+function status(args, opts = {}) {
+  const exit = opts.exit || process.exit;
+  const log = opts.log || fmt.log.plain;
+  const inferSlugFn = opts.inferSlugFn || inferSlug;
+  const getCurrentBranchFn = opts.getCurrentBranchFn || getCurrentBranch;
+  const findTaskFileFn = opts.findTaskFileFn || findTaskFile;
+  const getTaskStatusFn = opts.getTaskStatusFn || getTaskStatus;
+  const findMissionDirFn = opts.findMissionDirFn || findMissionDir;
+  const findCheckpointsFn = opts.findCheckpointsFn || findCheckpoints;
+  const getFirstLineFn = opts.getFirstLineFn || getFirstLine;
+  const getPrStatusFn = opts.getPrStatusFn || getPrStatus;
+  const findStaleMissionWorktreesFn = opts.findStaleMissionWorktreesFn || findStaleMissionWorktrees;
+  const readAgentConfigOrExitFn = opts.readAgentConfigOrExitFn || readAgentConfigOrExit;
+  const eligibleAgentsForStepFn = opts.eligibleAgentsForStepFn || eligibleAgentsForStep;
+  const allWorkflowAgentNamesFn = opts.allWorkflowAgentNamesFn || (() => WORKFLOW_AGENT_NAMES);
+  const workflowLauncherStatusFn = opts.workflowLauncherStatusFn || workflowLauncherStatus;
+  const getLastThreeCommitsFn = opts.getLastThreeCommitsFn || getLastThreeCommits;
+  const getUncommittedCountFn = opts.getUncommittedCountFn || getUncommittedCount;
+  const detectRebaseStateFn = opts.detectRebaseStateFn || detectRebaseState;
 
   const explicitSlug = args[0];
   const slug = inferSlugFn(explicitSlug);
@@ -168,17 +173,17 @@ function status(args, options = {}) {
 
   if (!explicitSlug) {
     const staleWorktrees = findStaleMissionWorktreesFn();
-    staleWorktrees.forEach(entry => {
+    staleWorktrees.forEach(/** @param {{path: string, branch: string | null, taskStatus: string | null, cleanupCommand?: string}} entry */ (entry) => {
       log(`Stale worktree: ${fmt.path(entry.path)} (task: ${entry.taskStatus})`);
       try {
         const rebaseState = detectRebaseStateFn(entry.path);
         if (rebaseState.inProgress) {
-          logRebaseDiagnostics(log, `Rebase in progress on ${formatWorktreeBranch(entry.branch)}`, rebaseState);
+          logRebaseDiagnostics(log, `Rebase in progress on ${formatWorktreeBranch(entry.branch || '')}`, rebaseState);
         }
       } catch (_) {
         // Ignore stale worktrees that disappear during inspection.
       }
-      log(`  Cleanup: ${fmt.command(entry.cleanupCommand)}`);
+      log(`  Cleanup: ${fmt.command(entry.cleanupCommand || '')}`);
     });
   }
 
@@ -203,7 +208,7 @@ function status(args, options = {}) {
 
   const lastThree = getLastThreeCommitsFn();
   log('Last 3 commits:');
-  lastThree.forEach(c => log(`  - ${c}`));
+  lastThree.forEach(/** @param {string} c */ (c) => log(`  - ${c}`));
 
   log(`Uncommitted files: ${getUncommittedCountFn()}`);
   log(fmt.bold('----------------------'));

package/lib/core/fmt.js

@@ -34,18 +34,22 @@ const agentMap = {
   custom: 'yellow',
 };
 
+/** @param {import('node:util').InspectColor} format @param {string} text */
 function colorize(format, text) {
   return styleText(format, String(text ?? ''));
 }
 
+/** @param {string} text */
 function stripAnsi(text) {
   return String(text ?? '').replace(/\x1B\[[0-9;]*m/g, '');
 }
 
+/** @param {string} text */
 function visibleWidth(text) {
   return stripAnsi(text).length;
 }
 
+/** @param {string} text @param {number} width */
 function padVisibleEnd(text, width) {
   const stringValue = String(text ?? '');
   const padLength = Math.max(0, width - visibleWidth(stringValue));
@@ -55,15 +59,19 @@ function padVisibleEnd(text, width) {
 /**
  * Formats a status line prefix (e.g. "[PASS]").
  */
+/** @param {string} type @param {string} text */
 function status(type, text) {
-  const format = statusMap[type];
-  if (!format) return `[${type}] ${text}`;
-  return `${colorize(format, `[${type}]`)} ${text}`;
+  /** @type {Record<string,string>} */
+  const sm = statusMap;
+  const format = sm[type];
+  if (!format) {return `[${type}] ${text}`;}
+  return `${colorize(/** @type {import('node:util').InspectColor} */(format), `[${type}]`)} ${text}`;
 }
 
 /**
  * Formats an agent family name.
  */
+/** @param {string} family @param {string} [text] */
 function agent(family, text = family) {
   let label = text;
   // Disambiguate the opencode-backed `custom` family only when the caller
@@ -73,15 +81,19 @@ function agent(family, text = family) {
   if (family === 'custom' && text !== 'custom') {
     label = 'custom (opencode)';
   }
-  const format = agentMap[family];
-  if (!format) return label;
-  return colorize(format, label);
+  /** @type {Record<string,string>} */
+  const am = agentMap;
+  const format = am[family];
+  if (!format) {return label;}
+  return colorize(/** @type {import('node:util').InspectColor} */(format), label);
 }
 
+/** @param {string} text */
 function bold(text) {
   return colorize('bold', text);
 }
 
+/** @param {string} text */
 function dim(text) {
   return colorize('gray', text);
 }
@@ -89,6 +101,7 @@ function dim(text) {
 /**
  * Aligned key-value pair.
  */
+/** @param {string} key @param {string} value @param {number} width */
 function kv(key, value, width = 30) {
   return `${bold(key.padEnd(width))} ${value}`;
 }
@@ -96,93 +109,123 @@ function kv(key, value, width = 30) {
 /**
  * Aligned table of columns.
  */
+/** @param {string[][]} rows @param {{indent?: number, colPadding?: number}} [opts] */
 function table(rows, { indent = 2, colPadding = 2 } = {}) {
-  if (rows.length === 0) return '';
+  if (rows.length === 0) {return '';}
+  /** @param {unknown} _ @param {number} i */
   const colWidths = rows[0].map((_, i) => Math.max(...rows.map(row => visibleWidth(row[i] ?? ''))));
   const padding = ' '.repeat(indent);
+  /** @param {string[]} row */
   return rows.map(row => padding + row.map((col, i) => padVisibleEnd(col ?? '', colWidths[i] + colPadding)).join('')).join('\n');
 }
 
 /**
  * Bulleted list.
  */
+/** @param {string[]} items @param {{bullet?: string, indent?: number}} [opts] */
 function list(items, { bullet = '-', indent = 2 } = {}) {
   const padding = ' '.repeat(indent);
+  /** @param {string} item */
   return items.map(item => `${padding}${bullet} ${item}`).join('\n');
 }
 
 const semantic = {
-  path: (text) => colorize('blue', text),
-  slug: (text) => colorize('cyan', bold(text)),
-  branch: (text) => colorize('magenta', text),
-  sha: (text) => colorize('yellow', text),
-  command: (text) => colorize('green', text),
+  path: /** @param {string} text */(text) => colorize('blue', text),
+  slug: /** @param {string} text */(text) => colorize('cyan', bold(text)),
+  branch: /** @param {string} text */(text) => colorize('magenta', text),
+  sha: /** @param {string} text */(text) => colorize('yellow', text),
+  command: /** @param {string} text */(text) => colorize('green', text),
 };
 
+/** @type {{log: Function, error: Function}} */
 let currentLogger = {
+  /** @param {...any} args */
   log: (...args) => console.log(...args),
+  /** @param {...any} args */
   error: (...args) => console.error(...args),
 };
 
+/** @typedef {{log?: Function, error?: Function}} LoggerObj */
+
+/** @type{{info: Function, pass: Function, fail: Function, warn: Function, error: Function, debug: Function, plain: Function, plainError: Function}} */
 const log = {
+  /** @param {string} text */
   info: (text) => {
+    /** @param {string} line */
     return text.toString().split('\n').map(line => {
       const s = status('INFO', line);
       currentLogger.log(s);
       return s;
     }).join('\n');
   },
+  /** @param {string} text */
   pass: (text) => {
+    /** @param {string} line */
     return text.toString().split('\n').map(line => {
       const s = status('PASS', line);
       currentLogger.log(s);
       return s;
     }).join('\n');
   },
+  /** @param {string} text */
   fail: (text) => {
+    /** @param {string} line */
     return text.toString().split('\n').map(line => {
       const s = status('FAIL', line);
       currentLogger.error(s);
       return s;
     }).join('\n');
   },
+  /** @param {string} text */
   warn: (text) => {
+    /** @param {string} line */
     return text.toString().split('\n').map(line => {
       const s = status('WARN', line);
       currentLogger.log(s);
       return s;
     }).join('\n');
   },
+  /** @param {string} text */
   error: (text) => {
+    /** @param {string} line */
     return text.toString().split('\n').map(line => {
       const s = status('FAIL', line);
       currentLogger.error(s);
       return s;
     }).join('\n');
   },
+  /** @param {string} text */
   debug: (text) => {
-    if (!process.env.DEBUG) return null;
+    if (!process.env.DEBUG) {return null;}
+    /** @param {string} line */
     return text.toString().split('\n').map(line => {
       const s = status('DEBUG', line);
       currentLogger.log(s);
       return s;
     }).join('\n');
   },
+  /** @param {string} text */
   plain: (text) => {
+    /** @param {string} line */
     text.toString().split('\n').forEach(line => currentLogger.log(line));
     return text;
   },
+  /** @param {string} text */
   plainError: (text) => {
+    /** @param {string} line */
     text.toString().split('\n').forEach(line => currentLogger.error(line));
     return text;
   },
 };
 
+/** @param {LoggerObj|Function} newLogger */
 function setLogger(newLogger) {
   const old = currentLogger;
+  /** @type {LoggerObj} */
+  const logger = /** @type {LoggerObj} */(newLogger);
   currentLogger = {
-    log: newLogger.log || newLogger,
-    error: newLogger.error || newLogger.log || newLogger,
+    log: typeof logger.log === 'function' ? logger.log : (() => {}),
+    error: typeof logger.error === 'function' ? logger.error : (typeof logger.log === 'function' ? logger.log : (() => {})),
   };
   return old;
 }

package/lib/core/git.js

@@ -1,26 +1,28 @@
 const childProcess = require('child_process');
 
+/** @param {string[]} args @param {object} options */
 function git(args, options = {}) {
   const spawnOptions = {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
     ...options
   };
-  const result = childProcess.spawnSync('git', args, spawnOptions);
-  if (result.error && result.status == null) {
+  const result = childProcess.spawnSync('git', args, /** @type {import('child_process').SpawnSyncOptionsWithStringEncoding} */(spawnOptions));
+  if (result.error && result.status === null) {
     throw result.error;
   }
   return result;
 }
 
+/** @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, spawnOptions);
-  if (result.error && result.status == null) {
+  const result = childProcess.spawnSync(command, args, /** @type {import('child_process').SpawnSyncOptionsWithStringEncoding} */(spawnOptions));
+  if (result.error && result.status === null) {
     throw result.error;
   }
   return result;
@@ -46,7 +48,7 @@ function isDirty(cwd = process.cwd()) {
 
 function getUncommittedCount(cwd = process.cwd()) {
   const result = git(['-C', cwd, 'status', '--porcelain']);
-  if (!result.stdout.trim()) return 0;
+  if (!result.stdout.trim()) {return 0;}
   return result.stdout.trim().split('\n').length;
 }
 

package/lib/core/gitignore.js

@@ -77,16 +77,18 @@ function ensureWorkflowGitignore(rootDir, options = {}) {
   try {
     existingContent = readFileSyncFn(gitignorePath, 'utf8');
   } catch (err) {
-    logFn(`[gitignore] Could not read ${gitignorePath}: ${err.message}`);
-    return { ok: false, created: false, appended: 0, skipped: false, reason: `read-error: ${err.message}` };
+    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
-      .map(line => line.trim())
-      .filter(line => line.length > 0 && !line.startsWith('#'))
+      /** @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