gitspace 0.2.0-rc.1

package/src/types/workspace-fuzzy.ts

@@ -0,0 +1,49 @@
+/**
+ * Type definitions for workspace fuzzy matching
+ */
+
+/**
+ * A workspace candidate for fuzzy matching
+ */
+export interface WorkspaceCandidate {
+  /** Workspace name */
+  name: string;
+  /** Absolute path to workspace */
+  path: string;
+  /** Current git branch */
+  branch: string;
+  /** Commits ahead of remote */
+  ahead: number;
+  /** Commits behind remote */
+  behind: number;
+  /** Number of uncommitted changes */
+  uncommittedChanges: number;
+  /** Last commit message */
+  lastCommit: string;
+}
+
+/**
+ * Result of fuzzy matching
+ */
+export interface FuzzyMatch {
+  /** Original candidate item */
+  item: WorkspaceCandidate;
+  /** Match score (0-100, higher is better) */
+  score: number;
+  /** Indices of matched characters in item.name */
+  matchedIndices: number[];
+}
+
+/**
+ * Workspace with ranking information
+ */
+export interface RankedWorkspace {
+  /** Workspace candidate */
+  workspace: WorkspaceCandidate;
+  /** Fuzzy match score */
+  matchScore: number;
+  /** Final ranking score (includes bonuses) */
+  finalScore: number;
+  /** Character indices that matched */
+  matchedIndices: number[];
+}

package/src/types/workspace.ts

@@ -0,0 +1,151 @@
+/**
+ * Type definitions for workspace management
+ */
+
+/**
+ * Information about a git worktree workspace
+ */
+export interface WorktreeInfo {
+	/** Workspace name (directory name) */
+	name: string
+	/** Absolute path to the workspace directory */
+	path: string
+	/** Current git branch */
+	branch: string
+	/** Number of commits ahead of base branch */
+	ahead: number
+	/** Number of commits behind base branch */
+	behind: number
+	/** Number of uncommitted changes */
+	uncommittedChanges: number
+	/** Last commit message */
+	lastCommit: string
+	/** Last commit date */
+	lastCommitDate: Date
+}
+
+/**
+ * Project information for listing
+ */
+export interface ProjectInfo {
+	/** Project name */
+	name: string
+	/** GitHub repository (owner/repo) */
+	repository: string
+	/** Absolute path to project directory */
+	path: string
+	/** Number of workspaces in this project */
+	workspaceCount: number
+	/** Whether this is the current project */
+	isCurrent: boolean
+}
+
+/**
+ * Dependency information
+ */
+export interface Dependency {
+	/** Display name of the dependency */
+	name: string
+	/** Command to check (e.g., "gh", "git") */
+	command: string
+	/** Arguments to run for version check */
+	checkArgs: string[]
+	/** URL for installation instructions */
+	installUrl: string
+	/** Optional custom auth check function */
+	authCheck?: () => Promise<boolean>
+}
+
+/**
+ * Options for creating a workspace
+ */
+export interface CreateWorkspaceOptions {
+	/** Workspace name */
+	name: string
+	/** Branch name (defaults to workspace name) */
+	branchName?: string
+	/** Base branch to create from (defaults to project base branch) */
+	fromBranch?: string
+	/** Whether to skip opening interactive shell */
+	noShell?: boolean
+	/** Whether to skip running setup commands */
+	noSetup?: boolean
+}
+
+/**
+ * Label attached to an issue
+ */
+export interface Label {
+	/** Unique identifier for the label */
+	id: string
+	/** Display name of the label */
+	name: string
+	/** Hex color code for the label */
+	color: string
+}
+
+/**
+ * User assigned to an issue
+ */
+export interface User {
+	/** Unique identifier for the user */
+	id: string
+	/** Display name of the user */
+	name: string
+	/** Email address of the user */
+	email: string
+}
+
+/**
+ * Issue state information
+ */
+export interface IssueState {
+	/** Unique identifier for the state */
+	id: string
+	/** Display name of the state (e.g., "In Progress", "Done") */
+	name: string
+	/** State type (e.g., "started", "completed", "canceled") */
+	type: string
+}
+
+/**
+ * Linear issue attachment
+ */
+export interface LinearAttachment {
+	/** Unique identifier for the attachment */
+	id: string
+	/** URL to the attachment */
+	url: string
+	/** Title of the attachment */
+	title: string | null
+	/** Source type (e.g., "upload", "url") */
+	sourceType: string | null
+	/** Creation timestamp */
+	createdAt: Date
+}
+
+/**
+ * Linear issue for workspace creation
+ */
+export interface LinearIssue {
+	/** Issue ID */
+	id: string
+	/** Issue identifier (e.g., "ENG-123") */
+	identifier: string
+	/** Issue title */
+	title: string
+	/** Issue state */
+	state: Promise<IssueState> | undefined
+	/** Issue description/body (can be null) */
+	description: string | null
+	/** Web URL to view the issue */
+	url: string
+	/** User assigned to the issue (null if unassigned) */
+	assignee: Promise<User> | undefined
+	/** Timestamp when issue was created */
+	createdAt: Date
+	/** Timestamp when issue was last updated */
+	updatedAt: Date
+	/** Issue attachments (images, files, etc.) - lazy-loaded function */
+	attachments: () => Promise<LinearAttachment[]>
+}

package/src/utils/bun-socket-writer.ts

@@ -0,0 +1,80 @@
+import type { Socket } from "bun";
+
+type WritableData = Buffer | Uint8Array | ArrayBuffer;
+
+/**
+ * Bun sockets are unbuffered. `socket.write()` can write fewer bytes than provided
+ * under backpressure. For framed protocols, partial writes will desync the reader.
+ *
+ * This helper buffers pending bytes and flushes them when the socket drains.
+ */
+export function createBufferedSocketWriter(socket: Socket<any>) {
+  const queue: Buffer[] = [];
+  let headOffset = 0;
+
+  const flush = () => {
+    while (queue.length > 0) {
+      const head = queue[0]!;
+      const remaining = head.length - headOffset;
+
+      if (remaining <= 0) {
+        queue.shift();
+        headOffset = 0;
+        continue;
+      }
+
+      const written = socket.write(head, headOffset, remaining);
+
+      // -1: closed/shutting down. 0: backpressure.
+      if (written <= 0) return;
+
+      headOffset += written;
+      if (headOffset >= head.length) {
+        queue.shift();
+        headOffset = 0;
+      }
+    }
+  };
+
+  const write = (data: WritableData) => {
+    // Copy into a stable Buffer (avoids subarray lifetime issues and ensures queue owns bytes)
+    const buf = Buffer.from(data as any);
+
+    // Fast-path if nothing queued.
+    if (queue.length === 0) {
+      const written = socket.write(buf);
+
+      if (written <= 0) {
+        queue.push(buf);
+        headOffset = 0;
+        return;
+      }
+
+      if (written >= buf.length) return;
+
+      queue.push(buf);
+      headOffset = written;
+      return;
+    }
+
+    queue.push(buf);
+    flush();
+  };
+
+  const clear = () => {
+    queue.length = 0;
+    headOffset = 0;
+  };
+
+  const pendingBytes = () => {
+    let total = 0;
+    for (let i = 0; i < queue.length; i++) total += queue[i]!.length;
+    return Math.max(0, total - headOffset);
+  };
+
+  return { write, flush, clear, pendingBytes };
+}
+
+
+
+

package/src/utils/deps.ts

@@ -0,0 +1,127 @@
+/**
+ * Dependency checking utilities
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import type { Dependency } from '../types/workspace.js';
+import { DependencyError, GitHubAuthError } from '../types/errors.js';
+import { logger } from './logger.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * Required system dependencies
+ */
+export const REQUIRED_DEPS: Dependency[] = [
+  {
+    name: 'GitHub CLI',
+    command: 'gh',
+    checkArgs: ['--version'],
+    installUrl: 'https://cli.github.com/',
+    authCheck: async () => {
+      try {
+        await execAsync('gh auth status');
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  },
+  {
+    name: 'Git',
+    command: 'git',
+    checkArgs: ['--version'],
+    installUrl: 'https://git-scm.com/',
+  },
+  {
+    name: 'jq',
+    command: 'jq',
+    checkArgs: ['--version'],
+    installUrl: 'https://stedolan.github.io/jq/',
+  },
+];
+
+/**
+ * Check if a command exists
+ */
+async function commandExists(command: string, checkArgs: string[]): Promise<boolean> {
+  try {
+    await execAsync(`${command} ${checkArgs.join(' ')}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check all required dependencies
+ */
+export async function checkDependencies(deps: Dependency[] = REQUIRED_DEPS): Promise<{
+  missing: Dependency[];
+  allPresent: boolean;
+}> {
+  const missing: Dependency[] = [];
+
+  for (const dep of deps) {
+    const exists = await commandExists(dep.command, dep.checkArgs);
+    if (!exists) {
+      missing.push(dep);
+    }
+  }
+
+  return {
+    missing,
+    allPresent: missing.length === 0,
+  };
+}
+
+/**
+ * Check GitHub CLI authentication
+ */
+export async function checkGitHubAuth(): Promise<void> {
+  const ghDep = REQUIRED_DEPS.find((d) => d.command === 'gh');
+  if (!ghDep?.authCheck) {
+    return;
+  }
+
+  const isAuthenticated = await ghDep.authCheck();
+  if (!isAuthenticated) {
+    throw new GitHubAuthError();
+  }
+}
+
+/**
+ * Display missing dependencies and exit
+ */
+export function displayMissingDependencies(missing: Dependency[]): never {
+  logger.error('Missing required dependencies:\n');
+
+  for (const dep of missing) {
+    logger.log(`  ${dep.name} (${dep.command})`);
+    logger.dim(`    Install: ${dep.installUrl}\n`);
+  }
+
+  throw new DependencyError(
+    'Please install the missing dependencies and try again.'
+  );
+}
+
+/**
+ * Check dependencies and throw if any are missing
+ */
+export async function ensureDependencies(deps?: Dependency[]): Promise<void> {
+  const { missing, allPresent } = await checkDependencies(deps);
+
+  if (!allPresent) {
+    displayMissingDependencies(missing);
+  }
+}
+
+/**
+ * Check specific dependencies (subset of all required)
+ */
+export async function checkSpecificDeps(commands: string[]): Promise<void> {
+  const depsToCheck = REQUIRED_DEPS.filter((d) => commands.includes(d.command));
+  await ensureDependencies(depsToCheck);
+}

package/src/utils/fuzzy-match.ts

@@ -0,0 +1,125 @@
+/**
+ * Fuzzy matching algorithm
+ * Matches query against candidates and returns scored results
+ */
+
+import type { FuzzyMatch, WorkspaceCandidate } from '../types/workspace-fuzzy.js';
+
+/**
+ * Perform fuzzy matching on workspace candidates
+ *
+ * Algorithm:
+ * 1. For each candidate, calculate match score
+ * 2. Filter out scores below threshold (30)
+ * 3. Sort by score descending
+ *
+ * @param query Search string
+ * @param candidates List of workspace candidates
+ * @returns Sorted array of matches with scores
+ */
+export function fuzzyMatch(
+  query: string,
+  candidates: WorkspaceCandidate[]
+): FuzzyMatch[] {
+  const matches: FuzzyMatch[] = [];
+
+  for (const candidate of candidates) {
+    const result = calculateMatchScore(query, candidate.name);
+
+    if (result.score >= 30) {  // Minimum threshold
+      matches.push({
+        item: candidate,
+        score: result.score,
+        matchedIndices: result.matchedIndices,
+      });
+    }
+  }
+
+  // Sort by score descending
+  matches.sort((a, b) => b.score - a.score);
+
+  return matches;
+}
+
+/**
+ * Calculate fuzzy match score between query and candidate
+ *
+ * Scoring rules:
+ * - All query characters must exist in order: otherwise score = 0
+ * - Consecutive character matches: +10 points per consecutive char
+ * - Word boundary matches: +5 points (e.g., "fb" matches "feature-branch")
+ * - Exact case match: +2 points per char
+ * - Start of string match: +15 points
+ * - Character proximity: -1 point per gap
+ * - Base score: 50 points if all chars match
+ *
+ * @param query Search string
+ * @param candidate String to match against
+ * @returns Object with score and matched character indices
+ */
+function calculateMatchScore(
+  query: string,
+  candidate: string
+): { score: number; matchedIndices: number[] } {
+  if (!query || !candidate) {
+    return { score: 0, matchedIndices: [] };
+  }
+
+  const queryLower = query.toLowerCase();
+  const candidateLower = candidate.toLowerCase();
+
+  // Find all query characters in candidate
+  const matchedIndices: number[] = [];
+  let candidateIndex = 0;
+
+  for (let i = 0; i < queryLower.length; i++) {
+    const queryChar = queryLower[i];
+    const foundIndex = candidateLower.indexOf(queryChar, candidateIndex);
+
+    if (foundIndex === -1) {
+      // Character not found - no match
+      return { score: 0, matchedIndices: [] };
+    }
+
+    matchedIndices.push(foundIndex);
+    candidateIndex = foundIndex + 1;
+  }
+
+  // All characters matched - start with base score
+  let score = 50;
+
+  // Bonus: Start of string match
+  if (matchedIndices[0] === 0) {
+    score += 15;
+  }
+
+  // Calculate bonuses for consecutive matches, word boundaries, and case
+  for (let i = 0; i < matchedIndices.length; i++) {
+    const index = matchedIndices[i];
+    const queryChar = query[i];
+    const candidateChar = candidate[index];
+
+    // Consecutive match bonus
+    if (i > 0 && matchedIndices[i] === matchedIndices[i - 1] + 1) {
+      score += 10;
+    }
+
+    // Word boundary bonus (after -, _, /, or at start)
+    if (index === 0 || ['-', '_', '/'].includes(candidate[index - 1])) {
+      score += 5;
+    }
+
+    // Exact case match bonus
+    if (queryChar === candidateChar) {
+      score += 2;
+    }
+
+    // Proximity penalty (gap between matched characters)
+    if (i > 0) {
+      const gap = matchedIndices[i] - matchedIndices[i - 1] - 1;
+      score -= gap;  // -1 point per character gap
+    }
+  }
+
+  return { score, matchedIndices };
+}

package/src/utils/logger.ts

@@ -0,0 +1,127 @@
+/**
+ * Logging utilities with chalk for colored output
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Log levels
+ */
+export type LogLevel = 'info' | 'success' | 'warning' | 'error' | 'debug';
+
+/**
+ * Logger instance
+ */
+class Logger {
+  private debugMode: boolean = false;
+
+  /**
+   * Enable or disable debug mode
+   */
+  setDebugMode(enabled: boolean): void {
+    this.debugMode = enabled;
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message: string): void {
+    console.log(chalk.blue('ℹ'), message);
+  }
+
+  /**
+   * Log a success message
+   */
+  success(message: string): void {
+    console.log(chalk.green('✓'), message);
+  }
+
+  /**
+   * Log a warning message
+   */
+  warning(message: string): void {
+    console.log(chalk.yellow('⚠'), message);
+  }
+
+  /**
+   * Log an error message
+   */
+  error(message: string): void {
+    console.error(chalk.red('✗'), message);
+  }
+
+  /**
+   * Log a debug message (only if debug mode is enabled)
+   */
+  debug(message: string): void {
+    if (this.debugMode) {
+      console.log(chalk.gray('DEBUG:'), message);
+    }
+  }
+
+  /**
+   * Log a message without any prefix
+   */
+  log(message: string): void {
+    console.log(message);
+  }
+
+  /**
+   * Log a dim/muted message
+   */
+  dim(message: string): void {
+    console.log(chalk.dim(message));
+  }
+
+  /**
+   * Log a bold message
+   */
+  bold(message: string): void {
+    console.log(chalk.bold(message));
+  }
+
+  /**
+   * Create a spinner-like loading message
+   */
+  loading(message: string): () => void {
+    process.stdout.write(chalk.blue('⠋') + ' ' + message);
+
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    let i = 0;
+
+    const interval = setInterval(() => {
+      process.stdout.write('\r' + chalk.blue(frames[i]) + ' ' + message);
+      i = (i + 1) % frames.length;
+    }, 80);
+
+    // Return a function to stop the spinner
+    return () => {
+      clearInterval(interval);
+      process.stdout.write('\r' + ' '.repeat(message.length + 2) + '\r');
+    };
+  }
+
+  /**
+   * Format a command for display
+   */
+  command(cmd: string): string {
+    return chalk.cyan(cmd);
+  }
+
+  /**
+   * Format a path for display
+   */
+  path(path: string): string {
+    return chalk.magenta(path);
+  }
+
+  /**
+   * Format a highlight for display
+   */
+  highlight(text: string): string {
+    return chalk.yellow(text);
+  }
+}
+
+// Export singleton instance
+export const logger = new Logger();