openspec-cn 0.23.0

package/dist/utils/file-system.js

@@ -0,0 +1,281 @@
+import { promises as fs, constants as fsConstants } from 'fs';
+import path from 'path';
+function isMarkerOnOwnLine(content, markerIndex, markerLength) {
+    let leftIndex = markerIndex - 1;
+    while (leftIndex >= 0 && content[leftIndex] !== '\n') {
+        const char = content[leftIndex];
+        if (char !== ' ' && char !== '\t' && char !== '\r') {
+            return false;
+        }
+        leftIndex--;
+    }
+    let rightIndex = markerIndex + markerLength;
+    while (rightIndex < content.length && content[rightIndex] !== '\n') {
+        const char = content[rightIndex];
+        if (char !== ' ' && char !== '\t' && char !== '\r') {
+            return false;
+        }
+        rightIndex++;
+    }
+    return true;
+}
+function findMarkerIndex(content, marker, fromIndex = 0) {
+    let currentIndex = content.indexOf(marker, fromIndex);
+    while (currentIndex !== -1) {
+        if (isMarkerOnOwnLine(content, currentIndex, marker.length)) {
+            return currentIndex;
+        }
+        currentIndex = content.indexOf(marker, currentIndex + marker.length);
+    }
+    return -1;
+}
+export class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     */
+    static toPosixPath(p) {
+        return p.replace(/\\/g, '/');
+    }
+    static isWindowsBasePath(basePath) {
+        return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
+    }
+    static normalizeSegments(segments) {
+        return segments
+            .flatMap((segment) => segment.split(/[\\/]+/u))
+            .filter((part) => part.length > 0);
+    }
+    static joinPath(basePath, ...segments) {
+        const normalizedSegments = this.normalizeSegments(segments);
+        if (this.isWindowsBasePath(basePath)) {
+            const normalizedBasePath = path.win32.normalize(basePath);
+            return normalizedSegments.length
+                ? path.win32.join(normalizedBasePath, ...normalizedSegments)
+                : normalizedBasePath;
+        }
+        const posixBasePath = basePath.replace(/\\/g, '/');
+        return normalizedSegments.length
+            ? path.posix.join(posixBasePath, ...normalizedSegments)
+            : path.posix.normalize(posixBasePath);
+    }
+    static async createDirectory(dirPath) {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+    static async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.debug(`Unable to check if file exists at ${filePath}: ${error.message}`);
+            }
+            return false;
+        }
+    }
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    static async findFirstExistingDirectory(dirPath) {
+        let currentDir = dirPath;
+        while (true) {
+            try {
+                const stats = await fs.stat(currentDir);
+                if (stats.isDirectory()) {
+                    return currentDir;
+                }
+                // Path component exists but is not a directory (edge case)
+                console.debug(`Path component ${currentDir} exists but is not a directory`);
+                return null;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Directory doesn't exist, move up one level
+                    const parentDir = path.dirname(currentDir);
+                    if (parentDir === currentDir) {
+                        // Reached filesystem root without finding existing directory
+                        return null;
+                    }
+                    currentDir = parentDir;
+                }
+                else {
+                    // Unexpected error (permissions, I/O error, etc.)
+                    console.debug(`Error checking directory ${currentDir}: ${error.message}`);
+                    return null;
+                }
+            }
+        }
+    }
+    static async canWriteFile(filePath) {
+        try {
+            const stats = await fs.stat(filePath);
+            if (!stats.isFile()) {
+                return true;
+            }
+            // On Windows, stats.mode doesn't reliably indicate write permissions.
+            // Use fs.access with W_OK to check actual write permissions cross-platform.
+            try {
+                await fs.access(filePath, fsConstants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // File doesn't exist - find first existing parent directory and check its permissions
+                const parentDir = path.dirname(filePath);
+                const existingDir = await this.findFirstExistingDirectory(parentDir);
+                if (existingDir === null) {
+                    // No existing parent directory found (edge case)
+                    return false;
+                }
+                // Check if the existing parent directory is writable
+                try {
+                    await fs.access(existingDir, fsConstants.W_OK);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            console.debug(`Unable to determine write permissions for ${filePath}: ${error.message}`);
+            return false;
+        }
+    }
+    static async directoryExists(dirPath) {
+        try {
+            const stats = await fs.stat(dirPath);
+            return stats.isDirectory();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.debug(`Unable to check if directory exists at ${dirPath}: ${error.message}`);
+            }
+            return false;
+        }
+    }
+    static async writeFile(filePath, content) {
+        const dir = path.dirname(filePath);
+        await this.createDirectory(dir);
+        await fs.writeFile(filePath, content, 'utf-8');
+    }
+    static async readFile(filePath) {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    static async updateFileWithMarkers(filePath, content, startMarker, endMarker) {
+        let existingContent = '';
+        if (await this.fileExists(filePath)) {
+            existingContent = await this.readFile(filePath);
+            const startIndex = findMarkerIndex(existingContent, startMarker);
+            const endIndex = startIndex !== -1
+                ? findMarkerIndex(existingContent, endMarker, startIndex + startMarker.length)
+                : findMarkerIndex(existingContent, endMarker);
+            if (startIndex !== -1 && endIndex !== -1) {
+                if (endIndex < startIndex) {
+                    throw new Error(`Invalid marker state in ${filePath}. End marker appears before start marker.`);
+                }
+                const before = existingContent.substring(0, startIndex);
+                const after = existingContent.substring(endIndex + endMarker.length);
+                existingContent = before + startMarker + '\n' + content + '\n' + endMarker + after;
+            }
+            else if (startIndex === -1 && endIndex === -1) {
+                existingContent = startMarker + '\n' + content + '\n' + endMarker + '\n\n' + existingContent;
+            }
+            else {
+                throw new Error(`Invalid marker state in ${filePath}. Found start: ${startIndex !== -1}, Found end: ${endIndex !== -1}`);
+            }
+        }
+        else {
+            existingContent = startMarker + '\n' + content + '\n' + endMarker;
+        }
+        await this.writeFile(filePath, existingContent);
+    }
+    static async ensureWritePermissions(dirPath) {
+        try {
+            // If directory doesn't exist, check parent directory permissions
+            if (!await this.directoryExists(dirPath)) {
+                const parentDir = path.dirname(dirPath);
+                if (!await this.directoryExists(parentDir)) {
+                    await this.createDirectory(parentDir);
+                }
+                return await this.ensureWritePermissions(parentDir);
+            }
+            const testFile = path.join(dirPath, '.openspec-test-' + Date.now() + '-' + Math.random().toString(36).slice(2));
+            await fs.writeFile(testFile, '');
+            // On Windows, file may be temporarily locked by antivirus or indexing services.
+            // Retry unlink with a small delay if it fails.
+            const maxRetries = 3;
+            for (let attempt = 0; attempt < maxRetries; attempt++) {
+                try {
+                    await fs.unlink(testFile);
+                    break;
+                }
+                catch (unlinkError) {
+                    if (attempt === maxRetries - 1) {
+                        // Last attempt failed, but we successfully wrote the file, so permissions are OK
+                        // Just log and continue - the temp file will be cleaned up eventually
+                        console.debug(`Could not clean up test file ${testFile}: ${unlinkError.message}`);
+                    }
+                    else {
+                        // Wait briefly before retrying (Windows file lock release)
+                        await new Promise((resolve) => setTimeout(resolve, 50));
+                    }
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            console.debug(`Insufficient permissions to write to ${dirPath}: ${error.message}`);
+            return false;
+        }
+    }
+}
+/**
+ * Removes a marker block from file content.
+ * Only removes markers that are on their own lines (ignores inline mentions).
+ * Cleans up double blank lines that may result from removal.
+ *
+ * @param content - File content with markers
+ * @param startMarker - The start marker string
+ * @param endMarker - The end marker string
+ * @returns Content with marker block removed, or original content if markers not found/invalid
+ */
+export function removeMarkerBlock(content, startMarker, endMarker) {
+    const startIndex = findMarkerIndex(content, startMarker);
+    const endIndex = startIndex !== -1
+        ? findMarkerIndex(content, endMarker, startIndex + startMarker.length)
+        : findMarkerIndex(content, endMarker);
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+        return content;
+    }
+    // Find the start of the line containing the start marker
+    let lineStart = startIndex;
+    while (lineStart > 0 && content[lineStart - 1] !== '\n') {
+        lineStart--;
+    }
+    // Find the end of the line containing the end marker
+    let lineEnd = endIndex + endMarker.length;
+    while (lineEnd < content.length && content[lineEnd] !== '\n') {
+        lineEnd++;
+    }
+    // Include the trailing newline if present
+    if (lineEnd < content.length && content[lineEnd] === '\n') {
+        lineEnd++;
+    }
+    const before = content.substring(0, lineStart);
+    const after = content.substring(lineEnd);
+    // Clean up double blank lines (handle both Unix \n and Windows \r\n)
+    let result = before + after;
+    result = result.replace(/(\r?\n){3,}/g, '\n\n');
+    // Trim trailing whitespace but preserve leading whitespace and original newline style
+    if (result.trimEnd() === '') {
+        return '';
+    }
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    return result.trimEnd() + newline;
+}
+//# sourceMappingURL=file-system.js.map

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { validateChangeName, createChange } from './change-utils.js';
+export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+// Shared utilities
+export { validateChangeName, createChange } from './change-utils.js';
+// Change metadata utilities
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+// File system utilities
+export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/interactive.d.ts

@@ -0,0 +1,18 @@
+export type InteractiveOptions = {
+    /**
+     * Explicit "disable prompts" flag passed by internal callers.
+     */
+    noInteractive?: boolean;
+    /**
+     * Commander-style negated option: `--no-interactive` sets this to false.
+     */
+    interactive?: boolean;
+};
+/**
+ * Resolves whether non-interactive mode is requested.
+ * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
+ * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ */
+export declare function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean;
+export declare function isInteractive(value?: boolean | InteractiveOptions): boolean;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -0,0 +1,21 @@
+/**
+ * Resolves whether non-interactive mode is requested.
+ * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
+ * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ */
+export function resolveNoInteractive(value) {
+    if (typeof value === 'boolean')
+        return value;
+    return value?.noInteractive === true || value?.interactive === false;
+}
+export function isInteractive(value) {
+    if (resolveNoInteractive(value))
+        return false;
+    if (process.env.OPEN_SPEC_INTERACTIVE === '0')
+        return false;
+    // Respect the standard CI environment variable (set by GitHub Actions, GitLab CI, Travis, etc.)
+    if ('CI' in process.env)
+        return false;
+    return !!process.stdin.isTTY;
+}
+//# sourceMappingURL=interactive.js.map

package/dist/utils/item-discovery.d.ts

@@ -0,0 +1,4 @@
+export declare function getActiveChangeIds(root?: string): Promise<string[]>;
+export declare function getSpecIds(root?: string): Promise<string[]>;
+export declare function getArchivedChangeIds(root?: string): Promise<string[]>;
+//# sourceMappingURL=item-discovery.d.ts.map

package/dist/utils/item-discovery.js

@@ -0,0 +1,72 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+export async function getActiveChangeIds(root = process.cwd()) {
+    const changesPath = path.join(root, 'openspec', 'changes');
+    try {
+        const entries = await fs.readdir(changesPath, { withFileTypes: true });
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive')
+                continue;
+            const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
+            try {
+                await fs.access(proposalPath);
+                result.push(entry.name);
+            }
+            catch {
+                // skip directories without proposal.md
+            }
+        }
+        return result.sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function getSpecIds(root = process.cwd()) {
+    const specsPath = path.join(root, 'openspec', 'specs');
+    const result = [];
+    try {
+        const entries = await fs.readdir(specsPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const specFile = path.join(specsPath, entry.name, 'spec.md');
+            try {
+                await fs.access(specFile);
+                result.push(entry.name);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return result.sort();
+}
+export async function getArchivedChangeIds(root = process.cwd()) {
+    const archivePath = path.join(root, 'openspec', 'changes', 'archive');
+    try {
+        const entries = await fs.readdir(archivePath, { withFileTypes: true });
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
+            try {
+                await fs.access(proposalPath);
+                result.push(entry.name);
+            }
+            catch {
+                // skip directories without proposal.md
+            }
+        }
+        return result.sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=item-discovery.js.map

package/dist/utils/match.d.ts

@@ -0,0 +1,3 @@
+export declare function nearestMatches(input: string, candidates: string[], max?: number): string[];
+export declare function levenshtein(a: string, b: string): number;
+//# sourceMappingURL=match.d.ts.map

package/dist/utils/match.js

@@ -0,0 +1,22 @@
+export function nearestMatches(input, candidates, max = 5) {
+    const scored = candidates.map(candidate => ({ candidate, distance: levenshtein(input, candidate) }));
+    scored.sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, max).map(s => s.candidate);
+}
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+//# sourceMappingURL=match.js.map

package/dist/utils/shell-detection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Supported shell types for completion generation
+ */
+export type SupportedShell = 'zsh' | 'bash' | 'fish' | 'powershell';
+/**
+ * Result of shell detection
+ */
+export interface ShellDetectionResult {
+    /** The detected shell if supported, otherwise undefined */
+    shell: SupportedShell | undefined;
+    /** The raw shell name detected (even if unsupported), or undefined if nothing detected */
+    detected: string | undefined;
+}
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export declare function detectShell(): ShellDetectionResult;
+//# sourceMappingURL=shell-detection.d.ts.map

package/dist/utils/shell-detection.js

@@ -0,0 +1,41 @@
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export function detectShell() {
+    // Try SHELL environment variable first (Unix-like systems)
+    const shellPath = process.env.SHELL;
+    if (shellPath) {
+        const shellName = shellPath.toLowerCase();
+        if (shellName.includes('zsh')) {
+            return { shell: 'zsh', detected: 'zsh' };
+        }
+        if (shellName.includes('bash')) {
+            return { shell: 'bash', detected: 'bash' };
+        }
+        if (shellName.includes('fish')) {
+            return { shell: 'fish', detected: 'fish' };
+        }
+        // Shell detected but not supported
+        // Extract shell name from path (e.g., /bin/tcsh -> tcsh)
+        const match = shellPath.match(/\/([^/]+)$/);
+        const detectedName = match ? match[1] : shellPath;
+        return { shell: undefined, detected: detectedName };
+    }
+    // Check for PowerShell on Windows
+    // PSModulePath is a reliable PowerShell-specific environment variable
+    if (process.env.PSModulePath || process.platform === 'win32') {
+        const comspec = process.env.COMSPEC?.toLowerCase();
+        // If PSModulePath exists, we're definitely in PowerShell
+        if (process.env.PSModulePath) {
+            return { shell: 'powershell', detected: 'powershell' };
+        }
+        // On Windows without PSModulePath, we might be in cmd.exe
+        if (comspec?.includes('cmd.exe')) {
+            return { shell: undefined, detected: 'cmd.exe' };
+        }
+    }
+    return { shell: undefined, detected: undefined };
+}
+//# sourceMappingURL=shell-detection.js.map

package/dist/utils/task-progress.d.ts

@@ -0,0 +1,8 @@
+export interface TaskProgress {
+    total: number;
+    completed: number;
+}
+export declare function countTasksFromContent(content: string): TaskProgress;
+export declare function getTaskProgressForChange(changesDir: string, changeName: string): Promise<TaskProgress>;
+export declare function formatTaskStatus(progress: TaskProgress): string;
+//# sourceMappingURL=task-progress.d.ts.map

package/dist/utils/task-progress.js

@@ -0,0 +1,36 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+export function countTasksFromContent(content) {
+    const lines = content.split('\n');
+    let total = 0;
+    let completed = 0;
+    for (const line of lines) {
+        if (line.match(TASK_PATTERN)) {
+            total++;
+            if (line.match(COMPLETED_TASK_PATTERN)) {
+                completed++;
+            }
+        }
+    }
+    return { total, completed };
+}
+export async function getTaskProgressForChange(changesDir, changeName) {
+    const tasksPath = path.join(changesDir, changeName, 'tasks.md');
+    try {
+        const content = await fs.readFile(tasksPath, 'utf-8');
+        return countTasksFromContent(content);
+    }
+    catch {
+        return { total: 0, completed: 0 };
+    }
+}
+export function formatTaskStatus(progress) {
+    if (progress.total === 0)
+        return 'No tasks';
+    if (progress.completed === progress.total)
+        return '✓ Complete';
+    return `${progress.completed}/${progress.total} tasks`;
+}
+//# sourceMappingURL=task-progress.js.map

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "openspec-cn",
+  "version": "0.23.0",
+  "description": "AI-native system for spec-driven development (Chinese Edition)",
+  "keywords": [
+    "openspec",
+    "openspec-cn",
+    "specs",
+    "cli",
+    "ai",
+    "development"
+  ],
+  "homepage": "https://github.com/xiangagou163/OpenSpec-cn",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xiangagou163/OpenSpec-cn"
+  },
+  "license": "MIT",
+  "author": "OpenSpec-cn Contributors",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "openspec": "./bin/openspec.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "schemas",
+    "scripts/postinstall.js",
+    "!dist/**/*.test.js",
+    "!dist/**/__tests__",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/openspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "pnpm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.27.7",
+    "@types/node": "^24.2.0",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@inquirer/core": "^10.2.2",
+    "@inquirer/prompts": "^7.8.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "ora": "^8.2.0",
+    "posthog-node": "^5.20.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.0.17"
+  }
+}