gitspace 0.2.0-rc.1

package/src/utils/markdown.ts

@@ -0,0 +1,254 @@
+/**
+ * Markdown generation for Linear issues
+ * Generates markdown files in the specified template format
+ */
+
+import { writeFileSync } from 'fs'
+import { join, extname } from 'path'
+import type { LinearIssue as Issue, LinearAttachment } from '../types/workspace'
+import { logger } from './logger.js'
+
+/**
+ * Convert a string to kebab-case for branch names
+ */
+function toKebabCase(str: string, maxLength = 60): string {
+	const kebab = str
+		.toLowerCase()
+		.replace(/[^\w\s-]/g, '') // Remove special chars
+		.replace(/\s+/g, '-') // Replace spaces with dashes
+		.replace(/-+/g, '-') // Collapse multiple dashes
+		.replace(/^-|-$/g, '') // Remove leading/trailing dashes
+
+	// Truncate to max length at word boundary
+	if (kebab.length <= maxLength) {
+		return kebab
+	}
+
+	const truncated = kebab.substring(0, maxLength)
+	const lastDash = truncated.lastIndexOf('-')
+
+	return lastDash > 0 ? truncated.substring(0, lastDash) : truncated
+}
+
+/**
+ * Clean markdown text to plaintext while preserving structure
+ * Keeps lists and code fences readable
+ */
+function cleanMarkdown(text: string): string {
+	// For now, just return the text as-is
+	// More sophisticated markdown-to-plaintext conversion can be added later
+	return text.trim()
+}
+
+/**
+ * Download an image from a URL and save it to disk
+ * Supports authenticated Linear image downloads
+ */
+async function downloadImage(
+	url: string,
+	filepath: string,
+	linearApiKey?: string
+): Promise<void> {
+	try {
+		// Check if this is a Linear upload URL that requires authentication
+		const isLinearUpload = url.includes('uploads.linear.app')
+
+		// Prepare fetch options
+		const fetchOptions: RequestInit = {}
+
+		if (isLinearUpload && linearApiKey) {
+			// Linear API keys (lin_api_...) don't use Bearer prefix
+			// Only OAuth tokens use Bearer prefix
+			const authHeader = linearApiKey.startsWith('lin_api_')
+				? linearApiKey
+				: `Bearer ${linearApiKey}`
+
+			fetchOptions.headers = {
+				Authorization: authHeader,
+			}
+		}
+
+		const response = await fetch(url, fetchOptions)
+
+		if (!response.ok) {
+			throw new Error(
+				`Failed to download image: ${response.status} ${response.statusText}`
+			)
+		}
+
+		const arrayBuffer = await response.arrayBuffer()
+		const buffer = Buffer.from(arrayBuffer)
+
+		writeFileSync(filepath, buffer)
+		logger.debug(`Downloaded image: ${url} -> ${filepath}`)
+	} catch (error) {
+		logger.warning(
+			`Failed to download image from ${url}: ${
+				error instanceof Error ? error.message : 'Unknown error'
+			}`
+		)
+		throw error
+	}
+}
+
+/**
+ * Get file extension from URL or default to .png
+ */
+function getExtensionFromUrl(url: string): string {
+	try {
+		const urlObj = new URL(url)
+		const pathname = urlObj.pathname
+		const ext = extname(pathname)
+
+		// Common image extensions
+		if (
+			['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp'].includes(
+				ext.toLowerCase()
+			)
+		) {
+			return ext.toLowerCase()
+		}
+	} catch {
+		// Invalid URL, fall through to default
+	}
+
+	return '.png'
+}
+
+/**
+ * Download and localize images in markdown and from attachments
+ * Replaces image URLs with local file paths
+ */
+async function downloadAndLocalizeImages(
+	description: string,
+	attachments: LinearAttachment[],
+	promptDir: string,
+	linearApiKey?: string
+): Promise<string> {
+	let localizedDescription = description
+	let imageCounter = 1
+
+	// Regular expression to match markdown images: ![alt](url)
+	const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g
+
+	// Extract all image URLs from markdown
+	const imageMatches = Array.from(description.matchAll(imageRegex))
+
+	// Download images from markdown description
+	for (const match of imageMatches) {
+		const [fullMatch, altText, imageUrl] = match
+
+		try {
+			const ext = getExtensionFromUrl(imageUrl)
+			const filename = `image-${imageCounter}${ext}`
+			const filepath = join(promptDir, filename)
+
+			await downloadImage(imageUrl, filepath, linearApiKey)
+
+			// Replace URL with local path in markdown
+			localizedDescription = localizedDescription.replace(
+				fullMatch,
+				`![${altText}](./${filename})`
+			)
+
+			imageCounter++
+		} catch (error) {
+			logger.warning(`Skipping image: ${imageUrl}`)
+			// Keep original URL if download fails
+		}
+	}
+
+	// Download images from Linear attachments (if they're image URLs)
+	for (const attachment of attachments) {
+		// Check if attachment is an image based on URL
+		const isImage = /\.(png|jpg|jpeg|gif|svg|webp)$/i.test(attachment.url)
+
+		if (isImage) {
+			try {
+				const ext = getExtensionFromUrl(attachment.url)
+				const filename = `attachment-${imageCounter}${ext}`
+				const filepath = join(promptDir, filename)
+
+				await downloadImage(attachment.url, filepath, linearApiKey)
+
+				// Add attachment to markdown if not already present
+				const attachmentTitle = attachment.title || `Attachment ${imageCounter}`
+				const attachmentMarkdown = `\n\n![${attachmentTitle}](./${filename})`
+
+				// Only add if this URL isn't already in the description
+				if (!description.includes(attachment.url)) {
+					localizedDescription += attachmentMarkdown
+				}
+
+				imageCounter++
+			} catch (error) {
+				logger.warning(`Skipping attachment: ${attachment.url}`)
+			}
+		}
+	}
+
+	return localizedDescription
+}
+
+/**
+ * Generate markdown content for an issue
+ * Follows the exact template format from the specification
+ *
+ * @param issue - The issue to generate markdown for
+ * @param promptDir - Directory where images will be saved (optional, if provided downloads images)
+ * @param linearApiKey - Linear API key for authenticated image downloads (optional)
+ * @returns Markdown formatted string
+ */
+export async function generateMarkdown(
+	issue: Issue,
+	promptDir?: string,
+	linearApiKey?: string
+): Promise<string> {
+	const assignee = await issue.assignee
+	const state = await issue.state
+
+	const assigneeName = assignee?.name || 'unassigned'
+
+	let description = issue.description || 'No description provided.'
+
+	// Download and localize images if promptDir is provided
+	if (promptDir && issue.description) {
+		try {
+			// Fetch attachments (lazy-loaded - only called when needed)
+			const attachments = await issue.attachments()
+
+			description = await downloadAndLocalizeImages(
+				issue.description,
+				attachments,
+				promptDir,
+				linearApiKey
+			)
+		} catch (error) {
+			logger.warning('Failed to download some images, using original URLs')
+		}
+	}
+
+	const fullDescription = cleanMarkdown(description)
+	const branchName = `${issue.identifier}-${toKebabCase(issue.title)}`
+
+	return `# ${issue.identifier}: ${issue.title}
+
+**linear url:** ${issue.url}
+**assignee:** ${assigneeName}
+**state:** ${state?.name ?? 'Unknown'}
+
+## description
+
+${fullDescription}
+
+## acceptance criteria (fill in)
+
+- [ ] criterion 1
+- [ ] criterion 2
+
+## implementation notes (auto-generated)
+
+- branch name: \`${branchName}\`
+- source issue id: \`${issue.id}\`
+`
+}

package/src/utils/onboarding.ts

@@ -0,0 +1,229 @@
+/**
+ * Onboarding step execution engine
+ * Runs interactive onboarding steps from bundle manifests
+ */
+
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { logger } from './logger.js';
+import { promptInput, promptConfirm, promptPassword } from './prompts.js';
+import type {
+  OnboardingStep,
+  OnboardingResult,
+  InfoStep,
+  ConfirmStep,
+  SecretStep,
+  InputStep,
+} from '../types/bundle.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Execute all onboarding steps
+ */
+export async function runOnboarding(
+  steps: OnboardingStep[]
+): Promise<OnboardingResult> {
+  const result: OnboardingResult = {
+    configValues: {},
+    completed: false,
+  };
+
+  logger.bold('\n=== Project Onboarding ===\n');
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const stepNumber = i + 1;
+    const totalSteps = steps.length;
+
+    logger.log(`\n[${stepNumber}/${totalSteps}] ${step.title}`);
+    logger.dim(step.description);
+    logger.log('');
+
+    const stepResult = await executeStep(step);
+
+    if (stepResult === null) {
+      // User cancelled
+      result.cancelledAt = step.id;
+      logger.warning('\nOnboarding cancelled');
+      return result;
+    }
+
+    // Store values for secret/input steps
+    if (step.type === 'secret' || step.type === 'input') {
+      const configKey = (step as SecretStep | InputStep).configKey;
+      result.configValues[configKey] = stepResult;
+    }
+  }
+
+  result.completed = true;
+  logger.success('\nOnboarding complete!');
+  return result;
+}
+
+/**
+ * Execute a single onboarding step
+ * Returns collected value or null if cancelled
+ */
+async function executeStep(step: OnboardingStep): Promise<string | null> {
+  switch (step.type) {
+    case 'info':
+      return executeInfoStep(step);
+    case 'confirm':
+      return executeConfirmStep(step);
+    case 'secret':
+      return executeSecretStep(step);
+    case 'input':
+      return executeInputStep(step);
+    default:
+      logger.warning('Unknown step type, skipping');
+      return '';
+  }
+}
+
+/**
+ * Execute info step - just wait for acknowledgment
+ */
+async function executeInfoStep(step: InfoStep): Promise<string | null> {
+  const confirmed = await promptConfirm('Press Enter to continue...', true);
+  return confirmed ? '' : null;
+}
+
+/**
+ * Execute confirm step - optionally check command
+ */
+async function executeConfirmStep(step: ConfirmStep): Promise<string | null> {
+  // Check if command exists (if specified)
+  if (step.checkCommand) {
+    const exists = await checkCommandExists(step.checkCommand);
+
+    if (exists) {
+      logger.success(`✓ ${step.checkCommand} is installed`);
+      return '';
+    }
+
+    logger.warning(`✗ ${step.checkCommand} not found in PATH`);
+
+    if (step.installUrl) {
+      logger.log(`\nInstall instructions: ${step.installUrl}`);
+    }
+
+    // Ask user to confirm they've installed it
+    const prompt = step.confirmPrompt || `Have you installed ${step.checkCommand}?`;
+
+    while (true) {
+      const confirmed = await promptConfirm(prompt, false);
+
+      if (!confirmed) {
+        // User said no or cancelled
+        if (step.required !== false) {
+          logger.warning('This step is required. Please install and try again.');
+          continue;
+        }
+        return null;
+      }
+
+      // Re-check if they say yes
+      const nowExists = await checkCommandExists(step.checkCommand);
+      if (nowExists) {
+        logger.success(`✓ ${step.checkCommand} is now available`);
+        return '';
+      }
+
+      logger.warning(`${step.checkCommand} still not found. Please ensure it's in your PATH.`);
+    }
+  }
+
+  // No command check, just confirm
+  const prompt = step.confirmPrompt || 'Continue?';
+  const confirmed = await promptConfirm(prompt, true);
+  return confirmed ? '' : null;
+}
+
+/**
+ * Execute secret step - collect masked input
+ */
+async function executeSecretStep(step: SecretStep): Promise<string | null> {
+  const validator = step.validationPattern
+    ? createValidator(step.validationPattern, step.validationMessage)
+    : undefined;
+
+  while (true) {
+    const value = await promptPassword(`Enter ${step.title}:`);
+
+    if (value === null) {
+      return null; // Cancelled
+    }
+
+    if (!value && step.required !== false) {
+      logger.warning('This field is required');
+      continue;
+    }
+
+    if (validator && value) {
+      const validationResult = validator(value);
+      if (validationResult !== true) {
+        logger.warning(typeof validationResult === 'string' ? validationResult : 'Invalid input');
+        continue;
+      }
+    }
+
+    return value;
+  }
+}
+
+/**
+ * Execute input step - collect plain text input
+ */
+async function executeInputStep(step: InputStep): Promise<string | null> {
+  const validator = step.validationPattern
+    ? createValidator(step.validationPattern, step.validationMessage)
+    : undefined;
+
+  const value = await promptInput(`Enter ${step.title}:`, {
+    default: step.defaultValue,
+    validate: (input) => {
+      if (!input && step.required !== false) {
+        return 'This field is required';
+      }
+      if (validator && input) {
+        return validator(input);
+      }
+      return true;
+    },
+  });
+
+  return value;
+}
+
+/**
+ * Check if a command exists in PATH
+ */
+async function checkCommandExists(command: string): Promise<boolean> {
+  if (!/^[a-zA-Z0-9_-]+$/.test(command)) {
+    return false;
+  }
+
+  try {
+    await execFileAsync('which', [command]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a validator function from regex pattern
+ */
+function createValidator(
+  pattern: string,
+  message?: string
+): (value: string) => boolean | string {
+  const regex = new RegExp(pattern);
+  return (value: string) => {
+    if (regex.test(value)) {
+      return true;
+    }
+    return message || `Value must match pattern: ${pattern}`;
+  };
+}

package/src/utils/prompts.ts

@@ -0,0 +1,114 @@
+/**
+ * User prompt utilities using @inquirer/prompts
+ */
+
+import { search, input, confirm, password } from '@inquirer/prompts';
+
+/**
+ * Select an item from a searchable list
+ * @param items Array of items to select from
+ * @param message Prompt message
+ * @returns Selected item or null if cancelled
+ */
+export async function selectItem(
+  items: string[],
+  message: string
+): Promise<string | null> {
+  if (items.length === 0) {
+    return null;
+  }
+
+  try {
+    const selected = await search({
+      message,
+      source: async (input) => {
+        if (!input) {
+          return items.map((item) => ({ name: item, value: item }));
+        }
+
+        // Filter items based on input
+        const filtered = items.filter((item) =>
+          item.toLowerCase().includes(input.toLowerCase())
+        );
+
+        return filtered.map((item) => ({ name: item, value: item }));
+      },
+    });
+
+    return selected;
+  } catch (error) {
+    // User cancelled (Ctrl+C)
+    return null;
+  }
+}
+
+/**
+ * Prompt for text input
+ * @param message Prompt message
+ * @param options Additional options
+ * @returns Input value or null if cancelled
+ */
+export async function promptInput(
+  message: string,
+  options: {
+    default?: string;
+    validate?: (value: string) => boolean | string;
+  } = {}
+): Promise<string | null> {
+  try {
+    const value = await input({
+      message,
+      default: options.default,
+      validate: options.validate,
+    });
+
+    return value;
+  } catch (error) {
+    // User cancelled (Ctrl+C)
+    return null;
+  }
+}
+
+/**
+ * Prompt for confirmation
+ * @param message Prompt message
+ * @param defaultValue Default value
+ * @returns Boolean response
+ */
+export async function promptConfirm(
+  message: string,
+  defaultValue = false
+): Promise<boolean> {
+  try {
+    const value = await confirm({
+      message,
+      default: defaultValue,
+    });
+
+    return value;
+  } catch (error) {
+    // User cancelled (Ctrl+C), treat as false
+    return false;
+  }
+}
+
+/**
+ * Prompt for password input
+ * @param message Prompt message
+ * @returns Password value or null if cancelled
+ */
+export async function promptPassword(
+  message: string
+): Promise<string | null> {
+  try {
+    const value = await password({
+      message,
+      mask: true,
+    });
+
+    return value;
+  } catch (error) {
+    // User cancelled (Ctrl+C)
+    return null;
+  }
+}

package/src/utils/run-commands.ts

@@ -0,0 +1,112 @@
+/**
+ * Run commands in the current terminal (not tmux)
+ * Intelligently runs setup commands only once, then select commands
+ */
+
+import { spawn } from 'child_process';
+import { SpacesError } from '../types/errors.js';
+import { logger } from './logger.js';
+import { hasSetupBeenRun, markSetupComplete } from './workspace-state.js';
+
+/**
+ * Run a single command in the workspace directory
+ * Streams output to current terminal
+ */
+async function runCommand(
+  command: string,
+  workspacePath: string
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    logger.dim(`  $ ${command}`);
+
+    // Parse command and args
+    const [cmd, ...args] = command.split(' ');
+
+    const child = spawn(cmd, args, {
+      cwd: workspacePath,
+      stdio: 'inherit', // Stream output to current terminal
+      shell: true, // Use shell to handle complex commands
+    });
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(
+          new SpacesError(
+            `Command failed with exit code ${code}: ${command}`,
+            'SYSTEM_ERROR',
+            2
+          )
+        );
+      } else {
+        resolve();
+      }
+    });
+
+    child.on('error', (error) => {
+      reject(
+        new SpacesError(
+          `Failed to run command: ${error.message}`,
+          'SYSTEM_ERROR',
+          2
+        )
+      );
+    });
+  });
+}
+
+/**
+ * Run commands in terminal with smart setup tracking
+ * Runs setup commands only once (first time), then select commands on subsequent runs
+ */
+export async function runCommandsInTerminal(
+  workspacePath: string,
+  setupCommands: string[] = [],
+  selectCommands: string[] = []
+): Promise<void> {
+  const setupAlreadyRun = hasSetupBeenRun(workspacePath);
+
+  let commandsToRun: string[] = [];
+  let commandType: string;
+
+  if (setupAlreadyRun) {
+    // Setup has been run before, use select commands
+    commandsToRun = selectCommands;
+    commandType = 'select';
+  } else {
+    // First time setup, run setup commands
+    commandsToRun = setupCommands;
+    commandType = 'setup';
+  }
+
+  if (commandsToRun.length === 0) {
+    logger.debug('No commands to run');
+    return;
+  }
+
+  logger.info(`Running ${commandType} commands...`);
+
+  try {
+    // Run commands sequentially
+    for (const cmd of commandsToRun) {
+      await runCommand(cmd, workspacePath);
+    }
+
+    // Mark setup as complete if we just ran setup commands
+    if (!setupAlreadyRun && setupCommands.length > 0) {
+      markSetupComplete(workspacePath);
+      logger.debug('Setup marked as complete');
+    }
+
+    logger.success('Commands completed');
+  } catch (error) {
+    if (error instanceof SpacesError) {
+      throw error;
+    }
+
+    throw new SpacesError(
+      `Failed to run commands: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      'SYSTEM_ERROR',
+      2
+    );
+  }
+}