openspecui 0.0.0

package/references/openspec/test/helpers/run-cli.ts

@@ -0,0 +1,139 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const projectRoot = path.resolve(__dirname, '..', '..');
+const cliEntry = path.join(projectRoot, 'dist', 'cli', 'index.js');
+
+let buildPromise: Promise<void> | undefined;
+
+interface RunCommandOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+interface RunCLIOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  input?: string;
+  timeoutMs?: number;
+}
+
+export interface RunCLIResult {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  command: string;
+}
+
+function runCommand(command: string, args: string[], options: RunCommandOptions = {}) {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? projectRoot,
+      env: { ...process.env, ...options.env },
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    });
+
+    child.on('error', (error) => reject(error));
+    child.on('close', (code, signal) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+        reject(new Error(`Command failed (${reason}): ${command} ${args.join(' ')}`));
+      }
+    });
+  });
+}
+
+export async function ensureCliBuilt() {
+  if (existsSync(cliEntry)) {
+    return;
+  }
+
+  if (!buildPromise) {
+    buildPromise = runCommand('pnpm', ['run', 'build']).catch((error) => {
+      buildPromise = undefined;
+      throw error;
+    });
+  }
+
+  await buildPromise;
+
+  if (!existsSync(cliEntry)) {
+    throw new Error('CLI entry point missing after build. Expected dist/cli/index.js');
+  }
+}
+
+export async function runCLI(args: string[] = [], options: RunCLIOptions = {}): Promise<RunCLIResult> {
+  await ensureCliBuilt();
+
+  const finalArgs = Array.isArray(args) ? args : [args];
+  const invocation = [cliEntry, ...finalArgs].join(' ');
+
+  return new Promise<RunCLIResult>((resolve, reject) => {
+    const child = spawn(process.execPath, [cliEntry, ...finalArgs], {
+      cwd: options.cwd ?? projectRoot,
+      env: {
+        ...process.env,
+        OPEN_SPEC_INTERACTIVE: '0',
+        ...options.env,
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const timeout = options.timeoutMs
+      ? setTimeout(() => {
+          timedOut = true;
+          child.kill('SIGKILL');
+        }, options.timeoutMs)
+      : undefined;
+
+    child.stdout?.setEncoding('utf-8');
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk;
+    });
+
+    child.stderr?.setEncoding('utf-8');
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on('error', (error) => {
+      if (timeout) clearTimeout(timeout);
+      reject(error);
+    });
+
+    child.on('close', (code, signal) => {
+      if (timeout) clearTimeout(timeout);
+      resolve({
+        exitCode: code,
+        signal,
+        stdout,
+        stderr,
+        timedOut,
+        command: `node ${invocation}`,
+      });
+    });
+
+    if (options.input && child.stdin) {
+      child.stdin.end(options.input);
+    } else if (child.stdin) {
+      child.stdin.end();
+    }
+  });
+}
+
+export const cliProjectRoot = projectRoot;

package/references/openspec/test/utils/file-system.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { randomUUID } from 'crypto';
+import { FileSystemUtils } from '../../src/utils/file-system.js';
+
+describe('FileSystemUtils', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = path.join(os.tmpdir(), `openspec-test-${randomUUID()}`);
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('createDirectory', () => {
+    it('should create a directory', async () => {
+      const dirPath = path.join(testDir, 'new-dir');
+      await FileSystemUtils.createDirectory(dirPath);
+      
+      const stats = await fs.stat(dirPath);
+      expect(stats.isDirectory()).toBe(true);
+    });
+
+    it('should create nested directories', async () => {
+      const dirPath = path.join(testDir, 'nested', 'deep', 'dir');
+      await FileSystemUtils.createDirectory(dirPath);
+      
+      const stats = await fs.stat(dirPath);
+      expect(stats.isDirectory()).toBe(true);
+    });
+
+    it('should not throw if directory already exists', async () => {
+      const dirPath = path.join(testDir, 'existing-dir');
+      await fs.mkdir(dirPath);
+      
+      await expect(FileSystemUtils.createDirectory(dirPath)).resolves.not.toThrow();
+    });
+  });
+
+  describe('fileExists', () => {
+    it('should return true for existing file', async () => {
+      const filePath = path.join(testDir, 'test.txt');
+      await fs.writeFile(filePath, 'test content');
+      
+      const exists = await FileSystemUtils.fileExists(filePath);
+      expect(exists).toBe(true);
+    });
+
+    it('should return false for non-existing file', async () => {
+      const filePath = path.join(testDir, 'non-existent.txt');
+      
+      const exists = await FileSystemUtils.fileExists(filePath);
+      expect(exists).toBe(false);
+    });
+
+    it('should return false for directory path', async () => {
+      const dirPath = path.join(testDir, 'dir');
+      await fs.mkdir(dirPath);
+      
+      const exists = await FileSystemUtils.fileExists(dirPath);
+      expect(exists).toBe(true); // fs.access doesn't distinguish between files and directories
+    });
+  });
+
+  describe('directoryExists', () => {
+    it('should return true for existing directory', async () => {
+      const dirPath = path.join(testDir, 'test-dir');
+      await fs.mkdir(dirPath);
+      
+      const exists = await FileSystemUtils.directoryExists(dirPath);
+      expect(exists).toBe(true);
+    });
+
+    it('should return false for non-existing directory', async () => {
+      const dirPath = path.join(testDir, 'non-existent-dir');
+      
+      const exists = await FileSystemUtils.directoryExists(dirPath);
+      expect(exists).toBe(false);
+    });
+
+    it('should return false for file path', async () => {
+      const filePath = path.join(testDir, 'file.txt');
+      await fs.writeFile(filePath, 'content');
+      
+      const exists = await FileSystemUtils.directoryExists(filePath);
+      expect(exists).toBe(false);
+    });
+  });
+
+  describe('writeFile', () => {
+    it('should write content to file', async () => {
+      const filePath = path.join(testDir, 'output.txt');
+      const content = 'Hello, World!';
+      
+      await FileSystemUtils.writeFile(filePath, content);
+      
+      const readContent = await fs.readFile(filePath, 'utf-8');
+      expect(readContent).toBe(content);
+    });
+
+    it('should create directory if it does not exist', async () => {
+      const filePath = path.join(testDir, 'nested', 'dir', 'output.txt');
+      const content = 'Nested content';
+      
+      await FileSystemUtils.writeFile(filePath, content);
+      
+      const readContent = await fs.readFile(filePath, 'utf-8');
+      expect(readContent).toBe(content);
+    });
+
+    it('should overwrite existing file', async () => {
+      const filePath = path.join(testDir, 'existing.txt');
+      await fs.writeFile(filePath, 'old content');
+      
+      const newContent = 'new content';
+      await FileSystemUtils.writeFile(filePath, newContent);
+      
+      const readContent = await fs.readFile(filePath, 'utf-8');
+      expect(readContent).toBe(newContent);
+    });
+  });
+
+  describe('readFile', () => {
+    it('should read file content', async () => {
+      const filePath = path.join(testDir, 'input.txt');
+      const content = 'Test content';
+      await fs.writeFile(filePath, content);
+      
+      const readContent = await FileSystemUtils.readFile(filePath);
+      expect(readContent).toBe(content);
+    });
+
+    it('should throw for non-existing file', async () => {
+      const filePath = path.join(testDir, 'non-existent.txt');
+      
+      await expect(FileSystemUtils.readFile(filePath)).rejects.toThrow();
+    });
+  });
+
+  describe('ensureWritePermissions', () => {
+    it('should return true for writable directory', async () => {
+      const hasPermission = await FileSystemUtils.ensureWritePermissions(testDir);
+      expect(hasPermission).toBe(true);
+    });
+
+    it('should return true for non-existing directory with writable parent', async () => {
+      const dirPath = path.join(testDir, 'new-dir');
+      const hasPermission = await FileSystemUtils.ensureWritePermissions(dirPath);
+      expect(hasPermission).toBe(true);
+    });
+
+    it('should handle deeply nested non-existing directories', async () => {
+      const dirPath = path.join(testDir, 'a', 'b', 'c', 'd');
+      const hasPermission = await FileSystemUtils.ensureWritePermissions(dirPath);
+      expect(hasPermission).toBe(true);
+    });
+  });
+
+  describe('joinPath', () => {
+    it('should join POSIX-style paths', () => {
+      const result = FileSystemUtils.joinPath(
+        '/tmp/project',
+        '.claude/commands/openspec/proposal.md'
+      );
+      expect(result).toBe('/tmp/project/.claude/commands/openspec/proposal.md');
+    });
+
+    it('should join Linux home directory paths', () => {
+      const result = FileSystemUtils.joinPath(
+        '/home/dev/workspace/openspec',
+        '.cursor/commands/install.md'
+      );
+      expect(result).toBe('/home/dev/workspace/openspec/.cursor/commands/install.md');
+    });
+
+    it('should join Windows drive-letter paths with backslashes', () => {
+      const result = FileSystemUtils.joinPath(
+        'C:\\Users\\dev\\project',
+        '.claude/commands/openspec/proposal.md'
+      );
+      expect(result).toBe(
+        'C:\\Users\\dev\\project\\.claude\\commands\\openspec\\proposal.md'
+      );
+    });
+
+    it('should join Windows paths that use forward slashes', () => {
+      const result = FileSystemUtils.joinPath(
+        'D:/workspace/app',
+        '.cursor/commands/openspec-apply.md'
+      );
+      expect(result).toBe(
+        'D:\\workspace\\app\\.cursor\\commands\\openspec-apply.md'
+      );
+    });
+
+    it('should join UNC-style Windows paths', () => {
+      const result = FileSystemUtils.joinPath(
+        '\\server\\share\\repo',
+        '.windsurf/workflows/openspec-archive.md'
+      );
+      expect(result).toBe(
+        '\\server\\share\\repo\\.windsurf\\workflows\\openspec-archive.md'
+      );
+    });
+  });
+});

package/references/openspec/test/utils/marker-updates.test.ts

@@ -0,0 +1,287 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { FileSystemUtils } from '../../src/utils/file-system.js';
+
+describe('FileSystemUtils.updateFileWithMarkers', () => {
+  let testDir: string;
+  const START_MARKER = '<!-- OPENSPEC:START -->';
+  const END_MARKER = '<!-- OPENSPEC:END -->';
+
+  beforeEach(async () => {
+    testDir = path.join(os.tmpdir(), `openspec-marker-test-${Date.now()}`);
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('new file creation', () => {
+    it('should create new file with markers and content', async () => {
+      const filePath = path.join(testDir, 'new-file.md');
+      const content = 'OpenSpec content';
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${START_MARKER}\n${content}\n${END_MARKER}`);
+    });
+  });
+
+  describe('existing file without markers', () => {
+    it('should prepend markers and content to existing file', async () => {
+      const filePath = path.join(testDir, 'existing.md');
+      const existingContent = '# Existing Content\nUser content here';
+      await fs.writeFile(filePath, existingContent);
+      
+      const newContent = 'OpenSpec content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(
+        `${START_MARKER}\n${newContent}\n${END_MARKER}\n\n${existingContent}`
+      );
+    });
+  });
+
+  describe('existing file with markers', () => {
+    it('should replace content between markers', async () => {
+      const filePath = path.join(testDir, 'with-markers.md');
+      const beforeContent = '# Before\nSome content before';
+      const oldManagedContent = 'Old OpenSpec content';
+      const afterContent = '# After\nSome content after';
+      
+      const existingFile = `${beforeContent}\n${START_MARKER}\n${oldManagedContent}\n${END_MARKER}\n${afterContent}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'New OpenSpec content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(
+        `${beforeContent}\n${START_MARKER}\n${newContent}\n${END_MARKER}\n${afterContent}`
+      );
+    });
+
+    it('should preserve content before and after markers', async () => {
+      const filePath = path.join(testDir, 'preserve.md');
+      const userContentBefore = '# User Content Before\nImportant user notes';
+      const userContentAfter = '## User Content After\nMore user notes';
+      
+      const existingFile = `${userContentBefore}\n${START_MARKER}\nOld content\n${END_MARKER}\n${userContentAfter}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'Updated content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toContain(userContentBefore);
+      expect(result).toContain(userContentAfter);
+      expect(result).toContain(newContent);
+      expect(result).not.toContain('Old content');
+    });
+
+    it('should handle markers at the beginning of file', async () => {
+      const filePath = path.join(testDir, 'markers-at-start.md');
+      const afterContent = 'User content after markers';
+      
+      const existingFile = `${START_MARKER}\nOld content\n${END_MARKER}\n${afterContent}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'New content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${START_MARKER}\n${newContent}\n${END_MARKER}\n${afterContent}`);
+    });
+
+    it('should handle markers at the end of file', async () => {
+      const filePath = path.join(testDir, 'markers-at-end.md');
+      const beforeContent = 'User content before markers';
+      
+      const existingFile = `${beforeContent}\n${START_MARKER}\nOld content\n${END_MARKER}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'New content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${beforeContent}\n${START_MARKER}\n${newContent}\n${END_MARKER}`);
+    });
+  });
+
+  describe('invalid marker states', () => {
+    it('should throw error if only start marker exists', async () => {
+      const filePath = path.join(testDir, 'invalid-start.md');
+      const existingFile = `Some content\n${START_MARKER}\nManaged content\nNo end marker`;
+      await fs.writeFile(filePath, existingFile);
+      
+      await expect(
+        FileSystemUtils.updateFileWithMarkers(
+          filePath,
+          'New content',
+          START_MARKER,
+          END_MARKER
+        )
+      ).rejects.toThrow(/Invalid marker state/);
+    });
+
+    it('should throw error if only end marker exists', async () => {
+      const filePath = path.join(testDir, 'invalid-end.md');
+      const existingFile = `Some content\nNo start marker\nManaged content\n${END_MARKER}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      await expect(
+        FileSystemUtils.updateFileWithMarkers(
+          filePath,
+          'New content',
+          START_MARKER,
+          END_MARKER
+        )
+      ).rejects.toThrow(/Invalid marker state/);
+    });
+  });
+
+  describe('idempotency', () => {
+    it('should produce same result when called multiple times with same content', async () => {
+      const filePath = path.join(testDir, 'idempotent.md');
+      const content = 'Consistent content';
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const firstResult = await fs.readFile(filePath, 'utf-8');
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const secondResult = await fs.readFile(filePath, 'utf-8');
+      expect(secondResult).toBe(firstResult);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty content', async () => {
+      const filePath = path.join(testDir, 'empty-content.md');
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        '',
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${START_MARKER}\n\n${END_MARKER}`);
+    });
+
+    it('should handle content with special characters', async () => {
+      const filePath = path.join(testDir, 'special-chars.md');
+      const content = '# Special chars: ${}[]()<>|\\`*_~';
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toContain(content);
+    });
+
+    it('should handle multi-line content', async () => {
+      const filePath = path.join(testDir, 'multi-line.md');
+      const content = `Line 1
+Line 2
+Line 3
+
+Line 5 with gap`;
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toContain(content);
+    });
+
+    it('should ignore inline mentions of markers when updating content', async () => {
+      const filePath = path.join(testDir, 'inline-mentions.md');
+      const existingFile = `Intro referencing markers like ${START_MARKER} and ${END_MARKER} inside text.
+
+${START_MARKER}
+Original content
+${END_MARKER}
+`;
+
+      await fs.writeFile(filePath, existingFile);
+
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        'Updated content',
+        START_MARKER,
+        END_MARKER
+      );
+
+      const firstResult = await fs.readFile(filePath, 'utf-8');
+      expect(firstResult).toContain('Intro referencing markers like');
+      expect(firstResult).toContain('Updated content');
+      expect(firstResult.match(new RegExp(START_MARKER, 'g'))?.length).toBe(2);
+      expect(firstResult.match(new RegExp(END_MARKER, 'g'))?.length).toBe(2);
+
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        'Updated content',
+        START_MARKER,
+        END_MARKER
+      );
+
+      const secondResult = await fs.readFile(filePath, 'utf-8');
+      expect(secondResult).toBe(firstResult);
+    });
+  });
+});

package/references/openspec/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "NodeNext",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/references/openspec/vitest.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    globalSetup: './vitest.setup.ts',
+    // Keep default pool settings; some tests rely on process.chdir,
+    // which is not supported in worker threads
+    include: ['test/**/*.test.ts'],
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'bin/',
+        '*.config.ts',
+        'build.js',
+        'test/**'
+      ]
+    },
+    testTimeout: 10000,
+    hookTimeout: 10000
+  }
+});

package/references/openspec/vitest.setup.ts

@@ -0,0 +1,6 @@
+import { ensureCliBuilt } from './test/helpers/run-cli.js';
+
+// Ensure the CLI bundle exists before tests execute
+export async function setup() {
+  await ensureCliBuilt();
+}