gitspace 0.2.0-rc.1

package/src/core/linear.ts

@@ -0,0 +1,225 @@
+/**
+ * Linear API integration for issue management
+ */
+
+import { LinearClient, LinearError, type Issue } from '@linear/sdk'
+import { SpacesError } from '../types/errors.js'
+import { logger } from '../utils/logger.js'
+import type { LinearIssue } from '../types/workspace.js'
+
+/**
+ * Singleton Linear client instance
+ */
+let clientInstance: LinearClient | null = null
+
+/**
+ * Get or create Linear client instance
+ */
+function getLinearClient(apiKey: string): LinearClient {
+	if (!clientInstance) {
+		clientInstance = new LinearClient({ apiKey })
+	}
+	return clientInstance
+}
+
+/**
+ * Reset the Linear client (useful when API key changes)
+ */
+export function resetLinearClient(): void {
+	clientInstance = null
+}
+
+/**
+ * Custom error class for Linear API errors
+ */
+export class LinearAPIError extends SpacesError {
+	constructor(message: string, originalError?: unknown) {
+		super(message, 'SERVICE_ERROR', 3)
+		this.name = 'LinearAPIError'
+
+		if (originalError) {
+			logger.debug(`Linear API error: ${originalError}`)
+		}
+	}
+}
+
+/**
+ * Retry a function with exponential backoff
+ */
+async function fetchWithRetry<T>(
+	fetchFn: () => Promise<T>,
+	maxRetries = 3
+): Promise<T> {
+	let lastError: unknown
+
+	for (let attempt = 0; attempt < maxRetries; attempt++) {
+		try {
+			return await fetchFn()
+		} catch (error: unknown) {
+			lastError = error
+
+			// Check if it's a retryable error (429 or 5xx)
+			let shouldRetry = false
+			let statusCode: number | undefined
+
+			if (error instanceof LinearError) {
+				// @ts-ignore - response may or may not have status
+				statusCode = error.response?.status
+			}
+
+			if (statusCode === 429 || (statusCode && statusCode >= 500)) {
+				shouldRetry = true
+			}
+
+			if (shouldRetry && attempt < maxRetries - 1) {
+				// Exponential backoff: 200ms, 400ms, 800ms
+				const delay = 200 * Math.pow(2, attempt)
+				await new Promise((resolve) => setTimeout(resolve, delay))
+				continue
+			}
+
+			throw error
+		}
+	}
+
+	throw lastError
+}
+
+/**
+ * Fetch all pages from a paginated Linear SDK response
+ */
+async function fetchAllPages<T extends { id: string }>(initialPage: {
+	nodes: T[]
+	pageInfo: { hasNextPage: boolean }
+	fetchNext?: () => Promise<{ nodes: T[]; pageInfo: { hasNextPage: boolean } }>
+}): Promise<T[]> {
+	const allItems: T[] = []
+	const seenIds = new Set<string>()
+	let currentPage = initialPage
+
+	while (true) {
+		// Add unique items
+		for (const item of currentPage.nodes) {
+			if (!seenIds.has(item.id)) {
+				seenIds.add(item.id)
+				allItems.push(item)
+			}
+		}
+
+		if (!currentPage.pageInfo.hasNextPage || !currentPage.fetchNext) {
+			break
+		}
+
+		currentPage = await currentPage.fetchNext()
+	}
+
+	return allItems
+}
+
+/**
+ * Fetch unstarted issues from Linear
+ * @param apiKey Linear API key
+ * @param teamKey Optional team key to filter by (e.g., "ENG")
+ * @returns Array of unstarted issues
+ */
+export async function fetchUnstartedIssues(
+	apiKey: string,
+	teamKey?: string
+): Promise<LinearIssue[]> {
+	try {
+		return await fetchWithRetry(async () => {
+			const client = getLinearClient(apiKey)
+
+			// Build filter for unstarted issues
+			const filter = {
+				state: { type: { eq: 'unstarted' } },
+			}
+
+			let linearIssues: Issue[]
+
+			if (teamKey) {
+				// Fetch team first
+				const teamsConnection = await client.teams({
+					filter: { key: { eq: teamKey } },
+				})
+
+				const team = teamsConnection.nodes[0]
+
+				if (!team) {
+					throw new LinearAPIError(`Team with key "${teamKey}" not found`)
+				}
+
+				// Fetch issues for the team
+				const issuesConnection = await team.issues({ filter })
+				linearIssues = await fetchAllPages(issuesConnection)
+			} else {
+				// Fetch all unstarted issues
+				const issuesConnection = await client.issues({ filter })
+				linearIssues = await fetchAllPages(issuesConnection)
+			}
+
+			const convertedIssues: LinearIssue[] = []
+			for (let i = 0; i < linearIssues.length; i++) {
+				const issue = linearIssues[i]
+
+				// Create a lazy function for attachments (only fetched when called)
+				const attachments = async () => {
+					const attachmentsConnection = await issue.attachments()
+					const linearAttachments = await fetchAllPages(attachmentsConnection)
+
+					// Convert to our attachment format
+					return linearAttachments.map((att) => ({
+						id: att.id,
+						url: att.url,
+						title: att.title ?? null,
+						sourceType: att.sourceType ?? null,
+						createdAt: att.createdAt,
+					}))
+				}
+
+				convertedIssues.push({
+					id: issue.id,
+					identifier: issue.identifier,
+					title: issue.title,
+					description: issue.description ?? null,
+					state: issue.state,
+					url: issue.url,
+					assignee: issue.assignee,
+					createdAt: issue.createdAt,
+					updatedAt: issue.updatedAt,
+					attachments,
+				})
+			}
+
+			return convertedIssues
+		})
+	} catch (error) {
+		if (error instanceof LinearAPIError) {
+			throw error
+		}
+
+		if (error instanceof LinearError) {
+			throw new LinearAPIError(`Linear API error: ${error.message}`, error)
+		}
+
+		throw new LinearAPIError(
+			`Failed to fetch Linear issues: ${
+				error instanceof Error ? error.message : 'Unknown error'
+			}`,
+			error
+		)
+	}
+}
+
+/**
+ * Validate a Linear API key
+ */
+export async function validateLinearApiKey(apiKey: string): Promise<boolean> {
+	try {
+		const testClient = new LinearClient({ apiKey })
+		await testClient.viewer
+		return true
+	} catch {
+		return false
+	}
+}

package/src/core/shell.ts

@@ -0,0 +1,161 @@
+/**
+ * Shell session management - spawns subshells for workspaces
+ * Uses tmux-lite for session persistence and management
+ */
+
+import { spawn, spawnSync } from 'child_process'
+import { logger } from '../utils/logger.js'
+import { hasSetupBeenRun, markSetupComplete } from '../utils/workspace-state.js'
+import { runScriptsInTerminal, type RunScriptsOptions } from '../utils/run-scripts.js'
+import { getScriptsPhaseDir, readProjectConfig } from './config.js'
+import { getProjectSecrets } from '../utils/secrets.js'
+import {
+	listSessions,
+	createSession,
+	isNested,
+	type Session,
+} from '../lib/tmux-lite/cli.js'
+
+/**
+ * Print a message to terminal using echo (same mechanism as scripts)
+ */
+function printToTerminal(message: string): void {
+	spawnSync('echo', [message], { stdio: 'inherit' })
+}
+
+/**
+ * Open a workspace in an interactive subshell
+ *
+ * Flow:
+ * 1. Determine if setup or select scripts should run
+ * 2. Run the appropriate scripts in the terminal
+ * 3. Spawn an interactive subshell in the workspace directory
+ * 4. User gets control of the shell with their environment ready
+ *
+ * @param selectOnly - If true, only run select scripts (skip setup check). Used by TUI which handles setup during creation.
+ * @param sessionName - Custom name for the tmux-lite session (required for new sessions)
+ */
+export async function openWorkspaceShell(
+	workspacePath: string,
+	projectName: string,
+	repository: string,
+	noSetup: boolean = false,
+	selectOnly: boolean = false,
+	sessionName?: string
+): Promise<void> {
+	const workspaceName = workspacePath.split('/').pop() || 'workspace'
+
+	// Build script options with bundle values and secrets
+	const projectConfig = readProjectConfig(projectName)
+	const scriptOptions: RunScriptsOptions = {
+		bundleValues: projectConfig.bundleValues,
+	}
+
+	// Fetch secrets from OS keychain if we have secret keys
+	if (projectConfig.bundleSecretKeys && projectConfig.bundleSecretKeys.length > 0) {
+		scriptOptions.bundleSecrets = await getProjectSecrets(projectName, projectConfig.bundleSecretKeys)
+	}
+
+	if (selectOnly) {
+		// TUI mode: setup was done during creation, just run select scripts
+		const selectScriptsDir = getScriptsPhaseDir(projectName, 'select')
+		await runScriptsInTerminal(
+			selectScriptsDir,
+			workspacePath,
+			workspaceName,
+			repository,
+			scriptOptions
+		)
+	} else {
+		const setupAlreadyRun = hasSetupBeenRun(workspacePath)
+
+		// Determine which scripts to run based on setup status
+		if (setupAlreadyRun) {
+			// Setup has been run before, run select scripts
+			const selectScriptsDir = getScriptsPhaseDir(projectName, 'select')
+			await runScriptsInTerminal(
+				selectScriptsDir,
+				workspacePath,
+				workspaceName,
+				repository,
+				scriptOptions
+			)
+		} else if (!noSetup) {
+			// First time setup, run setup scripts
+			printToTerminal('Running setup scripts (first time)...')
+			const setupScriptsDir = getScriptsPhaseDir(projectName, 'setup')
+			await runScriptsInTerminal(
+				setupScriptsDir,
+				workspacePath,
+				workspaceName,
+				repository,
+				scriptOptions
+			)
+
+			// Mark setup as complete
+			markSetupComplete(workspacePath)
+			printToTerminal('✓ Setup complete')
+		}
+	}
+
+	printToTerminal('')
+	printToTerminal('💡 Press Ctrl+Esc to detach and return to GitSpace TUI')
+	printToTerminal('')
+
+	// Create or attach to tmux-lite session
+	await openTmuxLiteSession(workspacePath, projectName, workspaceName, sessionName)
+}
+
+/**
+ * Build a full session name from components
+ */
+function buildSessionName(projectName: string, workspaceName: string, sessionName: string): string {
+	return `${projectName}:${workspaceName}:${sessionName}`
+}
+
+/**
+ * Open a tmux-lite session for the workspace
+ * Creates a new session or attaches to an existing one
+ * @param sessionName - Custom name for the session (required)
+ */
+async function openTmuxLiteSession(
+	workspacePath: string,
+	projectName: string,
+	workspaceName: string,
+	sessionName?: string
+): Promise<void> {
+	// Check if we're already in a tmux-lite session
+	if (isNested()) {
+		logger.error('Already inside a tmux-lite session. Detach first with Ctrl+Esc.')
+		return
+	}
+
+	try {
+		// Build the full session name
+		if (!sessionName) {
+			throw new Error('Session name is required')
+		}
+		const fullSessionName = buildSessionName(projectName, workspaceName, sessionName)
+
+		logger.debug(`Creating tmux-lite session: ${fullSessionName}`)
+
+		// Create new session
+		const session = await createSession(fullSessionName, workspacePath)
+
+		// Spawn the CLI attach command as a subprocess with inherited stdio
+		// This works better with TUI suspension than direct attach() call
+		const cliPath = new URL('../lib/tmux-lite/cli.ts', import.meta.url).pathname
+		const proc = spawn('bun', ['run', cliPath, 'attach', session.id, '-f'], {
+			stdio: 'inherit',
+			cwd: workspacePath,
+		})
+
+		await new Promise<void>((resolve, reject) => {
+			proc.on('exit', () => resolve())
+			proc.on('error', (err) => reject(err))
+		})
+	} catch (error) {
+		logger.error(`Failed to open tmux-lite session: ${(error as Error).message}`)
+		throw error
+	}
+}

package/src/core/trusted-relays.ts

@@ -0,0 +1,315 @@
+/**
+ * Trusted relay management
+ *
+ * Manages the list of relays this machine trusts for remote connections.
+ * Relays are identified by their URL and Ed25519 public key.
+ *
+ * Storage: ~/.gitspace/.identity/trusted-relays.json
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { getIdentityDir } from "./identity.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * A trusted relay entry
+ */
+export interface TrustedRelay {
+  /** Relay WebSocket URL (e.g., wss://relay.example.com) */
+  url: string;
+  /** Ed25519 signing public key (base64) */
+  publicKey: string;
+  /** Human-readable fingerprint */
+  fingerprint: string;
+  /** Optional label from relay */
+  label?: string;
+  /** When trust was established (Unix ms) */
+  trustedAt: number;
+}
+
+/**
+ * Result of checking relay trust status
+ */
+export type RelayTrustStatus = "trusted" | "mismatch" | "unknown";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const TRUSTED_RELAYS_FILE = "trusted-relays.json";
+
+// ============================================================================
+// Paths
+// ============================================================================
+
+/**
+ * Get path to trusted relays file
+ */
+function getTrustedRelaysPath(): string {
+  return join(getIdentityDir(), TRUSTED_RELAYS_FILE);
+}
+
+// ============================================================================
+// Fingerprint Computation
+// ============================================================================
+
+/**
+ * Compute fingerprint from relay public key
+ *
+ * Format: "Kx4f:2nB9:mP3q:vR8s" (16 chars with colons)
+ */
+export function computeRelayFingerprint(publicKey: string): string {
+  const keyBytes = Buffer.from(publicKey, "base64");
+  const hash = sha256(keyBytes);
+  const b64url = Buffer.from(hash).toString("base64url").substring(0, 16);
+  return b64url.match(/.{1,4}/g)?.join(":") || b64url;
+}
+
+// ============================================================================
+// URL Normalization
+// ============================================================================
+
+/**
+ * Normalize a relay URL for consistent comparison
+ *
+ * Removes trailing slashes and normalizes protocol
+ */
+function normalizeUrl(url: string): string {
+  // Normalize the URL
+  let normalized = url.toLowerCase().trim();
+
+  // Remove trailing slashes
+  while (normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  // Normalize ws:// to wss:// for non-localhost
+  if (normalized.startsWith("ws://") && !isLocalhostUrl(normalized)) {
+    normalized = "wss://" + normalized.slice(5);
+  }
+
+  return normalized;
+}
+
+/**
+ * Check if URL is localhost
+ */
+function isLocalhostUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname.toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "::1";
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Storage Operations
+// ============================================================================
+
+/**
+ * Load trusted relays from disk
+ */
+export function getTrustedRelays(): TrustedRelay[] {
+  const path = getTrustedRelaysPath();
+
+  if (!existsSync(path)) {
+    return [];
+  }
+
+  try {
+    const content = readFileSync(path, "utf-8");
+    return JSON.parse(content) as TrustedRelay[];
+  } catch {
+    console.warn("[trusted-relays] Failed to parse trusted relays file");
+    return [];
+  }
+}
+
+/**
+ * Save trusted relays to disk
+ */
+function saveTrustedRelays(relays: TrustedRelay[]): void {
+  const identityDir = getIdentityDir();
+
+  // Create directory if needed (should already exist from identity setup)
+  if (!existsSync(identityDir)) {
+    const { mkdirSync } = require("node:fs");
+    mkdirSync(identityDir, { recursive: true, mode: 0o700 });
+  }
+
+  writeFileSync(
+    getTrustedRelaysPath(),
+    JSON.stringify(relays, null, 2),
+    { encoding: "utf-8", mode: 0o600 }
+  );
+}
+
+// ============================================================================
+// Trust Management
+// ============================================================================
+
+/**
+ * Add a relay to the trusted list
+ *
+ * If the URL already exists, updates the public key and label.
+ *
+ * @param url - Relay WebSocket URL
+ * @param publicKey - Ed25519 public key (base64)
+ * @param label - Optional relay label
+ * @returns The created/updated entry
+ */
+export function addTrustedRelay(
+  url: string,
+  publicKey: string,
+  label?: string
+): TrustedRelay {
+  const relays = getTrustedRelays();
+  const normalizedUrl = normalizeUrl(url);
+
+  // Check if already exists by URL
+  const existing = relays.find((r) => normalizeUrl(r.url) === normalizedUrl);
+
+  if (existing) {
+    // Update existing entry
+    existing.publicKey = publicKey;
+    existing.fingerprint = computeRelayFingerprint(publicKey);
+    existing.label = label ?? existing.label;
+    existing.trustedAt = Date.now();
+    saveTrustedRelays(relays);
+    return existing;
+  }
+
+  // Create new entry
+  const entry: TrustedRelay = {
+    url: normalizedUrl,
+    publicKey,
+    fingerprint: computeRelayFingerprint(publicKey),
+    label,
+    trustedAt: Date.now(),
+  };
+
+  relays.push(entry);
+  saveTrustedRelays(relays);
+
+  return entry;
+}
+
+/**
+ * Remove a relay from the trusted list
+ *
+ * @param urlOrFingerprint - URL or fingerprint (or prefix) to match
+ * @returns The removed entry, or null if not found
+ */
+export function removeTrustedRelay(
+  urlOrFingerprint: string
+): TrustedRelay | null {
+  const relays = getTrustedRelays();
+  const searchLower = urlOrFingerprint.toLowerCase();
+
+  const index = relays.findIndex((r) => {
+    const urlLower = normalizeUrl(r.url);
+    const fingerprintLower = r.fingerprint.toLowerCase();
+    const labelLower = r.label?.toLowerCase();
+
+    return (
+      urlLower === searchLower ||
+      urlLower.includes(searchLower) ||
+      fingerprintLower === searchLower ||
+      fingerprintLower.startsWith(searchLower) ||
+      labelLower === searchLower
+    );
+  });
+
+  if (index === -1) {
+    return null;
+  }
+
+  const [removed] = relays.splice(index, 1);
+  saveTrustedRelays(relays);
+
+  return removed;
+}
+
+/**
+ * Get a trusted relay by URL
+ *
+ * @param url - Relay WebSocket URL
+ * @returns The relay entry if found, null otherwise
+ */
+export function getTrustedRelay(url: string): TrustedRelay | null {
+  const relays = getTrustedRelays();
+  const normalizedUrl = normalizeUrl(url);
+
+  return relays.find((r) => normalizeUrl(r.url) === normalizedUrl) ?? null;
+}
+
+/**
+ * Find a trusted relay by fingerprint or label
+ *
+ * @param fingerprintOrLabel - Fingerprint (or prefix) or label to match
+ * @returns The relay entry if found, null otherwise
+ */
+export function findTrustedRelay(
+  fingerprintOrLabel: string
+): TrustedRelay | null {
+  const relays = getTrustedRelays();
+  const searchLower = fingerprintOrLabel.toLowerCase();
+
+  return (
+    relays.find((r) => {
+      const fingerprintLower = r.fingerprint.toLowerCase();
+      const labelLower = r.label?.toLowerCase();
+
+      return (
+        fingerprintLower === searchLower ||
+        fingerprintLower.startsWith(searchLower) ||
+        labelLower === searchLower
+      );
+    }) ?? null
+  );
+}
+
+/**
+ * Check if a relay is trusted
+ *
+ * @param url - Relay WebSocket URL
+ * @param publicKey - Ed25519 public key (base64) from relay
+ * @returns Trust status: 'trusted', 'mismatch', or 'unknown'
+ */
+export function isRelayTrusted(
+  url: string,
+  publicKey: string
+): RelayTrustStatus {
+  // Localhost is always auto-trusted
+  if (isLocalhostUrl(url)) {
+    return "trusted";
+  }
+
+  const trustedRelay = getTrustedRelay(url);
+
+  if (!trustedRelay) {
+    return "unknown";
+  }
+
+  // Check if public key matches
+  if (trustedRelay.publicKey === publicKey) {
+    return "trusted";
+  }
+
+  // URL known but key doesn't match - SECURITY WARNING
+  return "mismatch";
+}
+
+/**
+ * Check if a URL is localhost (for auto-trust)
+ */
+export function isLocalhost(url: string): boolean {
+  return isLocalhostUrl(url);
+}