@notis_ai/cli 0.2.0-beta.145.1 → 0.2.0-beta.151.1

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 {
@@ -32,6 +43,7 @@ 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',
@@ -44,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('.');
@@ -246,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,
   };
 }
@@ -300,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, profileKey?: string, sessionId?: string, mountNonce?: 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,
@@ -308,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`),
 }) {
@@ -316,6 +442,9 @@ export async function startAppDevServer({
   }
 
   const appState = new Map();
+  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
@@ -344,17 +473,68 @@ export async function startAppDevServer({
       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) {
     const state = appState.get(slug);
     if (!state) return;
@@ -827,16 +1007,39 @@ export async function startAppDevServer({
       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));
@@ -845,6 +1048,12 @@ 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 = {}) {
@@ -866,7 +1075,19 @@ export async function startAppDevServer({
       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);
@@ -894,10 +1115,16 @@ 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();
@@ -907,6 +1134,7 @@ export async function startAppDevServer({
       }
       hostSseClients.clear();
       await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+      writeDevDiagnostic('stopped');
     },
   };
 }

package/src/runtime/app-platform.js

@@ -680,6 +680,9 @@ function validateConfiguredRoutes(routes) {
     if (route.default) {
       defaultCount += 1;
     }
+    if (route.resourceDeepLinks !== undefined && typeof route.resourceDeepLinks !== 'boolean') {
+      throw usageError(`Route "${route.slug}" resourceDeepLinks must be a boolean.`);
+    }
   }
 
   if (defaultCount !== 1) {
@@ -799,6 +802,7 @@ export function generateManifest(appConfig, projectDir) {
       icon: route.icon || null,
       parentSlug: route.parentSlug || null,
       default: route.default || false,
+      resourceDeepLinks: route.resourceDeepLinks === true,
       export_name: route.exportName || route.export_name || exportNameFromPath(route.path),
       collection: route.collection || null,
     };
@@ -902,6 +906,24 @@ export function generateManifest(appConfig, projectDir) {
   };
 }
 
+/**
+ * Keep the persisted app row's presentation metadata aligned with the bundle
+ * manifest. The app slug remains the stable identity; title/name is only the
+ * user-facing label.
+ */
+export function appRowFieldsFromManifest(manifest) {
+  const app = manifest?.app && typeof manifest.app === 'object' ? manifest.app : {};
+  const displayName = typeof app.title === 'string' && app.title.trim()
+    ? app.title.trim()
+    : typeof app.name === 'string' && app.name.trim()
+      ? app.name.trim()
+      : null;
+  return {
+    ...(displayName ? { name: displayName } : {}),
+    accent: app.accent ?? null,
+  };
+}
+
 export function normalizeAppToolBindings(bindings) {
   return (Array.isArray(bindings) ? bindings : [])
     .map((binding) => {
@@ -2818,7 +2840,7 @@ async function updateAppVersion(supabaseUrl, supabaseKey, appId, newVersion, man
     },
     body: JSON.stringify({
       manifest: { ...manifest, version: newVersion },
-      accent: manifest?.app?.accent ?? null,
+      ...appRowFieldsFromManifest(manifest),
       updated_at: new Date().toISOString(),
     }),
   });

package/template/packages/sdk/src/components/DocumentEditor.tsx

@@ -51,7 +51,7 @@ function DocumentEditorFallback({ documentId, variant = 'full', className }: Not
     );
   }
 
-  const isMarkdown = document.contentType !== 'file';
+  const isMarkdown = document.contentType === 'markdown' || !document.contentType;
   return (
     <div className={className}>
       {variant === 'full' ? <h1 style={fallbackTitleStyle}>{document.title}</h1> : null}
@@ -62,6 +62,15 @@ function DocumentEditorFallback({ documentId, variant = 'full', className }: Not
             <p style={fallbackNoticeStyle}>Read-only preview — editing is available inside the Notis portal.</p>
           )}
         </>
+      ) : document.contentType === 'view' ? (
+        <div style={fallbackFrameStyle}>
+          {document.viewType === 'report'
+            ? 'Interactive report'
+            : document.viewType === 'html'
+              ? 'Interactive HTML document'
+              : 'View document'} — open it in Notis Documents for
+          the full native experience.
+        </div>
       ) : (
         <div style={fallbackFrameStyle}>
           {document.fileType ? `${document.fileType.toUpperCase()} document` : 'File document'} — open it in
@@ -76,8 +85,9 @@ function DocumentEditorFallback({ documentId, variant = 'full', className }: Not
  * Embeds the document editor for a document anywhere in an app view. The host
  * (portal) provides the implementation through `runtime.ui.DocumentEditor` and
  * dispatches on the document's content type (markdown -> rich text editor,
- * files -> matching viewer). Outside the portal this falls back to a read-only
- * preview.
+ * files -> matching viewer, views -> their trusted native Documents surface).
+ * Outside the portal this falls back to a read-only preview or an explicit
+ * open-in-Documents notice for native views.
  *
  * ```tsx
  * <DocumentEditor documentId={entry.id} variant="body" className="min-h-[320px]" />

package/template/packages/sdk/src/config.ts

@@ -40,6 +40,12 @@ export interface NotisRouteConfig {
   icon?: string;
   parentSlug?: string | null;
   default?: boolean;
+  /**
+   * Allow the host to address an app-owned resource on this route through the
+   * canonical `?resource=<id>` deep link. Read the incoming id with
+   * `useNotis().resourceId`.
+   */
+  resourceDeepLinks?: boolean;
   exportName?: string;
   collection?: {
     database: string;

package/template/packages/sdk/src/documents.ts

@@ -107,7 +107,7 @@ export function normalizePropertyValue(value: unknown): unknown {
 }
 
 function normalizeContentType(value: unknown): DocumentContentType | null {
-  return value === 'markdown' || value === 'file' ? value : null;
+  return value === 'markdown' || value === 'file' || value === 'view' ? value : null;
 }
 
 /**
@@ -140,6 +140,12 @@ export function normalizeDocumentRecord(value: unknown): DocumentRecord {
         : null,
     contentMarkdown: optionalString(record.contentMarkdown) ?? optionalString(record.content_markdown),
     plainText: optionalString(record.plainText) ?? optionalString(record.plain_text),
+    viewType: optionalString(record.viewType) ?? optionalString(record.view_type),
+    viewState: asRecord(record.viewState) ?? asRecord(record.view_state),
+    viewRevision:
+      typeof (record.viewRevision ?? record.view_revision) === 'number'
+        ? Number(record.viewRevision ?? record.view_revision)
+        : null,
     createdAt:
       optionalString(record.createdAt)
       ?? optionalString(record.created_at)

package/template/packages/sdk/src/hooks/useNotis.ts

@@ -12,6 +12,8 @@ interface NotisContext {
   databases: DatabaseDescriptor[];
   /** Selected collection item for the current route, when applicable. */
   collectionItem: CollectionItemDetail | null;
+  /** Resource requested through this route's canonical deep link. */
+  resourceId: string | null;
   /** Whether the runtime is loaded and available. */
   ready: boolean;
 }
@@ -29,6 +31,7 @@ export function useNotis(): NotisContext {
     route: runtime?.route ?? null,
     databases: runtime?.databases ?? [],
     collectionItem: runtime?.context?.collectionItem ?? null,
+    resourceId: runtime?.context?.resourceId ?? null,
     ready: runtime !== null,
   };
 }

package/template/packages/sdk/src/hooks/useNotisNavigation.ts

@@ -5,7 +5,7 @@ import { useNotisRuntime } from '../provider';
 
 interface NavigationActions {
   /** Navigate to a route within the app by its path. */
-  toRoute: (path: string) => void;
+  toRoute: (path: string, options?: { resourceId?: string | null }) => void;
   /** Navigate to a document detail view. */
   toDocument: (documentId: string, title?: string | null) => void;
   /** Navigate to the app's default route. */
@@ -25,11 +25,14 @@ interface NavigationActions {
 export function useNotisNavigation(): NavigationActions {
   const runtime = useNotisRuntime();
 
-  const toRoute = useCallback((path: string) => {
+  const toRoute = useCallback((path: string, options?: { resourceId?: string | null }) => {
     if (runtime?.navigate) {
-      runtime.navigate({ kind: 'route', path });
+      runtime.navigate({ kind: 'route', path, resourceId: options?.resourceId ?? null });
     } else if (typeof window !== 'undefined') {
-      window.location.href = path;
+      const url = new URL(path, window.location.href);
+      if (options?.resourceId) url.searchParams.set('resource', options.resourceId);
+      else url.searchParams.delete('resource');
+      window.location.href = url.toString();
     }
   }, [runtime]);
 

package/template/packages/sdk/src/runtime.ts

@@ -71,7 +71,7 @@ export interface DatabaseDescriptor {
  * (pdf, xlsx, pptx, ...). Future content types (canvas, ...) extend this
  * union without changing the component contracts.
  */
-export type DocumentContentType = 'markdown' | 'file';
+export type DocumentContentType = 'markdown' | 'file' | 'view';
 
 export interface DocumentRecord {
   id: string;
@@ -86,6 +86,9 @@ export interface DocumentRecord {
   contentBlocknote?: Array<Record<string, unknown>> | null;
   contentMarkdown?: string | null;
   plainText?: string | null;
+  viewType?: string | null;
+  viewState?: Record<string, unknown> | null;
+  viewRevision?: number | null;
   createdAt?: string | null;
   lastEditedTime?: string | null;
 }
@@ -121,6 +124,7 @@ export interface RouteDescriptor {
   icon?: string | null;
   parentSlug?: string | null;
   default?: boolean;
+  resourceDeepLinks?: boolean;
   collection?: {
     database: string;
     titleProperty: string;
@@ -169,6 +173,8 @@ export interface QueryFilter {
 
 export interface NotisRuntimeContext {
   collectionItem?: CollectionItemDetail | null;
+  /** App-owned resource requested through the route's `?resource=<id>` link. */
+  resourceId?: string | null;
   /**
    * Set when the app is being rendered by the screenshot harness (`notis apps
    * screenshot`) for the named listing scenario. Lets apps and SDK components