gitspace 0.2.0-rc.1

package/src/utils/run-scripts.ts

@@ -0,0 +1,142 @@
+/**
+ * Convention-based script runner
+ * Discovers and runs executable scripts from project scripts/ directories
+ */
+
+import { existsSync, readdirSync, statSync } from 'fs';
+import { spawn } from 'child_process';
+import { join } from 'path';
+import { SpacesError } from '../types/errors.js';
+import { logger } from './logger.js';
+
+/**
+ * Discover executable scripts in a directory
+ * Returns scripts sorted alphabetically for predictable execution order
+ */
+export function discoverScripts(scriptsDir: string): string[] {
+  if (!existsSync(scriptsDir)) {
+    logger.debug(`Scripts directory does not exist: ${scriptsDir}`);
+    return [];
+  }
+
+  try {
+    const files = readdirSync(scriptsDir);
+    const scripts: string[] = [];
+
+    for (const file of files) {
+      const filePath = join(scriptsDir, file);
+      const stats = statSync(filePath);
+
+      // Check if file is executable (has execute permission)
+      // On Unix: check if any execute bit is set
+      if (stats.isFile() && (stats.mode & 0o111) !== 0) {
+        scripts.push(filePath);
+      }
+    }
+
+    // Sort alphabetically for predictable order
+    scripts.sort();
+
+    logger.debug(`Discovered ${scripts.length} executable scripts in ${scriptsDir}`);
+    return scripts;
+  } catch (error) {
+    logger.debug(`Error discovering scripts: ${error}`);
+    return [];
+  }
+}
+
+/**
+ * Options for running scripts
+ */
+export interface RunScriptsOptions {
+  /** Bundle values to pass as SPACE_VALUE_* environment variables */
+  bundleValues?: Record<string, string>;
+  /** Secret values to pass as SPACE_SECRET_* environment variables */
+  bundleSecrets?: Record<string, string>;
+}
+
+/**
+ * Run scripts in the current terminal
+ * Used for pre-scripts that run before tmux session
+ *
+ * Bundle values are passed as environment variables:
+ * - SPACE_VALUE_<KEY> for regular values (key is uppercased)
+ * - SPACE_SECRET_<KEY> for secret values (key is uppercased)
+ */
+export async function runScriptsInTerminal(
+  scriptsDir: string,
+  workspacePath: string,
+  workspaceName: string,
+  repository: string,
+  options?: RunScriptsOptions
+): Promise<void> {
+  const scripts = discoverScripts(scriptsDir);
+
+  if (scripts.length === 0) {
+    logger.debug(`No scripts to run in ${scriptsDir}`);
+    return;
+  }
+
+  const phaseName = scriptsDir.split('/').pop() || 'scripts';
+  logger.info(`Running ${phaseName} scripts...`);
+
+  // Build environment variables from bundle values
+  const scriptEnv: Record<string, string> = { ...process.env } as Record<string, string>;
+
+  // Add bundle values as SPACE_VALUE_<KEY>
+  if (options?.bundleValues) {
+    for (const [key, value] of Object.entries(options.bundleValues)) {
+      const envKey = `SPACE_VALUE_${key.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+      scriptEnv[envKey] = value;
+    }
+  }
+
+  // Add bundle secrets as SPACE_SECRET_<KEY>
+  if (options?.bundleSecrets) {
+    for (const [key, value] of Object.entries(options.bundleSecrets)) {
+      const envKey = `SPACE_SECRET_${key.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+      scriptEnv[envKey] = value;
+    }
+  }
+
+  for (const scriptPath of scripts) {
+    await new Promise<void>((resolve, reject) => {
+      const scriptName = scriptPath.split('/').pop() || scriptPath;
+      logger.dim(`  $ ${scriptName} ${workspaceName} ${repository}`);
+
+      const child = spawn(scriptPath, [workspaceName, repository], {
+        stdio: 'inherit',
+        shell: false,
+        cwd: workspacePath,
+        env: scriptEnv,
+      });
+
+      child.on('close', (code) => {
+        if (code !== 0) {
+          reject(
+            new SpacesError(
+              `Script failed with exit code ${code}: ${scriptName}`,
+              'SYSTEM_ERROR',
+              2
+            )
+          );
+        } else {
+          resolve();
+        }
+      });
+
+      child.on('error', (error) => {
+        reject(
+          new SpacesError(
+            `Failed to run script: ${error.message}`,
+            'SYSTEM_ERROR',
+            2
+          )
+        );
+      });
+    });
+  }
+
+  logger.success(`${phaseName} scripts completed`);
+}
+

package/src/utils/sanitize.ts

@@ -0,0 +1,98 @@
+/**
+ * Name sanitization utilities for filesystem safety
+ */
+
+/**
+ * Sanitize a string for filesystem use
+ * - Converts to lowercase
+ * - Replaces invalid characters with hyphens
+ * - Collapses multiple hyphens
+ * - Removes leading/trailing hyphens
+ * - Limits length to 100 characters
+ *
+ * @param name String to sanitize
+ * @returns Sanitized string safe for filesystem
+ *
+ * @example
+ * sanitizeForFileSystem("Fix Login Bug!") // "fix-login-bug"
+ * sanitizeForFileSystem("Feature / User Settings") // "feature-user-settings"
+ */
+export function sanitizeForFileSystem(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      // Replace any non-alphanumeric characters (except hyphens and underscores) with hyphen
+      .replace(/[^a-z0-9-_]/g, '-')
+      // Collapse multiple hyphens into one
+      .replace(/-+/g, '-')
+      // Remove leading and trailing hyphens
+      .replace(/^-|-$/g, '')
+      // Limit length to 100 characters
+      .slice(0, 100)
+  );
+}
+
+/**
+ * Generate a workspace name from a Linear issue identifier and title
+ *
+ * @param identifier Issue identifier (e.g., "ENG-123")
+ * @param title Issue title
+ * @returns Workspace name in format "{identifier}-{sanitized-title}"
+ *
+ * @example
+ * generateWorkspaceName("ENG-123", "Fix Login Bug!") // "eng-123-fix-login-bug"
+ * generateWorkspaceName("FEAT-456", "Add Dark Mode") // "feat-456-add-dark-mode"
+ */
+export function generateWorkspaceName(identifier: string, title: string): string {
+  const sanitizedTitle = sanitizeForFileSystem(title);
+  const sanitizedIdentifier = identifier.toLowerCase();
+
+  return `${sanitizedIdentifier}-${sanitizedTitle}`;
+}
+
+/**
+ * Validate a workspace name
+ * - Must contain only alphanumeric characters, hyphens, and underscores
+ * - Must not contain spaces
+ * - Must not be empty
+ * - Must not start or end with a hyphen
+ *
+ * @param name Workspace name to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidWorkspaceName(name: string): boolean {
+  if (!name || name.length === 0) {
+    return false;
+  }
+
+  // Check for spaces (explicitly rejected)
+  if (name.includes(' ')) {
+    return false;
+  }
+
+  // Check for valid characters
+  if (!/^[a-z0-9-_]+$/i.test(name)) {
+    return false;
+  }
+
+  // Check for leading/trailing hyphens
+  if (name.startsWith('-') || name.endsWith('-')) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Extract repository name from owner/repo format
+ *
+ * @param repository Repository in "owner/repo" format
+ * @returns Repository name
+ *
+ * @example
+ * extractRepoName("myorg/my-app") // "my-app"
+ */
+export function extractRepoName(repository: string): string {
+  const parts = repository.split('/');
+  return parts[parts.length - 1];
+}

package/src/utils/secrets.ts

@@ -0,0 +1,122 @@
+/**
+ * Secure secrets management using Bun.secrets API
+ * Stores secrets in the OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager)
+ */
+
+const SERVICE_NAME = 'com.gitspace';
+
+/**
+ * Build the secret name for a project's secret key
+ */
+function buildSecretName(projectName: string, key: string): string {
+  return `${projectName}:${key}`;
+}
+
+/**
+ * Store a secret for a project
+ */
+export async function setProjectSecret(
+  projectName: string,
+  key: string,
+  value: string
+): Promise<void> {
+  await Bun.secrets.set({
+    service: SERVICE_NAME,
+    name: buildSecretName(projectName, key),
+    value,
+  });
+}
+
+/**
+ * Retrieve a secret for a project
+ */
+export async function getProjectSecret(
+  projectName: string,
+  key: string
+): Promise<string | null> {
+  return Bun.secrets.get({
+    service: SERVICE_NAME,
+    name: buildSecretName(projectName, key),
+  });
+}
+
+/**
+ * Delete a secret for a project
+ */
+export async function deleteProjectSecret(
+  projectName: string,
+  key: string
+): Promise<boolean> {
+  return Bun.secrets.delete({
+    service: SERVICE_NAME,
+    name: buildSecretName(projectName, key),
+  });
+}
+
+/**
+ * Get all secrets for a project given a list of secret keys
+ * Returns a record of key -> value for all found secrets
+ */
+export async function getProjectSecrets(
+  projectName: string,
+  keys: string[]
+): Promise<Record<string, string>> {
+  const result: Record<string, string> = {};
+
+  for (const key of keys) {
+    const value = await getProjectSecret(projectName, key);
+    if (value !== null) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Delete all secrets for a project given a list of secret keys
+ */
+export async function deleteProjectSecrets(
+  projectName: string,
+  keys: string[]
+): Promise<void> {
+  for (const key of keys) {
+    await deleteProjectSecret(projectName, key);
+  }
+}
+
+// ============================================================================
+// Global Secrets (not project-scoped)
+// ============================================================================
+
+/**
+ * Store a global secret (not project-scoped)
+ * Used for: GITSPACE_TOKEN, TUNNEL_TOKEN_{subdomain}
+ */
+export async function setSecret(key: string, value: string): Promise<void> {
+  await Bun.secrets.set({
+    service: SERVICE_NAME,
+    name: key,
+    value,
+  });
+}
+
+/**
+ * Retrieve a global secret
+ */
+export async function getSecret(key: string): Promise<string | null> {
+  return Bun.secrets.get({
+    service: SERVICE_NAME,
+    name: key,
+  });
+}
+
+/**
+ * Delete a global secret
+ */
+export async function deleteSecret(key: string): Promise<boolean> {
+  return Bun.secrets.delete({
+    service: SERVICE_NAME,
+    name: key,
+  });
+}

package/src/utils/shell-escape.ts

@@ -0,0 +1,40 @@
+/**
+ * Shell escaping utilities for safe command execution
+ * Prevents command injection vulnerabilities when passing user input to shell commands
+ */
+
+/**
+ * Escape a string argument for safe use in shell commands
+ *
+ * This function wraps the argument in single quotes and escapes any single quotes
+ * within the string by replacing them with '\''
+ *
+ * @param arg The string to escape
+ * @returns Safely escaped string for shell use
+ *
+ * @example
+ * escapeShellArg("my-branch") // "'my-branch'"
+ * escapeShellArg("branch'name") // "'branch'\''name'"
+ * escapeShellArg("feature/test") // "'feature/test'"
+ * escapeShellArg('"; rm -rf / #') // "'\"rm -rf / #'"
+ */
+export function escapeShellArg(arg: string): string {
+  // Single quotes protect against all shell metacharacters except single quote itself
+  // To include a single quote, we end the single-quoted string, add an escaped single quote,
+  // and start a new single-quoted string: 'don'\''t' -> "don't"
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Escape multiple arguments and join them with spaces
+ *
+ * @param args Array of arguments to escape
+ * @returns Space-separated string of escaped arguments
+ *
+ * @example
+ * escapeShellArgs(["git", "commit", "-m", "my message"])
+ * // "'git' 'commit' '-m' 'my message'"
+ */
+export function escapeShellArgs(...args: string[]): string {
+  return args.map(escapeShellArg).join(' ');
+}

package/src/utils/utf8.ts

@@ -0,0 +1,79 @@
+/**
+ * UTF-8 Boundary Handling Utilities
+ *
+ * Provides functions for handling UTF-8 encoded data streams,
+ * particularly for finding safe split points in byte buffers
+ * to avoid breaking multi-byte character sequences.
+ */
+
+/**
+ * Find the boundary where complete UTF-8 sequences end.
+ * Returns the number of bytes that form complete UTF-8 sequences.
+ * Any bytes after this boundary are incomplete and should be buffered.
+ *
+ * This function is useful when streaming UTF-8 data in chunks,
+ * where a multi-byte character might be split across chunk boundaries.
+ *
+ * @param buf - The byte buffer to analyze (Buffer or Uint8Array)
+ * @returns The byte offset where complete UTF-8 sequences end
+ *
+ * @example
+ * ```ts
+ * const chunk = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0xc3]); // "Hello" + incomplete é
+ * const boundary = findUtf8Boundary(chunk); // Returns 5
+ * const complete = chunk.slice(0, boundary); // "Hello"
+ * const incomplete = chunk.slice(boundary); // [0xc3] - buffer for next chunk
+ * ```
+ */
+export function findUtf8Boundary(buf: Uint8Array | Buffer): number {
+  if (buf.length === 0) return 0;
+
+  // UTF-8 encoding:
+  // - 1 byte:  0xxxxxxx (0x00-0x7F) - always complete
+  // - 2 bytes: 110xxxxx 10xxxxxx (starts with 0xC0-0xDF)
+  // - 3 bytes: 1110xxxx 10xxxxxx 10xxxxxx (starts with 0xE0-0xEF)
+  // - 4 bytes: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx (starts with 0xF0-0xF7)
+  // Continuation bytes: 10xxxxxx (0x80-0xBF)
+
+  // Start from the last byte and work backwards (up to 3 bytes back)
+  for (let i = 0; i < Math.min(4, buf.length); i++) {
+    const pos = buf.length - 1 - i;
+    const byte = buf[pos];
+
+    // Skip continuation bytes (10xxxxxx) - keep looking for the leading byte
+    if ((byte & 0xc0) === 0x80) {
+      continue;
+    }
+
+    // Found a leading byte at pos - check if sequence is complete
+    let expectedLen: number;
+    if ((byte & 0x80) === 0x00) {
+      // ASCII (0xxxxxxx) - 1 byte
+      expectedLen = 1;
+    } else if ((byte & 0xe0) === 0xc0) {
+      // 2-byte sequence (110xxxxx)
+      expectedLen = 2;
+    } else if ((byte & 0xf0) === 0xe0) {
+      // 3-byte sequence (1110xxxx)
+      expectedLen = 3;
+    } else if ((byte & 0xf8) === 0xf0) {
+      // 4-byte sequence (11110xxx)
+      expectedLen = 4;
+    } else {
+      // Invalid leading byte - treat buffer as complete
+      return buf.length;
+    }
+
+    const actualLen = buf.length - pos;
+    if (actualLen >= expectedLen) {
+      // Sequence is complete
+      return buf.length;
+    } else {
+      // Incomplete sequence - boundary is at this position
+      return pos;
+    }
+  }
+
+  // Only found continuation bytes (malformed UTF-8) - buffer conservatively
+  return Math.max(0, buf.length - 3);
+}

package/src/utils/workspace-state.ts

@@ -0,0 +1,47 @@
+/**
+ * Workspace state tracking utilities
+ * Tracks whether setup commands have been run for a workspace
+ */
+
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { SpacesError } from '../types/errors.js';
+
+/**
+ * Marker file name to indicate setup has been completed
+ */
+const SETUP_MARKER_FILE = 'gitspace.lock';
+
+/**
+ * Check if setup commands have been run for a workspace
+ * @param workspacePath Absolute path to the workspace directory
+ * @returns true if setup has been run, false otherwise
+ */
+export function hasSetupBeenRun(workspacePath: string): boolean {
+  const markerPath = join(workspacePath, SETUP_MARKER_FILE);
+  return existsSync(markerPath);
+}
+
+/**
+ * Mark setup as complete for a workspace
+ * Creates a marker file in the workspace directory
+ * @param workspacePath Absolute path to the workspace directory
+ */
+export function markSetupComplete(workspacePath: string): void {
+  const markerPath = join(workspacePath, SETUP_MARKER_FILE);
+
+  try {
+    const timestamp = new Date().toISOString();
+    writeFileSync(
+      markerPath,
+      `Setup completed: ${timestamp}\nThis file indicates that setup commands have been run for this workspace.\n`,
+      'utf-8'
+    );
+  } catch (error) {
+    throw new SpacesError(
+      `Failed to mark setup complete: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      'SYSTEM_ERROR',
+      2
+    );
+  }
+}

package/src/web/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```