claude-code-swarm 0.0.1 → 0.3.3

package/references/opentasks/src/entire/utils/paths.ts

@@ -0,0 +1,59 @@
+/**
+ * Path Classification Helpers
+ *
+ * Utilities for classifying and normalizing paths within the Entire system.
+ *
+ * Ported from Go: paths/paths.go
+ */
+
+import * as path from 'node:path';
+import { ENTIRE_DIR } from '../types.js';
+
+/**
+ * Returns true if the path is part of Entire's infrastructure
+ * (i.e., inside the `.entire/` directory).
+ */
+export function isInfrastructurePath(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized === ENTIRE_DIR || normalized.startsWith(ENTIRE_DIR + '/');
+}
+
+/**
+ * Converts an absolute path to a repository-relative path.
+ * Returns empty string if the path is outside the working directory.
+ */
+export function toRelativePath(absPath: string, cwd: string): string {
+  if (!path.isAbsolute(absPath)) return absPath;
+
+  const relPath = path.relative(cwd, absPath);
+  if (relPath.startsWith('..')) return '';
+
+  return relPath;
+}
+
+/**
+ * Returns the absolute path for a relative path within the repository.
+ * If the path is already absolute, it is returned as-is.
+ */
+export function absPath(relPath: string, repoRoot: string): string {
+  if (path.isAbsolute(relPath)) return relPath;
+  return path.join(repoRoot, relPath);
+}
+
+/**
+ * Extract the session ID from a transcript file path.
+ * Expects paths like `/path/to/<sessionID>.jsonl` or `/path/to/<sessionID>.json`.
+ */
+export function extractSessionIDFromPath(transcriptPath: string): string {
+  const base = path.basename(transcriptPath);
+  // Remove extension (.jsonl, .json, etc.)
+  const dotIndex = base.indexOf('.');
+  return dotIndex > 0 ? base.slice(0, dotIndex) : base;
+}
+
+/**
+ * Returns the session metadata directory path for a given session ID.
+ */
+export function sessionMetadataDir(metadataRoot: string, sessionID: string): string {
+  return path.join(metadataRoot, 'sessions', sessionID);
+}

package/references/opentasks/src/entire/utils/preview-rewind.ts

@@ -0,0 +1,86 @@
+/**
+ * Rewind Preview
+ *
+ * Preview what files would change when rewinding to a checkpoint.
+ * Shows files that would be restored and untracked files that would be deleted.
+ *
+ * Ported from Go: strategy/manual_commit_rewind.go
+ */
+
+import {
+  git,
+  gitSafe,
+  getHead,
+  lsTree,
+  getUntrackedFiles,
+} from '../git-operations.js';
+import { isInfrastructurePath } from './paths.js';
+
+export interface RewindPreview {
+  filesToRestore: string[];
+  filesToDelete: string[];
+}
+
+/**
+ * Preview what will happen when rewinding to the given commit.
+ *
+ * Returns the list of files that would be restored from the checkpoint
+ * and untracked files that would be deleted.
+ *
+ * For logs-only rewind points, returns empty arrays since the working
+ * directory is not modified.
+ */
+export async function previewRewind(
+  commitHash: string,
+  isLogsOnly: boolean,
+  preservedUntrackedFiles?: string[],
+  cwd?: string,
+): Promise<RewindPreview> {
+  // Logs-only points don't modify the working directory
+  if (isLogsOnly) {
+    return { filesToRestore: [], filesToDelete: [] };
+  }
+
+  // Get files in the checkpoint tree (excluding infrastructure)
+  const checkpointEntries = await lsTree(commitHash, undefined, cwd);
+  const checkpointFiles = new Set<string>();
+  const filesToRestore: string[] = [];
+
+  for (const entry of checkpointEntries) {
+    if (!isInfrastructurePath(entry.name)) {
+      checkpointFiles.add(entry.name);
+      filesToRestore.push(entry.name);
+    }
+  }
+
+  // Get HEAD tree to identify tracked files
+  const headHash = await getHead(cwd);
+  const headEntries = await lsTree(headHash, undefined, cwd);
+  const trackedFiles = new Set<string>();
+  for (const entry of headEntries) {
+    trackedFiles.add(entry.name);
+  }
+
+  // Build set of preserved untracked files
+  const preserved = new Set(preservedUntrackedFiles ?? []);
+
+  // Find untracked files that would be deleted
+  const untrackedNow = await getUntrackedFiles(cwd);
+  const filesToDelete: string[] = [];
+
+  for (const relPath of untrackedNow) {
+    // Skip if file exists in the checkpoint
+    if (checkpointFiles.has(relPath)) continue;
+    // Skip if file is tracked in HEAD
+    if (trackedFiles.has(relPath)) continue;
+    // Skip if file was preserved from session start
+    if (preserved.has(relPath)) continue;
+
+    filesToDelete.push(relPath);
+  }
+
+  filesToRestore.sort();
+  filesToDelete.sort();
+
+  return { filesToRestore, filesToDelete };
+}

package/references/opentasks/src/entire/utils/rewind-conflict.ts

@@ -0,0 +1,121 @@
+/**
+ * Rewind Conflict Detection
+ *
+ * Utilities for detecting timestamp conflicts when restoring session logs
+ * from checkpoints. Prevents silent overwrites of newer local transcripts.
+ *
+ * Ported from Go: strategy/manual_commit_rewind.go
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export const enum SessionRestoreStatus {
+  /** Local file doesn't exist */
+  New = 0,
+  /** Local and checkpoint are the same */
+  Unchanged = 1,
+  /** Checkpoint has newer entries */
+  CheckpointNewer = 2,
+  /** Local has newer entries (conflict) */
+  LocalNewer = 3,
+}
+
+export interface SessionRestoreInfo {
+  sessionID: string;
+  prompt: string;
+  status: SessionRestoreStatus;
+  localTime: Date;
+  checkpointTime: Date;
+}
+
+// ============================================================================
+// Classification
+// ============================================================================
+
+/**
+ * Determine the restore status based on local and checkpoint timestamps.
+ */
+export function classifyTimestamps(
+  localTime: Date | null,
+  checkpointTime: Date | null,
+): SessionRestoreStatus {
+  // Local file doesn't exist
+  if (!localTime || localTime.getTime() === 0) {
+    return SessionRestoreStatus.New;
+  }
+
+  // Can't determine checkpoint time
+  if (!checkpointTime || checkpointTime.getTime() === 0) {
+    return SessionRestoreStatus.New;
+  }
+
+  if (localTime.getTime() > checkpointTime.getTime()) {
+    return SessionRestoreStatus.LocalNewer;
+  }
+  if (checkpointTime.getTime() > localTime.getTime()) {
+    return SessionRestoreStatus.CheckpointNewer;
+  }
+  return SessionRestoreStatus.Unchanged;
+}
+
+/**
+ * Returns a human-readable status string.
+ */
+export function statusToText(status: SessionRestoreStatus): string {
+  switch (status) {
+    case SessionRestoreStatus.New:
+      return '(new)';
+    case SessionRestoreStatus.Unchanged:
+      return '(unchanged)';
+    case SessionRestoreStatus.CheckpointNewer:
+      return '(checkpoint is newer)';
+    case SessionRestoreStatus.LocalNewer:
+      return '(local is newer)';
+    default:
+      return '';
+  }
+}
+
+/**
+ * Check if any sessions have conflicts (local is newer than checkpoint).
+ */
+export function hasConflicts(sessions: SessionRestoreInfo[]): boolean {
+  return sessions.some(s => s.status === SessionRestoreStatus.LocalNewer);
+}
+
+/**
+ * Separate sessions into conflicting and non-conflicting lists.
+ */
+export function partitionConflicts(sessions: SessionRestoreInfo[]): {
+  conflicting: SessionRestoreInfo[];
+  nonConflicting: SessionRestoreInfo[];
+} {
+  const conflicting: SessionRestoreInfo[] = [];
+  const nonConflicting: SessionRestoreInfo[] = [];
+  for (const s of sessions) {
+    if (s.status === SessionRestoreStatus.LocalNewer) {
+      conflicting.push(s);
+    } else {
+      nonConflicting.push(s);
+    }
+  }
+  return { conflicting, nonConflicting };
+}
+
+// ============================================================================
+// Agent Resolution
+// ============================================================================
+
+import type { Agent } from '../agent/types.js';
+import { getAgentByType } from '../agent/registry.js';
+import type { AgentType } from '../types.js';
+
+/**
+ * Resolve the agent from checkpoint metadata agent type string.
+ * Returns null if the agent type is not registered.
+ */
+export function resolveAgentForRewind(agentType: AgentType): Agent | null {
+  return getAgentByType(agentType);
+}

package/references/opentasks/src/entire/utils/shadow-branch.ts

@@ -0,0 +1,113 @@
+/**
+ * Shadow Branch Utilities
+ *
+ * Standalone utilities for shadow branch name generation, parsing,
+ * and classification. Extracted from checkpoint-store.ts for reuse.
+ *
+ * Ported from Go: checkpoint/temporary.go, strategy/cleanup.go
+ */
+
+import * as crypto from 'node:crypto';
+import {
+  SHADOW_BRANCH_PREFIX,
+  SHADOW_BRANCH_HASH_LENGTH,
+  CHECKPOINTS_BRANCH,
+} from '../types.js';
+import { listBranches, deleteBranch } from '../git-operations.js';
+
+/** Worktree ID hash length (6 hex characters) */
+const WORKTREE_ID_HASH_LENGTH = 6;
+
+/** Pattern for shadow branches: entire/<hex7+>(-<hex6+>)? */
+const SHADOW_BRANCH_PATTERN = new RegExp(
+  `^${SHADOW_BRANCH_PREFIX.replace('/', '\\/')}[0-9a-f]{${SHADOW_BRANCH_HASH_LENGTH},}(-[0-9a-f]{${WORKTREE_ID_HASH_LENGTH},})?$`,
+);
+
+/**
+ * Hash a worktree identifier to a short hex string.
+ */
+export function hashWorktreeID(worktreeID: string): string {
+  return crypto
+    .createHash('sha256')
+    .update(worktreeID)
+    .digest('hex')
+    .slice(0, WORKTREE_ID_HASH_LENGTH);
+}
+
+/**
+ * Returns the shadow branch name for a base commit hash and worktree identifier.
+ * Format: entire/<commit[:7]>-<hash(worktreeID)[:6]>
+ */
+export function shadowBranchNameForCommit(baseCommit: string, worktreeID?: string): string {
+  const commitPart = baseCommit.slice(0, SHADOW_BRANCH_HASH_LENGTH);
+  if (worktreeID) {
+    const worktreeHash = hashWorktreeID(worktreeID);
+    return `${SHADOW_BRANCH_PREFIX}${commitPart}-${worktreeHash}`;
+  }
+  return `${SHADOW_BRANCH_PREFIX}${commitPart}`;
+}
+
+/**
+ * Parse a shadow branch name to extract commit prefix and worktree hash.
+ * Returns null if the branch name doesn't match the shadow branch pattern.
+ */
+export function parseShadowBranchName(
+  branchName: string,
+): { commitPrefix: string; worktreeHash: string } | null {
+  if (!branchName.startsWith(SHADOW_BRANCH_PREFIX)) return null;
+  if (branchName === CHECKPOINTS_BRANCH) return null;
+
+  const suffix = branchName.slice(SHADOW_BRANCH_PREFIX.length);
+  const lastDash = suffix.lastIndexOf('-');
+
+  if (lastDash === -1 || lastDash === 0 || lastDash === suffix.length - 1) {
+    // No dash or dash at boundary — old format with just commit prefix
+    return { commitPrefix: suffix, worktreeHash: '' };
+  }
+
+  return {
+    commitPrefix: suffix.slice(0, lastDash),
+    worktreeHash: suffix.slice(lastDash + 1),
+  };
+}
+
+/**
+ * Returns true if the branch name matches the shadow branch pattern.
+ * The "entire/checkpoints/v1" branch is NOT a shadow branch.
+ */
+export function isShadowBranch(branchName: string): boolean {
+  if (branchName === CHECKPOINTS_BRANCH) return false;
+  return SHADOW_BRANCH_PATTERN.test(branchName);
+}
+
+/**
+ * List all shadow branches in the repository.
+ * Returns an empty array if no shadow branches exist.
+ */
+export async function listShadowBranches(cwd?: string): Promise<string[]> {
+  const allBranches = await listBranches(cwd);
+  return allBranches.filter(isShadowBranch);
+}
+
+/**
+ * Delete the specified shadow branches from the repository.
+ * Returns two arrays: successfully deleted and failed to delete.
+ */
+export async function deleteShadowBranches(
+  branches: string[],
+  cwd?: string,
+): Promise<{ deleted: string[]; failed: string[] }> {
+  const deleted: string[] = [];
+  const failed: string[] = [];
+
+  for (const branch of branches) {
+    try {
+      await deleteBranch(branch, false, cwd);
+      deleted.push(branch);
+    } catch {
+      failed.push(branch);
+    }
+  }
+
+  return { deleted, failed };
+}

package/references/opentasks/src/entire/utils/string-utils.ts

@@ -0,0 +1,46 @@
+/**
+ * String Utilities
+ *
+ * Rune-safe string operations for multi-byte character handling.
+ */
+
+/**
+ * Truncate a string to a maximum number of Unicode code points (runes).
+ * Avoids splitting multi-byte UTF-8 characters.
+ */
+export function truncateRunes(s: string, maxRunes: number, suffix: string = '...'): string {
+  const runes = [...s];
+  if (runes.length <= maxRunes) {
+    return s;
+  }
+  return runes.slice(0, maxRunes).join('') + suffix;
+}
+
+/**
+ * Collapse all whitespace sequences (including newlines) to single spaces.
+ */
+export function collapseWhitespace(s: string): string {
+  return s.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Capitalize the first character of a string.
+ */
+export function capitalizeFirst(s: string): string {
+  if (s.length === 0) return s;
+  return s[0].toUpperCase() + s.slice(1);
+}
+
+/**
+ * Count lines in a string.
+ * Empty string = 0 lines. String without newline = 1 line.
+ */
+export function countLines(content: string): number {
+  if (content === '') return 0;
+  let lines = 0;
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') lines++;
+  }
+  if (!content.endsWith('\n')) lines++;
+  return lines;
+}

package/references/opentasks/src/entire/utils/todo-extract.ts

@@ -0,0 +1,193 @@
+/**
+ * Todo Extraction
+ *
+ * Parses TodoWrite tool_input JSON to extract todo content for
+ * incremental checkpoint commit messages.
+ *
+ * Ported from Go: strategy/messages.go
+ */
+
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface TodoItem {
+  content: string;
+  activeForm?: string;
+  status: string;
+}
+
+// ============================================================================
+// Extraction Functions
+// ============================================================================
+
+/**
+ * Extract the content of the last completed todo item from a todos JSON array.
+ * Returns the work that was just finished (used for commit messages).
+ *
+ * Returns empty string if no completed items exist or JSON is invalid.
+ */
+export function extractLastCompletedTodo(todosJSON: string | Buffer): string {
+  const todos = parseTodos(todosJSON);
+  if (!todos) return '';
+
+  let lastCompleted = '';
+  for (const todo of todos) {
+    if (todo.status === 'completed') {
+      lastCompleted = todo.content;
+    }
+  }
+  return lastCompleted;
+}
+
+/**
+ * Return the number of todo items in the JSON array.
+ * Returns 0 if the JSON is invalid or empty.
+ */
+export function countTodos(todosJSON: string | Buffer): number {
+  const todos = parseTodos(todosJSON);
+  return todos ? todos.length : 0;
+}
+
+/**
+ * Extract the content of the in-progress todo item from tool_input.
+ * Used for commit messages in incremental checkpoints.
+ *
+ * Priority order:
+ *  1. in_progress item (current work)
+ *  2. first pending item (next work - fallback)
+ *  3. last completed item (work just finished)
+ *  4. first item with unknown status (edge case)
+ *  5. empty string (no items)
+ */
+export function extractInProgressTodo(todosJSON: string | Buffer): string {
+  const todos = parseTodos(todosJSON);
+  if (!todos || todos.length === 0) return '';
+
+  // 1. in_progress item
+  for (const todo of todos) {
+    if (todo.status === 'in_progress') {
+      return todo.content;
+    }
+  }
+
+  // 2. first pending item
+  for (const todo of todos) {
+    if (todo.status === 'pending') {
+      return todo.content;
+    }
+  }
+
+  // 3. last completed item
+  let lastCompleted = '';
+  for (const todo of todos) {
+    if (todo.status === 'completed') {
+      lastCompleted = todo.content;
+    }
+  }
+  if (lastCompleted) return lastCompleted;
+
+  // 4. first item with content (unknown status edge case)
+  if (todos[0].content) return todos[0].content;
+
+  return '';
+}
+
+// ============================================================================
+// Tool Input Wrappers
+// ============================================================================
+
+/**
+ * Extract todo content from a TodoWrite tool_input object.
+ * Handles unwrapping the outer { todos: [...] } structure.
+ */
+export function extractTodoContentFromToolInput(
+  toolInput: unknown,
+): string {
+  const todosJSON = extractTodosArrayJSON(toolInput);
+  if (!todosJSON) return '';
+  return extractInProgressTodo(todosJSON);
+}
+
+/**
+ * Extract last completed todo from a TodoWrite tool_input object.
+ */
+export function extractLastCompletedTodoFromToolInput(
+  toolInput: unknown,
+): string {
+  const todosJSON = extractTodosArrayJSON(toolInput);
+  if (!todosJSON) return '';
+  return extractLastCompletedTodo(todosJSON);
+}
+
+/**
+ * Count todos from a TodoWrite tool_input object.
+ */
+export function countTodosFromToolInput(toolInput: unknown): number {
+  const todosJSON = extractTodosArrayJSON(toolInput);
+  if (!todosJSON) return 0;
+  return countTodos(todosJSON);
+}
+
+// ============================================================================
+// Formatting
+// ============================================================================
+
+/** Maximum length for descriptions in commit messages */
+const MAX_DESCRIPTION_LENGTH = 60;
+
+/**
+ * Format a commit message for an incremental checkpoint.
+ * Format: "<todo-content> (<tool-use-id>)"
+ * Fallback: "Checkpoint #<sequence>: <tool-use-id>"
+ */
+export function formatIncrementalMessage(
+  todoContent: string,
+  sequence: number,
+  toolUseID: string,
+): string {
+  if (!todoContent) {
+    return `Checkpoint #${sequence}: ${toolUseID}`;
+  }
+
+  const truncated = truncateDescription(todoContent, MAX_DESCRIPTION_LENGTH);
+  return `${truncated} (${toolUseID})`;
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function parseTodos(todosJSON: string | Buffer): TodoItem[] | null {
+  try {
+    const str = typeof todosJSON === 'string' ? todosJSON : todosJSON.toString('utf-8');
+    if (!str) return null;
+    const parsed = JSON.parse(str) as unknown;
+    if (!Array.isArray(parsed)) return null;
+    return parsed as TodoItem[];
+  } catch {
+    return null;
+  }
+}
+
+function extractTodosArrayJSON(toolInput: unknown): string | null {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  const input = toolInput as Record<string, unknown>;
+  const todos = input.todos;
+  if (!Array.isArray(todos)) return null;
+  try {
+    return JSON.stringify(todos);
+  } catch {
+    return null;
+  }
+}
+
+function truncateDescription(s: string, maxLen: number): string {
+  const runes = [...s];
+  if (runes.length <= maxLen) return s;
+  const suffix = '...';
+  const suffixRunes = [...suffix];
+  const truncateAt = Math.max(0, maxLen - suffixRunes.length);
+  return runes.slice(0, truncateAt).join('') + suffix;
+}