@arimakouyou/spec-workflow-mcp 2.2.7

package/dist/core/archive-service.js

@@ -0,0 +1,99 @@
+import { promises as fs } from 'fs';
+import { PathUtils } from './path-utils.js';
+export class SpecArchiveService {
+    projectPath;
+    constructor(projectPath) {
+        // Path should already be translated by caller (ProjectManager)
+        this.projectPath = projectPath;
+    }
+    async archiveSpec(specName) {
+        const activeSpecPath = PathUtils.getSpecPath(this.projectPath, specName);
+        const archiveSpecPath = PathUtils.getArchiveSpecPath(this.projectPath, specName);
+        // Verify the active spec exists
+        try {
+            await fs.access(activeSpecPath);
+        }
+        catch {
+            throw new Error(`Spec '${specName}' not found in active specs`);
+        }
+        // Verify the archive destination doesn't already exist
+        try {
+            await fs.access(archiveSpecPath);
+            throw new Error(`Spec '${specName}' already exists in archive`);
+        }
+        catch (error) {
+            if (error instanceof Error && error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        try {
+            // Ensure archive directory structure exists
+            await fs.mkdir(PathUtils.getArchiveSpecsPath(this.projectPath), { recursive: true });
+            // Move the entire spec directory to archive
+            await fs.rename(activeSpecPath, archiveSpecPath);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to archive spec '${specName}': ${errorMessage}`);
+        }
+    }
+    async unarchiveSpec(specName) {
+        const archiveSpecPath = PathUtils.getArchiveSpecPath(this.projectPath, specName);
+        const activeSpecPath = PathUtils.getSpecPath(this.projectPath, specName);
+        // Verify the archived spec exists
+        try {
+            await fs.access(archiveSpecPath);
+        }
+        catch {
+            throw new Error(`Spec '${specName}' not found in archive`);
+        }
+        // Verify the active destination doesn't already exist
+        try {
+            await fs.access(activeSpecPath);
+            throw new Error(`Spec '${specName}' already exists in active specs`);
+        }
+        catch (error) {
+            if (error instanceof Error && error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        try {
+            // Ensure active specs directory exists
+            await fs.mkdir(PathUtils.getSpecPath(this.projectPath, ''), { recursive: true });
+            // Move the entire spec directory back to active
+            await fs.rename(archiveSpecPath, activeSpecPath);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to unarchive spec '${specName}': ${errorMessage}`);
+        }
+    }
+    async isSpecActive(specName) {
+        try {
+            await fs.access(PathUtils.getSpecPath(this.projectPath, specName));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isSpecArchived(specName) {
+        try {
+            await fs.access(PathUtils.getArchiveSpecPath(this.projectPath, specName));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async getSpecLocation(specName) {
+        const isActive = await this.isSpecActive(specName);
+        if (isActive)
+            return 'active';
+        const isArchived = await this.isSpecArchived(specName);
+        if (isArchived)
+            return 'archived';
+        return 'not-found';
+    }
+}
+//# sourceMappingURL=archive-service.js.map

package/dist/core/archive-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-service.js","sourceRoot":"","sources":["../../src/core/archive-service.ts"],"names":[],"mappings":"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"}

package/dist/core/dashboard-session.d.ts

@@ -0,0 +1,49 @@
+export interface DashboardSessionEntry {
+    url: string;
+    port: number;
+    pid: number;
+    startedAt: string;
+}
+/**
+ * Manages the global dashboard session
+ * Stores dashboard connection info in ~/.spec-workflow-mcp/activeSession.json
+ * (or SPEC_WORKFLOW_HOME if set)
+ */
+export declare class DashboardSessionManager {
+    private sessionDir;
+    private sessionPath;
+    constructor();
+    /**
+     * Ensure the session directory exists
+     */
+    private ensureSessionDir;
+    /**
+     * Read the session file
+     */
+    private readSession;
+    /**
+     * Write the session file atomically
+     */
+    private writeSession;
+    /**
+     * Check if a process is still running
+     */
+    private isProcessAlive;
+    /**
+     * Register the dashboard session
+     */
+    registerDashboard(url: string, port: number, pid: number): Promise<void>;
+    /**
+     * Unregister the dashboard session
+     */
+    unregisterDashboard(): Promise<void>;
+    /**
+     * Get the current dashboard session if it's valid
+     */
+    getDashboardSession(): Promise<DashboardSessionEntry | null>;
+    /**
+     * Check if a dashboard is currently running
+     */
+    isDashboardRunning(): Promise<boolean>;
+}
+//# sourceMappingURL=dashboard-session.d.ts.map

package/dist/core/dashboard-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-session.d.ts","sourceRoot":"","sources":["../../src/core/dashboard-session.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;;IAO5B;;OAEG;YACW,gBAAgB;IAkB9B;;OAEG;YACW,WAAW;IAezB;;OAEG;YACW,YAAY;IAW1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9E;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAU1C;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAqBlE;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;CAI7C"}

package/dist/core/dashboard-session.js

@@ -0,0 +1,132 @@
+import { join } from 'path';
+import { promises as fs } from 'fs';
+import { getGlobalDir, getPermissionErrorHelp } from './global-dir.js';
+/**
+ * Manages the global dashboard session
+ * Stores dashboard connection info in ~/.spec-workflow-mcp/activeSession.json
+ * (or SPEC_WORKFLOW_HOME if set)
+ */
+export class DashboardSessionManager {
+    sessionDir;
+    sessionPath;
+    constructor() {
+        this.sessionDir = getGlobalDir();
+        this.sessionPath = join(this.sessionDir, 'activeSession.json');
+    }
+    /**
+     * Ensure the session directory exists
+     */
+    async ensureSessionDir() {
+        try {
+            await fs.mkdir(this.sessionDir, { recursive: true });
+        }
+        catch (error) {
+            // Directory might already exist, ignore EEXIST errors
+            if (error.code === 'EEXIST') {
+                return;
+            }
+            // For permission errors, provide helpful guidance
+            if (error.code === 'EACCES' || error.code === 'EPERM') {
+                console.error(getPermissionErrorHelp('create directory', this.sessionDir));
+                throw error;
+            }
+            // Re-throw other errors
+            throw error;
+        }
+    }
+    /**
+     * Read the session file
+     */
+    async readSession() {
+        await this.ensureSessionDir();
+        try {
+            const content = await fs.readFile(this.sessionPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // File doesn't exist yet
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write the session file atomically
+     */
+    async writeSession(session) {
+        await this.ensureSessionDir();
+        const content = JSON.stringify(session, null, 2);
+        // Write to temporary file first, then rename for atomic operation
+        const tempPath = `${this.sessionPath}.tmp`;
+        await fs.writeFile(tempPath, content, 'utf-8');
+        await fs.rename(tempPath, this.sessionPath);
+    }
+    /**
+     * Check if a process is still running
+     */
+    isProcessAlive(pid) {
+        try {
+            // Sending signal 0 checks if process exists without actually sending a signal
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Register the dashboard session
+     */
+    async registerDashboard(url, port, pid) {
+        const session = {
+            url,
+            port,
+            pid,
+            startedAt: new Date().toISOString()
+        };
+        await this.writeSession(session);
+    }
+    /**
+     * Unregister the dashboard session
+     */
+    async unregisterDashboard() {
+        try {
+            await fs.unlink(this.sessionPath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Get the current dashboard session if it's valid
+     */
+    async getDashboardSession() {
+        const session = await this.readSession();
+        if (!session) {
+            return null;
+        }
+        // Check if the dashboard process is still alive
+        if (!this.isProcessAlive(session.pid)) {
+            // Process is dead, clean up
+            try {
+                await this.unregisterDashboard();
+            }
+            catch (error) {
+                // Ignore cleanup errors
+            }
+            return null;
+        }
+        return session;
+    }
+    /**
+     * Check if a dashboard is currently running
+     */
+    async isDashboardRunning() {
+        const session = await this.getDashboardSession();
+        return session !== null;
+    }
+}
+//# sourceMappingURL=dashboard-session.js.map

package/dist/core/dashboard-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-session.js","sourceRoot":"","sources":["../../src/core/dashboard-session.ts"],"names":[],"mappings":"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"}

package/dist/core/git-utils.d.ts

@@ -0,0 +1,25 @@
+export declare const SPEC_WORKFLOW_SHARED_ROOT_ENV = "SPEC_WORKFLOW_SHARED_ROOT";
+/**
+ * Resolves the git workspace root directory.
+ * For repositories and worktrees, this returns the top-level checked-out directory.
+ *
+ * @param projectPath - Any path inside the workspace
+ * @returns Workspace root path, or original path when git is unavailable
+ */
+export declare function resolveGitWorkspaceRoot(projectPath: string): string;
+/**
+ * Resolves the git root directory for storing shared specs.
+ * In worktrees, this returns the main repository path so all worktrees share specs.
+ *
+ * @param projectPath - The current project/worktree path
+ * @returns The resolved path (main repo for worktrees, or original path)
+ */
+export declare function resolveGitRoot(projectPath: string): string;
+/**
+ * Checks if the current directory is a git worktree (not the main repo).
+ *
+ * @param projectPath - The path to check
+ * @returns true if in a worktree, false if main repo or not a git repo
+ */
+export declare function isGitWorktree(projectPath: string): boolean;
+//# sourceMappingURL=git-utils.d.ts.map

package/dist/core/git-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.d.ts","sourceRoot":"","sources":["../../src/core/git-utils.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AAOzE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAWnE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAoC1D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAU1D"}

package/dist/core/git-utils.js

@@ -0,0 +1,87 @@
+import { execSync } from 'child_process';
+import { resolve } from 'path';
+export const SPEC_WORKFLOW_SHARED_ROOT_ENV = 'SPEC_WORKFLOW_SHARED_ROOT';
+const GIT_EXEC_OPTIONS = {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 5000
+};
+/**
+ * Resolves the git workspace root directory.
+ * For repositories and worktrees, this returns the top-level checked-out directory.
+ *
+ * @param projectPath - Any path inside the workspace
+ * @returns Workspace root path, or original path when git is unavailable
+ */
+export function resolveGitWorkspaceRoot(projectPath) {
+    try {
+        const workspaceRoot = execSync('git rev-parse --show-toplevel', {
+            cwd: projectPath,
+            ...GIT_EXEC_OPTIONS
+        }).trim();
+        return workspaceRoot || projectPath;
+    }
+    catch {
+        return projectPath;
+    }
+}
+/**
+ * Resolves the git root directory for storing shared specs.
+ * In worktrees, this returns the main repository path so all worktrees share specs.
+ *
+ * @param projectPath - The current project/worktree path
+ * @returns The resolved path (main repo for worktrees, or original path)
+ */
+export function resolveGitRoot(projectPath) {
+    // Check for explicit override first
+    const explicitRoot = process.env[SPEC_WORKFLOW_SHARED_ROOT_ENV]?.trim();
+    if (explicitRoot) {
+        return explicitRoot;
+    }
+    try {
+        // Get the git common directory (main repo's .git folder)
+        const gitCommonDir = execSync('git rev-parse --git-common-dir', {
+            cwd: projectPath,
+            ...GIT_EXEC_OPTIONS
+        }).trim();
+        // In main repo, returns ".git" - no change needed
+        if (gitCommonDir === '.git') {
+            return projectPath;
+        }
+        // In worktree or subdirectory, returns path like "/main/.git", "/main/.git/worktrees/name",
+        // or relative path like "../../.git" when run from a subdirectory.
+        // Extract the main repo path (parent of .git) and resolve to absolute path.
+        const gitIndex = gitCommonDir.lastIndexOf('.git');
+        if (gitIndex > 0) {
+            const mainRepoPath = gitCommonDir.substring(0, gitIndex - 1);
+            // If path is already absolute (Unix or Windows style), return as-is
+            // Otherwise, resolve relative to projectPath
+            const isAbsolute = mainRepoPath.startsWith('/') || /^[A-Za-z]:[\\/]/.test(mainRepoPath);
+            return isAbsolute ? mainRepoPath : resolve(projectPath, mainRepoPath);
+        }
+        return projectPath;
+    }
+    catch {
+        // Not a git repo or git unavailable - use original path
+        return projectPath;
+    }
+}
+/**
+ * Checks if the current directory is a git worktree (not the main repo).
+ *
+ * @param projectPath - The path to check
+ * @returns true if in a worktree, false if main repo or not a git repo
+ */
+export function isGitWorktree(projectPath) {
+    try {
+        const gitCommonDir = execSync('git rev-parse --git-common-dir', {
+            cwd: projectPath,
+            ...GIT_EXEC_OPTIONS
+        }).trim();
+        return gitCommonDir !== '.git';
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=git-utils.js.map

package/dist/core/git-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-utils.js","sourceRoot":"","sources":["../../src/core/git-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAqC,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B,MAAM,CAAC,MAAM,6BAA6B,GAAG,2BAA2B,CAAC;AACzE,MAAM,gBAAgB,GAAsC;IAC1D,QAAQ,EAAE,OAAO;IACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,QAAQ,CAAC,+BAA+B,EAAE;YAC9D,GAAG,EAAE,WAAW;YAChB,GAAG,gBAAgB;SACpB,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,OAAO,aAAa,IAAI,WAAW,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,oCAAoC;IACpC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,EAAE,IAAI,EAAE,CAAC;IACxE,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,CAAC;QACH,yDAAyD;QACzD,MAAM,YAAY,GAAG,QAAQ,CAAC,gCAAgC,EAAE;YAC9D,GAAG,EAAE,WAAW;YAChB,GAAG,gBAAgB;SACpB,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,kDAAkD;QAClD,IAAI,YAAY,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,4FAA4F;QAC5F,mEAAmE;QACnE,4EAA4E;QAC5E,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,MAAM,YAAY,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC;YAC7D,oEAAoE;YACpE,6CAA6C;YAC7C,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACxF,OAAO,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QACxE,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;QACxD,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,QAAQ,CAAC,gCAAgC,EAAE;YAC9D,GAAG,EAAE,WAAW;YAChB,GAAG,gBAAgB;SACpB,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,YAAY,KAAK,MAAM,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/core/global-dir.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Environment variable name for overriding the global directory location.
+ * When set, all global state files will be stored in this location instead of ~/.spec-workflow-mcp
+ *
+ * This is useful for sandboxed environments (e.g., Codex CLI with sandbox_mode=workspace-write)
+ * where $HOME is read-only.
+ *
+ * @example
+ * // Set to an absolute path
+ * SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx spec-workflow-mcp /workspace
+ *
+ * // Set to a relative path (resolved against current working directory)
+ * SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx spec-workflow-mcp /workspace
+ */
+export declare const SPEC_WORKFLOW_HOME_ENV = "SPEC_WORKFLOW_HOME";
+/**
+ * Get the global directory path for storing spec-workflow-mcp state files.
+ *
+ * Resolution order:
+ * 1. SPEC_WORKFLOW_HOME environment variable (if set)
+ *    - Absolute paths are used as-is
+ *    - Relative paths are resolved against process.cwd()
+ * 2. Default: ~/.spec-workflow-mcp
+ *
+ * Files stored in this directory:
+ * - activeProjects.json - Project registry
+ * - activeSession.json - Dashboard session info
+ * - settings.json - Global settings
+ * - job-execution-history.json - Job execution history
+ * - migration.log - Implementation log migration tracking
+ *
+ * @returns The absolute path to the global directory
+ */
+export declare function getGlobalDir(): string;
+/**
+ * Get a helpful error message for permission errors when accessing the global directory.
+ * Suggests using SPEC_WORKFLOW_HOME environment variable.
+ *
+ * @param operation - The operation that failed (e.g., "create directory", "write file")
+ * @param path - The path that couldn't be accessed
+ * @returns A formatted error message with suggestions
+ */
+export declare function getPermissionErrorHelp(operation: string, path: string): string;
+//# sourceMappingURL=global-dir.d.ts.map

package/dist/core/global-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-dir.d.ts","sourceRoot":"","sources":["../../src/core/global-dir.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAI3D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAWrC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB9E"}

package/dist/core/global-dir.js

@@ -0,0 +1,74 @@
+import { homedir } from 'os';
+import { join, isAbsolute } from 'path';
+/**
+ * Environment variable name for overriding the global directory location.
+ * When set, all global state files will be stored in this location instead of ~/.spec-workflow-mcp
+ *
+ * This is useful for sandboxed environments (e.g., Codex CLI with sandbox_mode=workspace-write)
+ * where $HOME is read-only.
+ *
+ * @example
+ * // Set to an absolute path
+ * SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx spec-workflow-mcp /workspace
+ *
+ * // Set to a relative path (resolved against current working directory)
+ * SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx spec-workflow-mcp /workspace
+ */
+export const SPEC_WORKFLOW_HOME_ENV = 'SPEC_WORKFLOW_HOME';
+const DEFAULT_DIR_NAME = '.spec-workflow-mcp';
+/**
+ * Get the global directory path for storing spec-workflow-mcp state files.
+ *
+ * Resolution order:
+ * 1. SPEC_WORKFLOW_HOME environment variable (if set)
+ *    - Absolute paths are used as-is
+ *    - Relative paths are resolved against process.cwd()
+ * 2. Default: ~/.spec-workflow-mcp
+ *
+ * Files stored in this directory:
+ * - activeProjects.json - Project registry
+ * - activeSession.json - Dashboard session info
+ * - settings.json - Global settings
+ * - job-execution-history.json - Job execution history
+ * - migration.log - Implementation log migration tracking
+ *
+ * @returns The absolute path to the global directory
+ */
+export function getGlobalDir() {
+    const envPath = process.env[SPEC_WORKFLOW_HOME_ENV];
+    if (envPath) {
+        // If an environment variable is set, use it
+        // Handle both absolute and relative paths
+        return isAbsolute(envPath) ? envPath : join(process.cwd(), envPath);
+    }
+    // Default to ~/.spec-workflow-mcp
+    return join(homedir(), DEFAULT_DIR_NAME);
+}
+/**
+ * Get a helpful error message for permission errors when accessing the global directory.
+ * Suggests using SPEC_WORKFLOW_HOME environment variable.
+ *
+ * @param operation - The operation that failed (e.g., "create directory", "write file")
+ * @param path - The path that couldn't be accessed
+ * @returns A formatted error message with suggestions
+ */
+export function getPermissionErrorHelp(operation, path) {
+    return `
+Failed to ${operation}: ${path}
+
+This error typically occurs in sandboxed environments where $HOME is read-only.
+
+To fix this, set the SPEC_WORKFLOW_HOME environment variable to a writable location:
+
+  SPEC_WORKFLOW_HOME=/path/to/writable/dir npx spec-workflow-mcp [project-path]
+
+For example, to store state files in your workspace:
+
+  SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx spec-workflow-mcp /workspace
+
+Or use a relative path:
+
+  SPEC_WORKFLOW_HOME=./.spec-workflow-mcp npx spec-workflow-mcp .
+`.trim();
+}
+//# sourceMappingURL=global-dir.js.map

package/dist/core/global-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-dir.js","sourceRoot":"","sources":["../../src/core/global-dir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAE3D,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAEpD,IAAI,OAAO,EAAE,CAAC;QACZ,4CAA4C;QAC5C,0CAA0C;QAC1C,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAED,kCAAkC;IAClC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiB,EAAE,IAAY;IACpE,OAAO;YACG,SAAS,KAAK,IAAI;;;;;;;;;;;;;;;CAe7B,CAAC,IAAI,EAAE,CAAC;AACT,CAAC"}

package/dist/core/implementation-log-migrator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Migrates implementation logs from JSON format to individual markdown files
+ * This utility class handles the automatic migration when the MCP server starts
+ */
+export declare class ImplementationLogMigrator {
+    private migrationLogPath;
+    constructor(userDataDir: string);
+    /**
+     * Log migration events
+     */
+    private log;
+    /**
+     * Sanitize taskId for use in filenames (e.g., "1.2" → "1-2")
+     */
+    private sanitizeTaskId;
+    /**
+     * Generate markdown filename for a log entry
+     */
+    private generateFileName;
+    /**
+     * Convert an implementation log entry to markdown format
+     */
+    private entryToMarkdown;
+    /**
+     * Migrate a single JSON file to markdown files
+     */
+    private migrateJsonFile;
+    /**
+     * Scan all specs and migrate their implementation logs
+     */
+    migrateAllSpecs(specsDir: string): Promise<{
+        totalSpecs: number;
+        migratedSpecs: number;
+        totalEntries: number;
+        errors: Array<{
+            spec: string;
+            error: string;
+        }>;
+    }>;
+}
+//# sourceMappingURL=implementation-log-migrator.d.ts.map

package/dist/core/implementation-log-migrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implementation-log-migrator.d.ts","sourceRoot":"","sources":["../../src/core/implementation-log-migrator.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,gBAAgB,CAAS;gBAErB,WAAW,EAAE,MAAM;IAI/B;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgHvB;;OAEG;YACW,eAAe;IA6B7B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAC/C,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAChD,CAAC;CAuFH"}