@notis_ai/cli 0.2.14 → 0.2.16

package/src/runtime/app-dev-server.js

@@ -12,9 +12,20 @@
  */
 
 import { createServer } from 'node:http';
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, statSync, watch as fsWatch } from 'node:fs';
+import { execFileSync, spawn } from 'node:child_process';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  watch as fsWatch,
+} from 'node:fs';
+import { freemem, loadavg, totalmem } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 
 import {
@@ -28,7 +39,11 @@ import {
   readLinkedState,
   writeLinkedState,
 } from './app-platform.js';
-import { linkAppDevSessionTarget } from './app-dev-sessions.js';
+import {
+  linkAppDevSessionTarget,
+  readAppDevSessions,
+} from './app-dev-sessions.js';
+import { captureDesktopWatcherOwnership } from './app-dev-process-identity.js';
 
 const CONTENT_TYPES = {
   '.js': 'application/javascript; charset=utf-8',
@@ -41,6 +56,115 @@ const CLI_ROOT = resolve(RUNTIME_DIR, '../..');
 const REPO_ROOT = resolve(RUNTIME_DIR, '../../../..');
 const HARNESS_TEMPLATE_PATH = join(CLI_ROOT, 'template', '.harness', 'index.html.tmpl');
 const FALLBACK_REACT_VERSION = '19.0.0';
+const BUILD_PROCESS_STOP_GRACE_MS = 1_000;
+const DEV_DIAGNOSTIC_INTERVAL_MS = 30_000;
+const DEV_DIAGNOSTIC_MAX_BYTES = 20 * 1024 * 1024;
+
+function processGroupIsRunning(pid, signalProcess = process.kill) {
+  try {
+    signalProcess(-pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}
+
+function readProcessGroupRssBytes(groupPids) {
+  if (process.platform === 'win32' || groupPids.size === 0) return new Map();
+  try {
+    const output = execFileSync('ps', ['-axo', 'pgid=,rss='], {
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const rssByGroup = new Map();
+    for (const line of output.split('\n')) {
+      const [rawGroupPid, rawRssKiB] = line.trim().split(/\s+/, 2);
+      const groupPid = Number.parseInt(rawGroupPid, 10);
+      if (!groupPids.has(groupPid)) continue;
+      const rssKiB = Number.parseInt(rawRssKiB, 10);
+      if (!Number.isFinite(rssKiB)) continue;
+      rssByGroup.set(groupPid, (rssByGroup.get(groupPid) || 0) + (rssKiB * 1024));
+    }
+    return rssByGroup;
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Stop the npm wrapper and every Vite/esbuild descendant it launched.
+ *
+ * Killing only the npm PID leaves its watch process alive after a Desktop host
+ * restart. Each watcher therefore owns a separate POSIX process group. Windows
+ * uses taskkill's tree mode for the equivalent cleanup.
+ */
+export async function terminateBuildProcessTree(child, {
+  platform = process.platform,
+  signalProcess = process.kill,
+  spawnProcess = spawn,
+  graceMs = BUILD_PROCESS_STOP_GRACE_MS,
+} = {}) {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+
+  if (platform === 'win32') {
+    await new Promise((resolvePromise) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        resolvePromise();
+      };
+      try {
+        const killer = spawnProcess('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+          stdio: 'ignore',
+          windowsHide: true,
+        });
+        killer.once('error', () => {
+          try {
+            child.kill('SIGTERM');
+          } catch {
+            // The wrapper already exited.
+          }
+          finish();
+        });
+        killer.once('exit', finish);
+        setTimeout(finish, graceMs).unref?.();
+      } catch {
+        try {
+          child.kill('SIGTERM');
+        } catch {
+          // The wrapper already exited.
+        }
+        finish();
+      }
+    });
+    return;
+  }
+
+  try {
+    signalProcess(-pid, 'SIGTERM');
+  } catch (error) {
+    if (error?.code === 'ESRCH') return;
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      return;
+    }
+  }
+
+  const deadline = Date.now() + graceMs;
+  while (processGroupIsRunning(pid, signalProcess) && Date.now() < deadline) {
+    await delay(25);
+  }
+  if (!processGroupIsRunning(pid, signalProcess)) return;
+  try {
+    signalProcess(-pid, 'SIGKILL');
+  } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+}
 
 function extFor(pathname) {
   const idx = pathname.lastIndexOf('.');
@@ -243,10 +367,11 @@ function buildHarnessDescriptor({ state, manifest, appConfig, route, scenario =
       icon: route.icon || null,
       parentSlug: route.parentSlug || null,
       default: Boolean(route.default),
+      resourceDeepLinks: route.resourceDeepLinks === true,
       collection: route.collection || null,
     },
     databases,
-    context: { collectionItem: null, screenshotScenario: scenario },
+    context: { collectionItem: null, resourceId: null, screenshotScenario: scenario },
     tools,
   };
 }
@@ -297,7 +422,7 @@ function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions,
 /**
  * Start the dev server for one or more apps.
  *
- * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string}>, port: number, watch?: boolean, sessionsFilePath?: string, harness?: { mode?: string, apiBase?: string, jwt?: string }, log?: (m: string) => void, logError?: (m: string) => void}} options
+ * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string, profileKey?: string, sessionId?: string, mountNonce?: string}>, port: number, watch?: boolean, sessionsFilePath?: string, harness?: { mode?: string, apiBase?: string, jwt?: string }, diagnosticsFile?: string | null, desktopOwnerId?: string | null, desktopOwnerScope?: string | null, terminateBuildProcess?: typeof terminateBuildProcessTree, log?: (m: string) => void, logError?: (m: string) => void}} options
  */
 export async function startAppDevServer({
   apps,
@@ -305,6 +430,10 @@ export async function startAppDevServer({
   watch = true,
   sessionsFilePath,
   harness = {},
+  diagnosticsFile = process.env.NOTIS_DEV_DIAGNOSTICS_FILE || null,
+  desktopOwnerId = process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_ID || null,
+  desktopOwnerScope = process.env.NOTIS_APPS_DEV_DESKTOP_OWNER_SCOPE || null,
+  terminateBuildProcess = terminateBuildProcessTree,
   log = (msg) => process.stdout.write(`${msg}\n`),
   logError = (msg) => process.stderr.write(`${msg}\n`),
 }) {
@@ -313,22 +442,97 @@ export async function startAppDevServer({
   }
 
   const appState = new Map();
-  for (const app of apps) {
-    appState.set(app.slug, {
+  let diagnosticsTimer = null;
+  let diagnosticWriteFailed = false;
+  let serverClosing = false;
+  // Sidebar reconciliation needs one stream for the shared host, not one
+  // long-lived HTTP/1.1 connection per discovered app. Keeping a stream per
+  // app exhausts Chromium's per-origin connection pool and can indefinitely
+  // queue the active view's bundle fetch during hot reload.
+  const hostSseClients = new Set();
+  const createAppState = (app) => {
+    let resolveBundleReady;
+    const bundleReadyPromise = new Promise((resolvePromise) => {
+      resolveBundleReady = resolvePromise;
+    });
+    return {
       slug: app.slug,
       projectDir: app.projectDir,
       appId: app.appId || null,
       targetAppId: app.targetAppId || null,
       userId: app.userId || null,
+      profileKey: app.profileKey || null,
+      sessionId: app.sessionId || null,
+      mountNonce: app.mountNonce || null,
       canonicalBundleDir: getBundleDir(app.projectDir),
       bundleDir: null,
       jsPath: null,
       sseClients: new Set(),
       watcher: null,
+      sourceWatchers: [],
+      prepareTimer: null,
+      reloadTimer: null,
       buildProcess: null,
+      watcherOwnership: null,
       lastMtimeMs: 0,
       watchPollTimer: null,
-    });
+      bundleReady: false,
+      bundleReadyPromise,
+      resolveBundleReady,
+      buildProcessStopPromise: null,
+    };
+  };
+  for (const app of apps) {
+    appState.set(app.slug, createAppState(app));
+  }
+
+  function writeDevDiagnostic(event) {
+    if (!diagnosticsFile) return;
+    const memory = process.memoryUsage();
+    const watcherPids = new Set(
+      [...appState.values()]
+        .map((state) => state.buildProcess?.pid)
+        .filter((pid) => Number.isSafeInteger(pid) && pid > 0),
+    );
+    const watcherGroupRss = readProcessGroupRssBytes(watcherPids);
+    const record = {
+      at: new Date().toISOString(),
+      event,
+      host_pid: process.pid,
+      parent_pid: process.ppid,
+      rss_bytes: memory.rss,
+      heap_used_bytes: memory.heapUsed,
+      heap_total_bytes: memory.heapTotal,
+      external_bytes: memory.external,
+      system_free_bytes: freemem(),
+      system_total_bytes: totalmem(),
+      load_average_1m: loadavg()[0],
+      watcher_groups_rss_bytes: [...watcherGroupRss.values()].reduce((total, rss) => total + rss, 0),
+      apps: [...appState.values()].map((state) => ({
+        slug: state.slug,
+        project_dir: state.projectDir,
+        watcher_pid: state.buildProcess?.pid || null,
+        watcher_exit_code: state.buildProcess?.exitCode ?? null,
+        watcher_signal: state.buildProcess?.signalCode ?? null,
+        watcher_group_rss_bytes: watcherGroupRss.get(state.buildProcess?.pid) ?? null,
+        bundle_ready: state.bundleReady,
+      })),
+    };
+    try {
+      mkdirSync(dirname(diagnosticsFile), { recursive: true, mode: 0o700 });
+      if (existsSync(diagnosticsFile) && statSync(diagnosticsFile).size >= DEV_DIAGNOSTIC_MAX_BYTES) {
+        const previous = `${diagnosticsFile}.previous`;
+        rmSync(previous, { force: true });
+        renameSync(diagnosticsFile, previous);
+      }
+      appendFileSync(diagnosticsFile, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+      diagnosticWriteFailed = false;
+    } catch (error) {
+      if (!diagnosticWriteFailed) {
+        diagnosticWriteFailed = true;
+        logError(`[notis apps dev] persistent diagnostics failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
   }
 
   function broadcastReload(slug) {
@@ -342,6 +546,14 @@ export async function startAppDevServer({
         state.sseClients.delete(res);
       }
     }
+    const hostPayload = `event: reload\ndata: ${JSON.stringify({ slug, at: Date.now() })}\n\n`;
+    for (const res of hostSseClients) {
+      try {
+        res.write(hostPayload);
+      } catch {
+        hostSseClients.delete(res);
+      }
+    }
   }
 
   function matchAppRoute(pathname) {
@@ -374,6 +586,10 @@ export async function startAppDevServer({
     state.jsPath = join(bundleDir, 'app.js');
     try {
       state.lastMtimeMs = statSync(state.jsPath).mtimeMs;
+      if (!state.bundleReady) {
+        state.bundleReady = true;
+        state.resolveBundleReady();
+      }
     } catch {
       state.lastMtimeMs = 0;
     }
@@ -451,6 +667,9 @@ export async function startAppDevServer({
             try {
               const body = await readRequestJson(req);
               const appId = typeof body.app_id === 'string' ? body.app_id.trim() : '';
+              const version = Number.isInteger(body.version) && body.version > 0
+                ? body.version
+                : null;
               if (!appId) {
                 res.writeHead(400, {
                   ...headers,
@@ -459,20 +678,69 @@ export async function startAppDevServer({
                 res.end(JSON.stringify({ error: 'app_id is required' }));
                 return;
               }
+              if (version === null) {
+                res.writeHead(400, {
+                  ...headers,
+                  'Content-Type': 'application/json; charset=utf-8',
+                });
+                res.end(JSON.stringify({ error: 'version must be a positive integer' }));
+                return;
+              }
+              const proofSession = readAppDevSessions(sessionsFilePath).sessions.find((session) => (
+                typeof body.session_id === 'string'
+                && typeof body.mount_nonce === 'string'
+                && session.sessionId === body.session_id
+                && session.mountNonce === body.mount_nonce
+                && session.devSlug === state.slug
+                && session.projectDir === state.projectDir
+              ));
+              if (!proofSession) {
+                res.writeHead(403, {
+                  ...headers,
+                  'Content-Type': 'application/json; charset=utf-8',
+                });
+                res.end(JSON.stringify({ error: 'invalid app development session proof' }));
+                return;
+              }
+              const expectedAppId = proofSession.targetAppId || proofSession.appId;
+              if (!expectedAppId || appId !== expectedAppId) {
+                res.writeHead(409, {
+                  ...headers,
+                  'Content-Type': 'application/json; charset=utf-8',
+                });
+                res.end(JSON.stringify({ error: 'app_id does not match this development session' }));
+                return;
+              }
 
-              const currentState = readLinkedState(state.projectDir) || {};
+              const currentState = readLinkedState(
+                state.projectDir,
+                proofSession.profileKey || state.profileKey,
+              ) || {};
               const now = new Date().toISOString();
-              writeLinkedState(state.projectDir, {
+              const promotedInPlace = proofSession.appId === appId;
+              const nextState = {
                 ...currentState,
                 app_id: appId,
-                dev_app_id: state.appId || currentState.dev_app_id,
                 linked_at: currentState.linked_at || now,
-                dev_linked_at: currentState.dev_linked_at || now,
+                version,
+                deployed_at: now,
                 updated_at: now,
-              });
-              state.targetAppId = appId;
+              };
+              if (promotedInPlace) {
+                delete nextState.dev_app_id;
+                delete nextState.dev_linked_at;
+              } else {
+                nextState.dev_app_id = proofSession.appId || currentState.dev_app_id;
+                nextState.dev_linked_at = currentState.dev_linked_at || now;
+              }
+              writeLinkedState(
+                state.projectDir,
+                nextState,
+                proofSession.profileKey || state.profileKey,
+              );
               linkAppDevSessionTarget({
-                appId: state.appId,
+                sessionId: proofSession.sessionId,
+                appId: proofSession.appId,
                 devSlug: state.slug,
                 targetAppId: appId,
                 lastHeartbeatAt: now,
@@ -480,8 +748,9 @@ export async function startAppDevServer({
               const response = {
                 ok: true,
                 app_id: appId,
-                dev_app_id: state.appId || null,
+                dev_app_id: promotedInPlace ? null : proofSession.appId || null,
                 target_app_id: appId,
+                version,
               };
               res.writeHead(200, {
                 ...headers,
@@ -525,6 +794,18 @@ export async function startAppDevServer({
       return;
     }
 
+    if (url.pathname === '/events') {
+      res.writeHead(200, {
+        ...headers,
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        Connection: 'keep-alive',
+      });
+      res.write(': connected\n\n');
+      hostSseClients.add(res);
+      req.on('close', () => hostSseClients.delete(res));
+      return;
+    }
+
     const routed = matchAppRoute(url.pathname);
     if (!routed) {
       res.writeHead(404, headers);
@@ -644,15 +925,23 @@ export async function startAppDevServer({
     try {
       state.watcher = fsWatch(state.bundleDir, { persistent: false }, (_event, filename) => {
         if (!filename || filename !== 'app.js') return;
-        try {
-          const stat = statSync(state.jsPath);
-          if (stat.mtimeMs === state.lastMtimeMs) return;
-          state.lastMtimeMs = stat.mtimeMs;
-          log(`[notis apps dev] ${state.slug}: bundle updated — reloading portal`);
-          broadcastReload(state.slug);
-        } catch {
-          // Bundle file may be missing mid-write; ignore.
-        }
+        // Vite may emit the filesystem notification while its output file is
+        // still being replaced. Debounce the notification so consumers never
+        // fetch the previous or partially-written bundle under the new build
+        // revision.
+        if (state.reloadTimer) clearTimeout(state.reloadTimer);
+        state.reloadTimer = setTimeout(() => {
+          state.reloadTimer = null;
+          try {
+            const stat = statSync(state.jsPath);
+            if (stat.mtimeMs === state.lastMtimeMs) return;
+            state.lastMtimeMs = stat.mtimeMs;
+            log(`[notis apps dev] ${state.slug}: bundle updated — reloading portal`);
+            broadcastReload(state.slug);
+          } catch {
+            // Bundle file may be missing mid-write; the next change retries.
+          }
+        }, 100);
       });
     } catch (error) {
       logError(`[notis apps dev] ${state.slug}: watch failed: ${error.message}`);
@@ -669,21 +958,88 @@ export async function startAppDevServer({
     state.watchPollTimer = setTimeout(() => pollForBundleAndWatch(state), 300);
   }
 
+  function watchManifestInputs(state) {
+    const schedulePrepare = () => {
+      if (state.prepareTimer) clearTimeout(state.prepareTimer);
+      state.prepareTimer = setTimeout(() => {
+        state.prepareTimer = null;
+        void prepareArtifactBuild(state.projectDir).then(() => {
+          // Name, icon, and route metadata can change without changing the
+          // compiled JS bytes. Notify consumers immediately; a generated-entry
+          // change will produce the normal second reload after Vite rebuilds.
+          broadcastReload(state.slug);
+        }).catch((error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          logError(`[notis apps dev] ${state.slug}: ${message}`);
+        });
+      }, 75);
+    };
+    try {
+      state.sourceWatchers.push(fsWatch(
+        state.projectDir,
+        { persistent: false },
+        (_event, filename) => {
+          if (filename && /^notis\.config\.(?:ts|js|mjs)$/.test(String(filename))) {
+            schedulePrepare();
+          }
+        },
+      ));
+    } catch (error) {
+      logError(`[notis apps dev] ${state.slug}: config watch failed: ${error.message}`);
+    }
+    const appDir = join(state.projectDir, 'app');
+    if (existsSync(appDir)) {
+      try {
+        state.sourceWatchers.push(fsWatch(
+          appDir,
+          { persistent: false, recursive: process.platform === 'darwin' || process.platform === 'win32' },
+          schedulePrepare,
+        ));
+      } catch (error) {
+        logError(`[notis apps dev] ${state.slug}: route watch failed: ${error.message}`);
+      }
+    }
+  }
+
   for (const state of appState.values()) {
     if (watch) {
       await prepareArtifactBuild(state.projectDir);
+      watchManifestInputs(state);
       pollForBundleAndWatch(state);
 
-      state.buildProcess = spawn('npm', ['run', 'build', '--', '--watch'], {
+      const buildProcess = spawn('npm', ['run', 'build', '--', '--watch'], {
         cwd: state.projectDir,
+        detached: process.platform !== 'win32',
         stdio: 'inherit',
         env: { ...process.env, NOTIS_DEV: '1' },
       });
+      state.buildProcess = buildProcess;
+      for (let attempt = 0; attempt < 5 && !state.watcherOwnership; attempt += 1) {
+        state.watcherOwnership = captureDesktopWatcherOwnership({
+          pid: buildProcess.pid,
+          projectDir: state.projectDir,
+          desktopOwnerId,
+          desktopOwnerScope,
+        });
+        if (!state.watcherOwnership && attempt < 4) await delay(10);
+      }
 
-      state.buildProcess.on('exit', (code) => {
+      buildProcess.on('exit', (code) => {
         if (code !== 0 && code !== null) {
           logError(`[notis apps dev] ${state.slug}: vite build --watch exited with code ${code}`);
         }
+        if (!serverClosing) {
+          if (state.buildProcess === buildProcess) state.buildProcess = null;
+          const stopPromise = terminateBuildProcess(buildProcess).catch((error) => {
+            logError(`[notis apps dev] ${state.slug}: watcher cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+          });
+          state.buildProcessStopPromise = stopPromise;
+          void stopPromise.finally(() => {
+            if (state.buildProcessStopPromise === stopPromise) {
+              state.buildProcessStopPromise = null;
+            }
+          });
+        }
       });
     } else {
       updateBundleDir(state, resolveBundleDir(state));
@@ -692,10 +1048,57 @@ export async function startAppDevServer({
     log(`[notis apps dev] ${state.slug}: serving bundle at http://127.0.0.1:${port}/a/${state.slug}/bundle/app.js`);
   }
 
+  writeDevDiagnostic('started');
+  if (diagnosticsFile) {
+    diagnosticsTimer = setInterval(() => writeDevDiagnostic('sample'), DEV_DIAGNOSTIC_INTERVAL_MS);
+    diagnosticsTimer.unref?.();
+  }
+
   return {
     port,
+    updateApp(slug, updates = {}) {
+      const state = appState.get(slug);
+      if (!state) throw new Error(`unknown app: ${slug}`);
+      for (const key of ['appId', 'targetAppId', 'userId', 'profileKey', 'sessionId', 'mountNonce']) {
+        if (Object.prototype.hasOwnProperty.call(updates, key)) {
+          state[key] = updates[key] || null;
+        }
+      }
+    },
+    isBundleReady(slug) {
+      const state = appState.get(slug);
+      if (!state) throw new Error(`unknown app: ${slug}`);
+      return state.bundleReady;
+    },
+    waitForBundle(slug) {
+      const state = appState.get(slug);
+      if (!state) return Promise.reject(new Error(`unknown app: ${slug}`));
+      return state.bundleReadyPromise;
+    },
+    getWatcherOwnership(slug) {
+      const state = appState.get(slug);
+      if (!state) throw new Error(`unknown app: ${slug}`);
+      return state.watcherOwnership ? { ...state.watcherOwnership } : null;
+    },
     async close() {
+      serverClosing = true;
+      if (diagnosticsTimer) {
+        clearInterval(diagnosticsTimer);
+        diagnosticsTimer = null;
+      }
+      writeDevDiagnostic('stopping');
+      const buildProcessStops = [];
       for (const state of appState.values()) {
+        if (state.prepareTimer) clearTimeout(state.prepareTimer);
+        if (state.reloadTimer) clearTimeout(state.reloadTimer);
+        for (const watcher of state.sourceWatchers) {
+          try {
+            watcher.close();
+          } catch {
+            // ignore
+          }
+        }
+        state.sourceWatchers = [];
         if (state.watchPollTimer) clearTimeout(state.watchPollTimer);
         if (state.watcher) {
           try {
@@ -712,11 +1115,26 @@ export async function startAppDevServer({
           }
         }
         state.sseClients.clear();
-        if (state.buildProcess && state.buildProcess.exitCode === null) {
-          state.buildProcess.kill('SIGTERM');
+        if (state.buildProcessStopPromise) {
+          buildProcessStops.push(state.buildProcessStopPromise);
+        }
+        if (state.buildProcess) {
+          const buildProcess = state.buildProcess;
+          state.buildProcess = null;
+          buildProcessStops.push(terminateBuildProcess(buildProcess));
+        }
+      }
+      await Promise.allSettled(buildProcessStops);
+      for (const res of hostSseClients) {
+        try {
+          res.end();
+        } catch {
+          // ignore
         }
       }
+      hostSseClients.clear();
       await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+      writeDevDiagnostic('stopped');
     },
   };
 }