jamdesk 1.1.39 → 1.1.41

package/dist/commands/clean.js

@@ -1,49 +1,69 @@
 /**
  * Clean Command
  *
- * Clears the ~/.jamdesk cache directory.
+ * Default: clears the current project's workspace
+ * (`<jamdeskDir>/workspaces/<slug>/`).
+ *
+ * `--all`: clears everything under `<jamdeskDir>/`, including shared
+ * `node_modules` (next dev will reinstall on first run).
+ *
+ * Both modes use safeRemoveCache so a still-running dev session in the
+ * target tree surfaces a clear "another dev is running" message rather
+ * than crashing ENOTEMPTY.
  */
 import fs from 'fs-extra';
-import path from 'path';
-import { homedir } from 'os';
 import { output } from '../lib/output.js';
 import { spinner } from '../lib/spinner.js';
-export async function clean() {
-    const jamdeskDir = path.join(homedir(), '.jamdesk');
-    if (!fs.existsSync(jamdeskDir)) {
-        output.info('Nothing to clean - ~/.jamdesk does not exist');
+import { getJamdeskDir } from '../lib/deps.js';
+import { getProjectWorkspaceDir } from '../lib/workspace-paths.js';
+import { safeRemoveCache } from '../lib/safe-fs.js';
+export async function clean(options = {}, ctx = { jamdeskDir: getJamdeskDir(), projectDir: process.cwd() }) {
+    const { jamdeskDir, projectDir } = ctx;
+    if (options.all) {
+        if (!fs.existsSync(jamdeskDir)) {
+            output.info(`Nothing to clean — ${jamdeskDir} does not exist`);
+            return;
+        }
+        const spin = spinner('Calculating cache size...');
+        const size = await getDirectorySize(jamdeskDir);
+        spin.text = `Removing ${jamdeskDir} (${formatBytes(size)})...`;
+        await safeRemoveCache(jamdeskDir);
+        spin.succeed(`Cleared ${formatBytes(size)} of cache`);
+        console.log('\nCleared:');
+        console.log(`  - ${jamdeskDir}/workspaces/ (all per-project caches)`);
+        console.log(`  - ${jamdeskDir}/node_modules/ (installed dependencies)`);
+        console.log(`  - ${jamdeskDir}/version-cache.json (update check cache)`);
+        console.log('\nNote: any currently-running `jamdesk dev` sessions will fail until you restart them.');
+        console.log('\nNext `jamdesk dev` will reinstall dependencies.');
+        return;
+    }
+    const workspaceDir = getProjectWorkspaceDir(jamdeskDir, projectDir);
+    if (!fs.existsSync(workspaceDir)) {
+        output.info(`Nothing to clean — no workspace at ${workspaceDir}`);
         return;
     }
-    const spin = spinner('Calculating cache size...');
-    // Calculate total size before cleaning
-    const size = await getDirectorySize(jamdeskDir);
-    spin.text = `Removing ~/.jamdesk (${formatBytes(size)})...`;
-    // Remove the entire directory
-    await fs.remove(jamdeskDir);
-    spin.succeed(`Cleared ${formatBytes(size)} of cache`);
-    console.log('\nCleared:');
-    console.log('  - ~/.jamdesk/workspace/ (Build cache)');
-    console.log('  - ~/.jamdesk/node_modules/ (installed dependencies)');
-    console.log('  - ~/.jamdesk/version-cache.json (update check cache)');
-    console.log('\nNext `jamdesk dev` will reinstall dependencies.');
+    const spin = spinner('Calculating workspace size...');
+    const size = await getDirectorySize(workspaceDir);
+    spin.text = `Removing ${workspaceDir} (${formatBytes(size)})...`;
+    await safeRemoveCache(workspaceDir);
+    spin.succeed(`Cleared ${formatBytes(size)} from this project's workspace`);
+    console.log(`\nNext \`jamdesk dev\` in this directory will recompile from scratch.`);
+    console.log(`Use \`jamdesk clean --all\` to also wipe shared node_modules.`);
 }
 async function getDirectorySize(dir) {
     let size = 0;
     try {
         const files = await fs.readdir(dir, { withFileTypes: true });
         for (const file of files) {
-            const filePath = path.join(dir, file.name);
-            if (file.isDirectory()) {
+            const filePath = `${dir}/${file.name}`;
+            if (file.isDirectory())
                 size += await getDirectorySize(filePath);
-            }
-            else {
-                const stats = await fs.stat(filePath);
-                size += stats.size;
-            }
+            else
+                size += (await fs.stat(filePath)).size;
         }
     }
     catch {
-        // Ignore errors (permission issues, etc.)
+        // ignore (permissions, vanished entries)
     }
     return size;
 }

package/dist/commands/clean.js.map

@@ -1 +1 @@
-{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/commands/clean.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,MAAM,CAAC,KAAK,UAAU,KAAK;IACzB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;IAEpD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;QAC5D,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAElD,uCAAuC;IACvC,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAEhD,IAAI,CAAC,IAAI,GAAG,wBAAwB,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;IAE5D,8BAA8B;IAC9B,MAAM,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAE5B,IAAI,CAAC,OAAO,CAAC,WAAW,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAEtD,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC1B,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,uDAAuD,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;IACtE,OAAO,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;AACnE,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,GAAW;IACzC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;gBACvB,IAAI,IAAI,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YAC3C,CAAC;iBAAM,CAAC;gBACN,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACtC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,KAAK,IAAI,CAAC;IACtC,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IAClF,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/commands/clean.ts"],"names":[],"mappings":"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"}

package/dist/commands/dev.d.ts

@@ -27,5 +27,22 @@ export interface DevOptions {
     webpack?: boolean;
     clean?: boolean;
 }
+/**
+ * Sync vendored files to workspace, only copying files that changed.
+ * This preserves file timestamps for unchanged files, allowing Turbopack
+ * to reuse its cache and avoid 35s recompilation on every start.
+ */
+export declare function syncVendoredFiles(srcDir: string, destDir: string, filter: (relativePath: string) => boolean): Promise<{
+    copied: number;
+    skipped: number;
+    removed: number;
+}>;
+/**
+ * Validates the .next cache and cleans it if corrupted or stale.
+ * Returns true if cache is valid and usable, false if it was cleared.
+ *
+ * Exported for unit testing.
+ */
+export declare function validateAndCleanCache(nextCacheDir: string, cliVersionFile: string, workspaceDir: string, verbose: boolean): Promise<boolean>;
 export declare function dev(options: DevOptions): Promise<void>;
 //# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAO/E;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAsQD,wBAAsB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA2sB5D"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAO/E;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAiJD;;;;GAIG;AAGH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,GACxC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAuE/D;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED,wBAAsB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAqtB5D"}

package/dist/commands/dev.js

@@ -5,17 +5,21 @@
  * Wraps the dev-project.cjs logic from build-service.
  */
 import { execSync, spawn } from 'child_process';
+import { runBuildScript } from '../lib/run-build-script.js';
 import fs from 'fs-extra';
 import path from 'path';
 import { createRequire } from 'module';
 import { output } from '../lib/output.js';
 import { spinner } from '../lib/spinner.js';
-import { ensureDependencies, getWorkspaceDir, getJamdeskDir } from '../lib/deps.js';
+import { ensureDependencies, getJamdeskDir } from '../lib/deps.js';
+import { getProjectWorkspaceDir, migrateLegacyWorkspace } from '../lib/workspace-paths.js';
+import { acquireDevLock, releaseDevLock } from '../lib/dev-lock.js';
 import { validateOpenApiSpec, formatErrorForCli, clearSpecCache } from '../lib/openapi.js';
 import { validateConfig } from '../lib/docs-config.js';
 import { validateBrandingAssets } from '../lib/validate-branding.js';
 import { findAvailablePort } from '../lib/port.js';
 import { createLoadingServer } from '../lib/dev-loading-server.js';
+import { safeRemoveCache } from '../lib/safe-fs.js';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -151,7 +155,9 @@ async function syncDirectory(srcDir, destDir) {
  * This preserves file timestamps for unchanged files, allowing Turbopack
  * to reuse its cache and avoid 35s recompilation on every start.
  */
-async function syncVendoredFiles(srcDir, destDir, filter) {
+// Exported for unit testing — verifies the skip list preserves CLI metadata
+// like the dev lockfile, which acquireDevLock writes before this runs.
+export async function syncVendoredFiles(srcDir, destDir, filter) {
     const stats = { copied: 0, skipped: 0, removed: 0 };
     // Build set of source files (relative paths)
     const sourceFiles = new Set();
@@ -188,9 +194,14 @@ async function syncVendoredFiles(srcDir, destDir, filter) {
             // - node_modules: managed separately via NODE_PATH
             // - projects: symlink to user's project
             // - public: contains project-specific files added after sync (docs.json, images)
+            // Plus any CLI-managed dotfile written before sync (e.g. the dev lockfile
+            // acquireDevLock writes at workspace root) — don't sweep our own metadata.
             if (entry.name === '.next' || entry.name === 'node_modules' || entry.name === 'projects' || entry.name === 'public') {
                 continue;
             }
+            if (entry.name === '.jamdesk-dev.lock' || entry.name === '.content-hash') {
+                continue;
+            }
             const destPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
                 await walkDest(destPath, relativePath);
@@ -212,8 +223,10 @@ async function syncVendoredFiles(srcDir, destDir, filter) {
 /**
  * Validates the .next cache and cleans it if corrupted or stale.
  * Returns true if cache is valid and usable, false if it was cleared.
+ *
+ * Exported for unit testing.
  */
-async function validateAndCleanCache(nextCacheDir, cliVersionFile, workspaceDir, verbose) {
+export async function validateAndCleanCache(nextCacheDir, cliVersionFile, workspaceDir, verbose) {
     const cachedVersion = fs.existsSync(cliVersionFile)
         ? fs.readFileSync(cliVersionFile, 'utf-8').trim()
         : null;
@@ -222,7 +235,7 @@ async function validateAndCleanCache(nextCacheDir, cliVersionFile, workspaceDir,
     if (cachedVersion !== currentVersion) {
         if (verbose)
             output.info(`CLI version changed (${cachedVersion} → ${currentVersion}), clearing cache`);
-        await fs.remove(nextCacheDir);
+        await safeRemoveCache(nextCacheDir);
         return false;
     }
     // Check for Turbopack cache corruption (workspace deleted while dev server running)
@@ -230,7 +243,7 @@ async function validateAndCleanCache(nextCacheDir, cliVersionFile, workspaceDir,
     const appDir = path.join(workspaceDir, 'app');
     if (fs.existsSync(turbopackCache) && !fs.existsSync(appDir)) {
         output.warn('Detected corrupted cache, clearing...');
-        await fs.remove(nextCacheDir);
+        await safeRemoveCache(nextCacheDir);
         return false;
     }
     // Remove stale lock file from previous runs (prevents "another dev server" warning)
@@ -351,7 +364,38 @@ export async function dev(options) {
     // Step 2: Prepare workspace
     spin = spinner('Preparing workspace...');
     const jamdeskDir = getJamdeskDir();
-    const workspaceDir = getWorkspaceDir();
+    // Drop the legacy single-workspace layout (CLI ≤1.1.40). safeRemoveCache
+    // surfaces a friendly message if a 1.1.40 dev session is still holding it.
+    if (await migrateLegacyWorkspace(jamdeskDir)) {
+        if (verbose)
+            output.info('Migrated legacy ~/.jamdesk/workspace/ to per-project layout');
+    }
+    const workspaceDir = getProjectWorkspaceDir(jamdeskDir, projectDir);
+    // Same-project guard: refuse to start if another dev is using this workspace.
+    // Acquired BEFORE --clean so a concurrent `dev --clean` can't wipe our
+    // lockfile out from under us.
+    const lock = acquireDevLock(workspaceDir);
+    if (!lock.acquired) {
+        spin.fail('Another `jamdesk dev` is already running for this project');
+        output.error(`   PID ${lock.heldBy} holds the lock at ${path.join(workspaceDir, '.jamdesk-dev.lock')}.\n` +
+            `   Stop it first (Ctrl-C in that terminal, or kill ${lock.heldBy}), then retry.`);
+        process.exit(1);
+    }
+    // Release the lock on any normal exit path. SIGINT/SIGTERM additionally
+    // run `cleanup` further below, which calls release() before tree-killing
+    // the spawned next dev process group.
+    const release = () => releaseDevLock(workspaceDir);
+    process.once('exit', release);
+    // Handle --clean: wipe workspace contents but preserve the lockfile we just
+    // acquired. safeRemoveCache surfaces the friendly message if any path is
+    // still held open.
+    if (options.clean) {
+        output.info('Clearing workspace cache...');
+        const entries = await fs.readdir(workspaceDir);
+        await Promise.all(entries
+            .filter((name) => name !== '.jamdesk-dev.lock')
+            .map((name) => safeRemoveCache(path.join(workspaceDir, name))));
+    }
     const vendoredDir = path.join(__dirname, '../../vendored');
     // Check if vendored directory exists
     if (!fs.existsSync(vendoredDir)) {
@@ -363,58 +407,46 @@ export async function dev(options) {
     // Only remove and recopy vendored files, keeping the .next directory
     const nextCacheDir = path.join(workspaceDir, '.next');
     const cliVersionFile = path.join(nextCacheDir, '.jamdesk-cli-version');
-    // Handle --clean flag: remove entire workspace to start fresh
-    if (options.clean && fs.existsSync(workspaceDir)) {
-        output.info('Clearing workspace cache...');
-        await fs.remove(workspaceDir);
-    }
-    // Determine if we have usable cached compilation
-    let hadCache = fs.existsSync(nextCacheDir);
-    if (hadCache) {
-        hadCache = await validateAndCleanCache(nextCacheDir, cliVersionFile, workspaceDir, verbose);
-    }
+    const hadCache = fs.existsSync(nextCacheDir)
+        && await validateAndCleanCache(nextCacheDir, cliVersionFile, workspaceDir, verbose);
     // Ensure workspace directory exists
     await fs.ensureDir(workspaceDir);
     // Sync vendored files - only copy files that actually changed
     // This preserves timestamps for unchanged files, allowing Turbopack to reuse cache
     const syncStats = await syncVendoredFiles(vendoredDir, workspaceDir, (relativePath) => !relativePath.includes('node_modules') && !relativePath.includes('.next'));
-    // Log sync stats in verbose mode only (internal detail)
     if (verbose && syncStats.copied > 0) {
         output.info(`Synced ${syncStats.copied} build files (${syncStats.skipped} unchanged)`);
     }
-    // Use NODE_PATH instead of symlink for node_modules
-    // Symlinks break Turbopack with "Symlink node_modules is invalid" error
-    // NODE_PATH tells Node.js where to find modules without needing a symlink
-    const jamdeskNodeModules = path.join(path.dirname(workspaceDir), 'node_modules');
-    // Clean up any stale node_modules symlink (Turbopack doesn't allow external symlinks)
+    // Turbopack rejects external symlinks (`Symlink node_modules is invalid`),
+    // so use NODE_PATH=depsDir below instead and clear any stale symlink here.
     const workspaceNodeModules = path.join(workspaceDir, 'node_modules');
-    if (fs.existsSync(workspaceNodeModules)) {
+    try {
         const stats = await fs.lstat(workspaceNodeModules);
-        if (stats.isSymbolicLink()) {
+        if (stats.isSymbolicLink())
             await fs.remove(workspaceNodeModules);
-        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
     }
     // Symlink public directory to parent so Turbopack can find static files
     // (outputFileTracingRoot and turbopack.root are set to parent directory)
     const parentPublic = path.join(jamdeskDir, 'public');
     const workspacePublic = path.join(workspaceDir, 'public');
     await fs.ensureDir(workspacePublic);
-    // Only recreate symlink if target changed
+    // Only recreate symlink if target changed (preserves Turbopack cache mtimes)
     let needsPublicSymlink = true;
-    if (fs.existsSync(parentPublic)) {
-        try {
-            const stats = await fs.lstat(parentPublic);
-            if (stats.isSymbolicLink()) {
-                const currentTarget = await fs.readlink(parentPublic);
-                if (currentTarget === workspacePublic) {
-                    needsPublicSymlink = false;
-                }
-                else {
-                    await fs.remove(parentPublic);
-                }
-            }
+    try {
+        const stats = await fs.lstat(parentPublic);
+        if (stats.isSymbolicLink() && (await fs.readlink(parentPublic)) === workspacePublic) {
+            needsPublicSymlink = false;
         }
-        catch {
+        else {
+            await fs.remove(parentPublic);
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
             await fs.remove(parentPublic);
         }
     }
@@ -427,28 +459,23 @@ export async function dev(options) {
     const workspaceProjectsDir = path.join(workspaceDir, 'projects');
     const workspaceProjectDir = path.join(workspaceProjectsDir, projectName);
     await fs.ensureDir(workspaceProjectsDir);
-    // Only recreate symlink if target changed (preserves timestamps for Turbopack cache)
     let needsSymlink = true;
-    if (fs.existsSync(workspaceProjectDir)) {
-        try {
-            const currentTarget = await fs.readlink(workspaceProjectDir);
-            if (currentTarget === projectDir) {
-                needsSymlink = false; // Symlink already points to correct location
-            }
-            else {
-                await fs.remove(workspaceProjectDir);
-            }
+    try {
+        if ((await fs.readlink(workspaceProjectDir)) === projectDir) {
+            needsSymlink = false;
         }
-        catch {
-            // Not a symlink or can't read - remove and recreate
+        else {
+            await fs.remove(workspaceProjectDir);
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
             await fs.remove(workspaceProjectDir);
         }
     }
     if (needsSymlink) {
         await fs.symlink(projectDir, workspaceProjectDir, 'junction');
     }
-    // Copy project's docs.json to workspace/public/ (only if changed)
-    await fs.ensureDir(path.join(workspaceDir, 'public'));
     await copyIfChanged(docsJsonPath, path.join(workspaceDir, 'public/docs.json'));
     spin.succeed('Workspace prepared');
     // Step 3: Copy project assets (images, etc.) - only copy changed files
@@ -500,30 +527,31 @@ export async function dev(options) {
     // Compute content hash to detect changes (based on file mtimes for speed)
     const crypto = await import('crypto');
     const { glob } = await import('glob');
+    const statMtime = async (file, root) => {
+        try {
+            const stat = await fs.stat(path.join(root, file));
+            return { key: file, mtimeMs: stat.mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    };
     const computeContentHash = async () => {
         const hash = crypto.createHash('md5');
-        // Hash docs.json content
         hash.update(await fs.readFile(docsJsonPath, 'utf-8'));
-        // Glob only MDX/MD files instead of recursive readdir on entire project
-        // (readdir walks node_modules, .git, images — thousands of irrelevant entries)
-        const mdxFiles = await glob('**/*.{mdx,md}', { cwd: projectDir, nodir: true });
-        mdxFiles.sort(); // Deterministic order — glob walk order varies between runs
-        for (const file of mdxFiles) {
-            try {
-                const stat = await fs.stat(path.join(projectDir, file));
-                hash.update(`${file}:${stat.mtimeMs}`);
-            }
-            catch { /* skip inaccessible files */ }
+        // Glob only MDX/MD files — recursive readdir walks node_modules/.git.
+        const mdxFiles = (await glob('**/*.{mdx,md}', { cwd: projectDir, nodir: true })).sort();
+        const mdxStats = await Promise.all(mdxFiles.map((f) => statMtime(f, projectDir)));
+        for (const s of mdxStats) {
+            if (s)
+                hash.update(`${s.key}:${s.mtimeMs}`);
         }
-        // Hash snippets mtimes if they exist
         if (hasSnippets) {
-            const snippetFiles = await fs.readdir(snippetsDir);
-            for (const file of snippetFiles) {
-                try {
-                    const stat = await fs.stat(path.join(snippetsDir, file));
-                    hash.update(`snippets/${file}:${stat.mtimeMs}`);
-                }
-                catch { /* skip */ }
+            const snippetFiles = (await fs.readdir(snippetsDir)).sort();
+            const snippetStats = await Promise.all(snippetFiles.map((f) => statMtime(f, snippetsDir)));
+            for (const s of snippetStats) {
+                if (s)
+                    hash.update(`snippets/${s.key}:${s.mtimeMs}`);
             }
         }
         return hash.digest('hex');
@@ -544,34 +572,26 @@ export async function dev(options) {
     const contentChanged = currentHash !== cachedHash;
     if (contentChanged) {
         spin.text = 'Processing navigation, snippets, and search index...';
-        // Helper to run a script (uses hardcoded script names, no user input)
-        const runScript = (script) => {
-            return new Promise((resolve) => {
-                try {
-                    execSync(`node scripts/${script}`, {
-                        cwd: workspaceDir,
-                        stdio: verbose ? 'inherit' : 'pipe',
-                        env: { ...env, PROJECT_NAME: path.basename(projectDir) },
-                    });
-                    resolve({ script, success: true });
-                }
-                catch (error) {
-                    resolve({ script, success: false, error });
-                }
-            });
+        const scriptOpts = {
+            cwd: workspaceDir,
+            env: { ...env, PROJECT_NAME: path.basename(projectDir) },
+            verbose,
         };
-        // Run all three scripts in parallel
         const [navResult, snippetsResult, searchResult] = await Promise.all([
-            runScript('enhance-navigation.cjs'),
-            runScript('compile-snippets.cjs'),
-            runScript('build-search-index.cjs'),
+            runBuildScript('enhance-navigation.cjs', scriptOpts),
+            runBuildScript('compile-snippets.cjs', scriptOpts),
+            runBuildScript('build-search-index.cjs', scriptOpts),
         ]);
-        // Check for failures
         const failures = [navResult, snippetsResult, searchResult].filter((r) => !r.success);
         if (failures.length > 0) {
             spin.fail('Build step failed');
             for (const f of failures) {
                 output.error(`Failed: ${f.script}`);
+                // Surface child stderr (or stdout) on every failure so non-verbose users
+                // see the actual error, not just the script name.
+                const tail = (f.stderr || f.stdout || '').trim();
+                if (tail)
+                    console.error(tail.split('\n').slice(-20).join('\n'));
                 if (verbose && f.error)
                     console.error(f.error);
             }
@@ -634,7 +654,7 @@ export async function dev(options) {
     console.log('   If it gets stuck at "Starting...", run `jamdesk clean` and restart.\n');
     // Show cold start warning if no cache
     if (!hadCache) {
-        console.log(`\n   ⏳ First run - full compile needed (this takes ~30-40s, then it's cached)`);
+        console.log(`\n   ⏳ First run - full compile needed (this takes a minute, then it's cached)`);
     }
     console.log(`\n   Access at: http://localhost:${proxyPort}${basePath}/${firstPage}\n`);
     // Use Turbopack by default (~5x faster than webpack)
@@ -857,6 +877,7 @@ export async function dev(options) {
     });
     // Handle Ctrl+C - be aggressive about cleanup
     function cleanup() {
+        release(); // Release the workspace lock first so a subsequent dev isn't blocked.
         if (compileSpinner) {
             clearInterval(compileSpinner);
             process.stdout.write('\r\x1b[K');
@@ -882,7 +903,7 @@ export async function dev(options) {
         }
         process.exit(0);
     }
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
 }
 //# sourceMappingURL=dev.js.map