@notis_ai/cli 0.2.0-beta.21.1 → 0.2.0-beta.35.1

package/src/command-specs/apps.js

@@ -1,12 +1,17 @@
 /**
  * Notis apps CLI commands.
  *
- * Clean command set for the Vercel-like Notis app workflow:
- *   init -> dev -> build -> preview -> deploy
+ * Canonical Notis app workflow:
+ *   init -> dev -> build -> deploy
  *
  * Supporting commands: list, link, doctor.
  */
 
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
 import { EXIT_CODES, usageError } from '../runtime/errors.js';
 import { formatTable } from '../runtime/output.js';
 import {
@@ -20,17 +25,38 @@ import {
   writeLinkedState,
   requireLinkedAppId,
   scaffoldProject,
+  loadScaffoldCatalog,
+  inspectListingReadiness,
   collectArtifactFiles,
-  runProjectScript,
+  collectSourceFiles,
   directDeploy,
+  pullAppSource,
 } from '../runtime/app-platform.js';
-import { startPreviewServer } from '../runtime/app-preview-server.js';
+import { startAppDevServer } from '../runtime/app-dev-server.js';
+import {
+  closeAgentBrowserSession,
+  isAgentBrowserAvailable,
+  runHarnessRoute,
+} from '../runtime/agent-browser.js';
+import {
+  heartbeatAppDevSession,
+  removeAppDevSession,
+  upsertAppDevSessions,
+} from '../runtime/app-dev-sessions.js';
+import { getAvailablePort } from '../runtime/ports.js';
+import { getCliMode } from '../runtime/cli-mode.js';
 import {
   nextIdempotencyKey,
   runToolCommand,
   toolConflictToError,
 } from './helpers.js';
 
+const DEFAULT_DEV_PORT = 5173;
+const DEV_HEARTBEAT_INTERVAL_MS = 10_000;
+const CONFIG_FILENAMES = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'];
+const ENSURE_DEV_APP_INSTALLATION_TOOL = 'notis-default-ensure_dev_app_installation';
+const GET_APP_TOOL = 'notis-default-get_app';
+
 // ---------------------------------------------------------------------------
 // Formatters
 // ---------------------------------------------------------------------------
@@ -44,6 +70,380 @@ function appsTable(apps) {
   ]);
 }
 
+function scaffoldsTable(scaffolds) {
+  return formatTable(scaffolds, [
+    { label: 'Slug', value: (scaffold) => scaffold.slug || '' },
+    { label: 'Name', value: (scaffold) => scaffold.name || scaffold.slug || '' },
+    { label: 'Category', value: (scaffold) => (scaffold.categories || [])[0] || '' },
+    { label: 'Tagline', value: (scaffold) => scaffold.tagline || scaffold.description || '' },
+  ]);
+}
+
+function hasNotisConfig(dir) {
+  return CONFIG_FILENAMES.some((name) => existsSync(join(dir, name)));
+}
+
+function discoverAppDirs(projectDir) {
+  if (hasNotisConfig(projectDir)) {
+    return [projectDir];
+  }
+
+  const appsDir = join(projectDir, 'apps');
+  if (!existsSync(appsDir)) {
+    throw usageError(
+      `No notis.config.ts in ${projectDir}. Run from a Notis app project or a monorepo root with apps/<name>/notis.config.ts.`,
+    );
+  }
+
+  const entries = readdirSync(appsDir, { withFileTypes: true });
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+    const dir = join(appsDir, entry.name);
+    if (hasNotisConfig(dir)) {
+      candidates.push(dir);
+    }
+  }
+
+  if (candidates.length === 0) {
+    throw usageError(
+      `Found apps/ in ${projectDir} but no apps/<name>/notis.config.ts inside it.`,
+    );
+  }
+
+  return candidates;
+}
+
+function decodeJwtSub(jwt) {
+  if (!jwt) return null;
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const decoded = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return decoded.sub || decoded.email || null;
+  } catch {
+    return null;
+  }
+}
+
+function openInBrowser(url) {
+  const platform = process.platform;
+  let command;
+  let args;
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    command = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    // Non-fatal. The URL is printed in the CLI output.
+  }
+}
+
+function slugify(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)+/g, '');
+}
+
+function buildDevInstallSlug(appName) {
+  const base = slugify(appName);
+  if (!base) {
+    return '';
+  }
+  return base.endsWith('-dev') ? base : `${base}-dev`;
+}
+
+function timingMs(startedAt) {
+  return Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+}
+
+function logAppsTiming(label, details = {}) {
+  const suffix = Object.entries(details)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(' ');
+  process.stderr.write(`[notis apps timing] ${label}${suffix ? ` ${suffix}` : ''}\n`);
+}
+
+function nextDevInstallIdempotencyKey(globalOptions = {}, devSlug) {
+  if (globalOptions.idempotencyKey) {
+    return `${globalOptions.idempotencyKey}:${devSlug}`;
+  }
+  return nextIdempotencyKey(globalOptions);
+}
+
+function pickDefaultRouteSlug(manifest) {
+  const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
+  const explicit = routes.find((route) => route && route.default && typeof route.slug === 'string');
+  if (explicit) return explicit.slug;
+  const firstWithSlug = routes.find((route) => route && typeof route.slug === 'string' && route.slug);
+  return firstWithSlug ? firstWithSlug.slug : null;
+}
+
+export function buildDevelopmentDesktopUrl(appHref = null) {
+  const route = String(appHref || '/store').replace(/^\/+/, '');
+  return `notis://${route || 'store'}`;
+}
+
+function buildAppHref({ appSlug, appId, manifest }) {
+  const originlessBase = `/apps/${appSlug}-${appId}`;
+  const routeSlug = pickDefaultRouteSlug(manifest);
+  return routeSlug ? `${originlessBase}/${routeSlug}` : originlessBase;
+}
+
+function parsePort(value) {
+  if (!value) return null;
+  const port = Number.parseInt(value, 10);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw usageError('Port must be between 1 and 65535.');
+  }
+  return port;
+}
+
+function parseRouteSlugs(value) {
+  if (!value) return null;
+  const slugs = String(value)
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (slugs.length === 0) {
+    throw usageError('--routes must include at least one route slug.');
+  }
+  return slugs;
+}
+
+function routeSelection(manifest, rawRouteSlugs) {
+  const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
+  if (routes.length === 0) {
+    throw usageError('Manifest has no routes to verify.');
+  }
+  if (!rawRouteSlugs) {
+    return routes;
+  }
+
+  const bySlug = new Map(routes.map((route) => [route.slug, route]));
+  const selected = [];
+  const missing = [];
+  for (const slug of rawRouteSlugs) {
+    const route = bySlug.get(slug);
+    if (route) {
+      selected.push(route);
+    } else {
+      missing.push(slug);
+    }
+  }
+  if (missing.length) {
+    throw usageError(
+      `Unknown route slug${missing.length === 1 ? '' : 's'}: ${missing.join(', ')}.`,
+      { available_routes: routes.map((route) => route.slug) },
+    );
+  }
+  return selected;
+}
+
+function declaredDatabaseSlugs(appConfig, manifest, route) {
+  const slugs = new Set();
+  for (const entry of appConfig?.databases || manifest?.databases || []) {
+    if (typeof entry === 'string' && entry) {
+      slugs.add(entry);
+    } else if (entry && typeof entry === 'object' && typeof entry.slug === 'string') {
+      slugs.add(entry.slug);
+    }
+  }
+  if (route?.collection?.database) {
+    slugs.add(route.collection.database);
+  }
+  return Array.from(slugs);
+}
+
+function harnessErrorMessage(error) {
+  if (!error || typeof error !== 'object') {
+    return String(error);
+  }
+  return error.message || error.reason || error.type || JSON.stringify(error);
+}
+
+function assertHarnessResult(result, route, databaseSlugs) {
+  const assertions = [];
+  if (result.tool_error) {
+    assertions.push({
+      ok: false,
+      code: 'tool_error',
+      message: `agent-browser ${result.tool_error.phase || 'command'} failed`,
+      details: result.tool_error,
+    });
+  }
+  if (result.mounted !== true) {
+    assertions.push({
+      ok: false,
+      code: 'not_mounted',
+      message: 'Harness did not report mounted === true.',
+    });
+  }
+  if (result.timed_out) {
+    assertions.push({
+      ok: false,
+      code: 'timeout',
+      message: 'Timed out waiting for window.__harness.mounted.',
+    });
+  }
+  for (const error of result.errors || []) {
+    assertions.push({
+      ok: false,
+      code: 'render_error',
+      message: harnessErrorMessage(error),
+      details: error,
+    });
+  }
+  for (const databaseSlug of databaseSlugs) {
+    const seen = (result.runtimeCalls || []).some(
+      (call) =>
+        call?.op === 'callTool' &&
+        call?.args?.name === 'notis-default-query' &&
+        call?.args?.arguments?.database_slug === databaseSlug,
+    );
+    if (!seen) {
+      assertions.push({
+        ok: false,
+        code: 'missing_database_query',
+        message: `Route "${route.slug}" did not call notis-default-query for "${databaseSlug}".`,
+        details: { databaseSlug },
+      });
+    }
+  }
+  return assertions;
+}
+
+function renderVerifyReport({ summary, results, noBrowser }) {
+  const lines = [
+    noBrowser
+      ? `Harness URLs ready for ${summary.total} route${summary.total === 1 ? '' : 's'}.`
+      : `Verified ${summary.total} route${summary.total === 1 ? '' : 's'}: ${summary.passed} passed, ${summary.failed} failed.`,
+  ];
+  for (const result of results) {
+    const marker = result.ok ? 'PASS' : result.status === 'manual' ? 'URL' : 'FAIL';
+    lines.push(`${marker.padEnd(4)} ${result.route.padEnd(18)} ${result.url}`);
+    for (const assertion of result.assertions || []) {
+      lines.push(`     - ${assertion.message}`);
+    }
+  }
+  if (noBrowser) {
+    lines.push('', 'Pass --keep-open to leave the harness process running while you inspect the URLs.');
+  }
+  return lines.join('\n');
+}
+
+function buildManifestForDev(appConfig) {
+  const routes = Array.isArray(appConfig.routes) ? appConfig.routes : [];
+  return {
+    version: 1,
+    spec_version: 3,
+    app: {
+      name: appConfig.name,
+      description: appConfig.description || null,
+      icon: appConfig.icon || null,
+    },
+    routes: routes.map((route) => ({
+      path: route.path,
+      slug: route.slug,
+      name: route.name,
+      icon: route.icon || null,
+      parentSlug: route.parentSlug || null,
+      default: route.default || false,
+      export_name: route.exportName || route.export_name,
+      collection: route.collection || null,
+    })),
+    bundle: {
+      js: 'bundle/app.js',
+      css: 'bundle/app.css',
+    },
+    databases: appConfig.databases || [],
+    tools: appConfig.tools || [],
+  };
+}
+
+export function buildEnsureDevInstallArguments({ appConfig, manifest, linkedState }) {
+  const devSlug = buildDevInstallSlug(appConfig.name);
+  const arguments_ = {
+    dev_slug: devSlug,
+    name: appConfig.name,
+    manifest,
+  };
+  if (linkedState?.app_id) {
+    arguments_.app_id = linkedState.app_id;
+  }
+  return arguments_;
+}
+
+export async function ensureDevInstall({
+  ctx,
+  appConfig,
+  projectDir,
+  idempotencyKey,
+  runTool = runToolCommand,
+}) {
+  if (!appConfig.name) {
+    throw usageError(`notis.config.ts in ${projectDir} must define a non-empty name.`);
+  }
+  const devSlug = buildDevInstallSlug(appConfig.name);
+  if (!devSlug) {
+    throw usageError(`notis.config.ts name in ${projectDir} must slugify to a non-empty value.`);
+  }
+
+  const manifest = buildManifestForDev(appConfig);
+  const linkedState = readLinkedState(projectDir);
+  const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState });
+  const ensureResult = await runTool({
+    runtime: ctx.runtime,
+    toolName: ENSURE_DEV_APP_INSTALLATION_TOOL,
+    arguments_: ensureArguments,
+    mutating: true,
+    idempotencyKey,
+  });
+  const appId = ensureResult.payload.app_id;
+  if (!appId) {
+    throw usageError('Dev installation tool did not return an app_id.');
+  }
+  return {
+    slug: ensureResult.payload.slug || devSlug,
+    devSlug,
+    name: appConfig.name,
+    appId,
+    projectDir,
+    manifest,
+    created: ensureResult.payload.created || false,
+    linkedAppId: linkedState?.app_id || null,
+    databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
+  };
+}
+
+function databaseMaterializationWarnings(apps) {
+  const warnings = [];
+  for (const app of apps) {
+    const unresolved = app.databaseMaterialization?.unresolved || [];
+    if (!unresolved.length) {
+      continue;
+    }
+    warnings.push(
+      `${app.name}: database slug${unresolved.length === 1 ? '' : 's'} ${unresolved.join(', ')} ` +
+      'could not be created because no store snapshot schema exists. Create them manually or link to a store-installed app.',
+    );
+  }
+  return warnings;
+}
+
 async function assertDirectDeployAccess(runtime, appId) {
   const result = await runToolCommand({
     runtime,
@@ -76,33 +476,46 @@ async function appsListHandler(ctx) {
 
 async function appsInitHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || ctx.args.name.toLowerCase().replace(/[^a-z0-9]+/g, '-'));
+  const fromSlug = ctx.options.from || null;
 
-  scaffoldProject({ projectDir, appName: ctx.args.name });
+  scaffoldProject({ projectDir, appName: ctx.args.name, fromSlug });
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
-    data: { project_dir: projectDir, app_name: ctx.args.name },
-    humanSummary: `Scaffolded "${ctx.args.name}" in ${projectDir}`,
+    data: { project_dir: projectDir, app_name: ctx.args.name, scaffold: fromSlug },
+    humanSummary: fromSlug
+      ? `Scaffolded "${ctx.args.name}" from ${fromSlug} in ${projectDir}`
+      : `Scaffolded "${ctx.args.name}" in ${projectDir}`,
     hints: [
       { command: `cd ${projectDir} && npm install`, reason: 'Install dependencies' },
-      { command: 'npm run dev', reason: 'Start the Vite dev server' },
+      { command: `cd ${projectDir} && notis apps dev`, reason: 'Start the real-portal dev workflow' },
     ],
   });
 }
 
+async function appsScaffoldsListHandler(ctx) {
+  const scaffolds = loadScaffoldCatalog();
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { scaffolds },
+    humanSummary: scaffolds.length
+      ? `Found ${scaffolds.length} bundled scaffolds`
+      : 'No bundled scaffolds found. Run the CLI build step to generate the scaffold catalog.',
+    renderHuman: () => (scaffolds.length ? scaffoldsTable(scaffolds) : 'No bundled scaffolds found.'),
+  });
+}
+
 async function appsCreateHandler(ctx) {
   const projectDir = ctx.args.dir ? resolveProjectDir(ctx.args.dir) : null;
+  const appConfig = projectDir ? await loadAppConfig(projectDir) : null;
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
-  const icon = ctx.options.icon
-    ? (ctx.options.icon.startsWith('lucide:') ? ctx.options.icon : `lucide:${ctx.options.icon}`)
-    : undefined;
   const result = await runToolCommand({
     runtime: ctx.runtime,
     toolName: 'notis_create_app',
     arguments_: {
       name: ctx.args.name,
-      description: ctx.options.description || undefined,
-      icon,
+      description: appConfig?.description || undefined,
+      icon: appConfig?.icon || undefined,
     },
     mutating: true,
     idempotencyKey,
@@ -139,18 +552,199 @@ async function appsCreateHandler(ctx) {
 }
 
 async function appsDevHandler(ctx) {
-  const projectDir = resolveProjectDir(ctx.args.dir || '.');
-  const problems = detectProjectProblems(projectDir);
-  if (problems.length) {
-    throw usageError(`Project has problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  const rootDir = resolveProjectDir(ctx.args.dir || '.');
+  const appDirs = discoverAppDirs(rootDir);
+
+  for (const projectDir of appDirs) {
+    const problems = detectProjectProblems(projectDir);
+    if (problems.length) {
+      throw usageError(`Project ${projectDir} has problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+    }
   }
 
-  await runProjectScript({
-    projectDir,
-    scriptName: 'dev',
-    env: { NOTIS_DEV: '1' },
+  const port = ctx.options.port ? Number.parseInt(ctx.options.port, 10) : DEFAULT_DEV_PORT;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw usageError('Port must be between 1 and 65535.');
+  }
+
+  const mode = getCliMode();
+  const identity = decodeJwtSub(ctx.runtime.jwt);
+  if (!identity) {
+    throw usageError('Could not determine the current user from the CLI auth token. Open the Notis desktop app, sign in, and retry.');
+  }
+  const apiBase = String(ctx.runtime.apiBase || '').replace(/\/$/, '');
+  const sessionId = randomUUID();
+
+  const candidates = [];
+  for (const projectDir of appDirs) {
+    const appConfig = await loadAppConfig(projectDir);
+    if (!appConfig.name) {
+      throw usageError(`notis.config.ts in ${projectDir} must define a non-empty name.`);
+    }
+    const devSlug = buildDevInstallSlug(appConfig.name);
+    if (!devSlug) {
+      throw usageError(`notis.config.ts name in ${projectDir} must slugify to a non-empty value.`);
+    }
+    candidates.push({ appConfig, devSlug, projectDir });
+  }
+
+  const seenSlugs = new Map();
+  for (const app of candidates) {
+    if (seenSlugs.has(app.devSlug)) {
+      throw usageError(
+        `Multiple apps slugify to "${app.devSlug}" (${seenSlugs.get(app.devSlug).projectDir} and ${app.projectDir}). Rename one in notis.config.ts.`,
+      );
+    }
+    seenSlugs.set(app.devSlug, app);
+  }
+
+  const registrationStartedAt = process.hrtime.bigint();
+  const registered = await Promise.all(
+    candidates.map(async ({ appConfig, devSlug, projectDir }) => {
+      const appStartedAt = process.hrtime.bigint();
+      try {
+        return await ensureDevInstall({
+          ctx,
+          appConfig,
+          projectDir,
+          idempotencyKey: nextDevInstallIdempotencyKey(ctx.globalOptions, devSlug),
+        });
+      } finally {
+        logAppsTiming('ensure-dev-install', {
+          slug: devSlug,
+          ms: timingMs(appStartedAt).toFixed(1),
+        });
+      }
+    }),
+  );
+  logAppsTiming('ensure-dev-install:all', {
+    apps: registered.length,
+    ms: timingMs(registrationStartedAt).toFixed(1),
   });
 
+  const apps = registered.map((app) => {
+    const bundleBaseUrl = `http://127.0.0.1:${port}/a/${app.devSlug}`;
+    return {
+      ...app,
+      bundleBaseUrl,
+      appHref: buildAppHref({
+        appSlug: app.slug,
+        appId: app.appId,
+        manifest: app.manifest,
+      }),
+    };
+  });
+  const developmentTabUrl = buildDevelopmentDesktopUrl(apps[0]?.appHref);
+  const warnings = databaseMaterializationWarnings(apps);
+
+  const devServer = await startAppDevServer({
+    apps: apps.map((app) => ({
+      slug: app.devSlug,
+      projectDir: app.projectDir,
+      appId: app.appId,
+      userId: identity,
+    })),
+    port,
+  });
+
+  try {
+    const now = new Date().toISOString();
+    upsertAppDevSessions(apps.map((app) => ({
+      sessionId,
+      userId: identity,
+      apiBase,
+      appId: app.appId,
+      devSlug: app.devSlug,
+      bundleBaseUrl: app.bundleBaseUrl,
+      projectDir: app.projectDir,
+      startedAt: now,
+      lastHeartbeatAt: now,
+    })));
+  } catch (error) {
+    try {
+      await devServer.close();
+    } catch {
+      // ignore cleanup failure on registry errors
+    }
+    throw error;
+  }
+
+  let heartbeatTimer = setInterval(() => {
+    try {
+      heartbeatAppDevSession(sessionId, new Date().toISOString());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`[notis apps dev] heartbeat failed: ${message}\n`);
+    }
+  }, DEV_HEARTBEAT_INTERVAL_MS);
+
+  ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: {
+      mode,
+      api_base: apiBase,
+      development_url: developmentTabUrl,
+      session_id: sessionId,
+      identity,
+      apps: apps.map((app) => ({
+        slug: app.devSlug,
+        app_id: app.appId,
+        name: app.name,
+        project_dir: app.projectDir,
+        bundle_base_url: app.bundleBaseUrl,
+        app_href: app.appHref,
+        created: app.created,
+        linked_app_id: app.linkedAppId,
+        database_materialization: app.databaseMaterialization,
+      })),
+    },
+    warnings,
+    humanSummary: [
+      `Running apps dev against ${apiBase} as ${identity} (mode: ${mode})`,
+      '',
+      `Open in desktop: ${developmentTabUrl}`,
+      '',
+      ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
+      '',
+      'Press Ctrl-C to stop.',
+    ].join('\n'),
+  });
+
+  if (!ctx.options.noOpen) {
+    openInBrowser(developmentTabUrl);
+  }
+
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    process.stdout.write(`\n[notis apps dev] stopping (${signal})...\n`);
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    try {
+      removeAppDevSession(sessionId);
+    } catch {
+      // ignore cleanup failures during shutdown
+    }
+    try {
+      await devServer.close();
+    } catch {
+      // ignore cleanup failures during shutdown
+    }
+    process.exit(EXIT_CODES.ok);
+  };
+
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+
+  await new Promise(() => {});
+
   return EXIT_CODES.ok;
 }
 
@@ -170,25 +764,212 @@ async function appsBuildHandler(ctx) {
   });
 }
 
-async function appsPreviewHandler(ctx) {
+async function appsVerifyHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
-  const port = ctx.options.port ? Number.parseInt(ctx.options.port, 10) : 8787;
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw usageError('Port must be between 1 and 65535.');
+  const problems = detectProjectProblems(projectDir);
+  if (problems.length) {
+    throw usageError(`Project has problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+
+  const mode = ctx.options.mode || 'stub';
+  if (!['stub', 'live'].includes(mode)) {
+    throw usageError('--mode must be either "stub" or "live".');
+  }
+
+  let linkedState = null;
+  if (mode === 'live') {
+    if (!ctx.runtime.jwt) {
+      throw usageError('Live verify mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
+    }
+    linkedState = readLinkedState(projectDir);
+    if (!linkedState?.app_id) {
+      throw usageError('Live verify mode requires a linked app. Run `notis apps link <app-id> .` first.');
+    }
+  }
+
+  if (!ctx.options.skipBuild) {
+    await buildArtifact(projectDir);
   }
 
   const manifest = readManifest(projectDir);
-  const defaultRoute = (manifest.routes || []).find((r) => r.default) || manifest.routes?.[0];
-  const url = `http://localhost:${port}${defaultRoute?.path || '/'}`;
+  const appConfig = await loadAppConfig(projectDir);
+  const listing = inspectListingReadiness(projectDir, appConfig);
+  if (listing.errors.length) {
+    throw usageError(`Listing metadata has problems:\n${listing.errors.map((error) => `  - ${error}`).join('\n')}`);
+  }
+  const listingWarnings = listing.warnings;
+  const routes = routeSelection(manifest, parseRouteSlugs(ctx.options.routes));
+  const port = parsePort(ctx.options.port) || await getAvailablePort();
+  const appSlug = slugify(appConfig.name || manifest.app?.name || 'app') || 'app';
+  const baseUrl = `http://127.0.0.1:${port}/a/${appSlug}`;
+  const browserSessionName = `notis-verify-${process.pid}`;
+  const noBrowser = ctx.options.browser === false;
+  const keepOpen = Boolean(ctx.options.keepOpen);
+  let devServer = null;
+  let browserTouched = false;
 
-  ctx.output.emitSuccess({
-    command: ctx.spec.command_path.join(' '),
-    data: { port, url, routes: manifest.routes.length },
-    humanSummary: `Preview at ${url} -- press Ctrl+C to stop.`,
-  });
+  try {
+    devServer = await startAppDevServer({
+      apps: [{
+        slug: appSlug,
+        projectDir,
+        appId: linkedState?.app_id || 'harness-app',
+      }],
+      port,
+      watch: false,
+      harness: {
+        mode,
+        apiBase: ctx.runtime.apiBase,
+        jwt: mode === 'live' ? ctx.runtime.jwt : null,
+      },
+      log: () => {},
+      logError: (message) => process.stderr.write(`${message}\n`),
+    });
 
-  await startPreviewServer({ projectDir, port });
-  return EXIT_CODES.ok;
+    const urls = routes.map((route) => ({
+      route,
+      url: `${baseUrl}/harness?route=${encodeURIComponent(route.slug)}`,
+    }));
+
+    let results;
+    const warnings = [...listingWarnings];
+    if (noBrowser) {
+      results = urls.map(({ route, url }) => ({
+        route: route.slug,
+        path: route.path,
+        url,
+        ok: true,
+        status: 'manual',
+        mounted: null,
+        errors: [],
+        runtimeCalls: [],
+        assertions: [],
+        snapshot_path: null,
+        tool_error: null,
+      }));
+    } else if (!isAgentBrowserAvailable()) {
+      warnings.push('agent-browser is not available on PATH; rerun with --no-browser to inspect harness URLs manually.');
+      results = urls.map(({ route, url }) => {
+        const toolError = {
+          phase: 'available',
+          message: 'agent-browser is not available on PATH',
+        };
+        const result = {
+          route: route.slug,
+          path: route.path,
+          url,
+          mounted: false,
+          renderStarted: false,
+          errors: [],
+          runtimeCalls: [],
+          snapshotPath: null,
+          tool_error: toolError,
+        };
+        const assertions = assertHarnessResult(
+          result,
+          route,
+          declaredDatabaseSlugs(appConfig, manifest, route),
+        );
+        return {
+          ...result,
+          ok: false,
+          status: 'failed',
+          assertions,
+          snapshot_path: null,
+        };
+      });
+    } else {
+      browserTouched = true;
+      results = [];
+      for (const { route, url } of urls) {
+        const snapshotPath = join(projectDir, '.notis', 'output', '.harness', `${route.slug}.snapshot.txt`);
+        const result = await runHarnessRoute({
+          url,
+          sessionName: browserSessionName,
+          timeoutMs: Number.parseInt(ctx.globalOptions.timeoutMs || '', 10) || 10_000,
+          snapshotPath,
+        });
+        const assertions = assertHarnessResult(
+          result,
+          route,
+          declaredDatabaseSlugs(appConfig, manifest, route),
+        );
+        results.push({
+          route: route.slug,
+          path: route.path,
+          url,
+          ok: assertions.length === 0,
+          status: assertions.length === 0 ? 'passed' : 'failed',
+          mounted: result.mounted,
+          renderStarted: result.renderStarted,
+          errors: result.errors,
+          runtimeCalls: result.runtimeCalls,
+          assertions,
+          snapshot_path: result.snapshotPath,
+          timed_out: Boolean(result.timed_out),
+          tool_error: result.tool_error,
+        });
+      }
+    }
+
+    const summary = {
+      total: results.length,
+      passed: results.filter((result) => result.status === 'passed').length,
+      failed: results.filter((result) => result.status === 'failed').length,
+      manual: results.filter((result) => result.status === 'manual').length,
+    };
+    const overallOk = summary.failed === 0;
+    const exitCode = overallOk ? EXIT_CODES.ok : EXIT_CODES.unexpected;
+    const data = {
+      status: overallOk ? (summary.manual ? 'manual' : 'passed') : 'failed',
+      project_dir: projectDir,
+      app_slug: appSlug,
+      mode,
+      browser_session: noBrowser ? null : browserSessionName,
+      server: {
+        port,
+        base_url: baseUrl,
+        urls: urls.map(({ route, url }) => ({ route: route.slug, url })),
+      },
+      summary,
+      results,
+    };
+
+    ctx.output.emitSuccess({
+      ok: overallOk,
+      command: ctx.spec.command_path.join(' '),
+      data,
+      humanSummary: overallOk
+        ? (summary.manual ? `Harness URLs ready for ${summary.manual} routes.` : `Verified ${summary.passed} routes successfully.`)
+        : `Verification failed for ${summary.failed} routes.`,
+      warnings,
+      renderHuman: () => renderVerifyReport({ summary, results, noBrowser }),
+    });
+
+    if (keepOpen) {
+      process.stderr.write(`[notis apps verify] harness open at ${baseUrl}. Press Ctrl-C to stop.\n`);
+      await new Promise(() => {});
+    }
+
+    return exitCode;
+  } finally {
+    if (!keepOpen) {
+      if (browserTouched) {
+        try {
+          await closeAgentBrowserSession(browserSessionName);
+        } catch {
+          // Ignore browser cleanup failures.
+        }
+      }
+      if (devServer) {
+        try {
+          await devServer.close();
+        } catch {
+          // Ignore server cleanup failures.
+        }
+      }
+    }
+  }
 }
 
 async function appsLinkHandler(ctx) {
@@ -210,10 +991,60 @@ async function appsLinkHandler(ctx) {
   });
 }
 
+async function appsPullHandler(ctx) {
+  const appId = ctx.args.appId;
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: GET_APP_TOOL,
+    arguments_: { app_id: appId },
+  });
+  const app = result.payload?.app || {};
+  const defaultDir = app.slug || slugify(app.name) || appId;
+  const targetDir = resolveProjectDir(ctx.args.dir || defaultDir);
+  const version = ctx.options.version || 'latest';
+
+  const pulled = await pullAppSource({
+    apiBase: ctx.runtime.apiBase,
+    jwt: ctx.runtime.jwt,
+    appId,
+    targetDir,
+    version,
+    force: Boolean(ctx.options.force),
+  });
+
+  const versionLabel = pulled.version === 'latest' ? 'latest version' : `v${pulled.version}`;
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: {
+      app_id: appId,
+      project_dir: pulled.projectDir,
+      version: pulled.version,
+    },
+    humanSummary: `Pulled ${versionLabel} to ${pulled.projectDir}. Run \`cd ${pulled.projectDir} && npm install && notis apps dev\` to start editing.`,
+  });
+}
+
+function updateLinkedDeployState(projectDir, linkedState, appId, version) {
+  if (!linkedState || linkedState.app_id !== appId || !Number.isFinite(version)) {
+    return;
+  }
+  writeLinkedState(projectDir, {
+    ...linkedState,
+    app_id: appId,
+    version,
+    linked_at: linkedState.linked_at || new Date().toISOString(),
+    deployed_at: new Date().toISOString(),
+  });
+}
+
 async function appsDeployHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
   const appId = requireLinkedAppId(projectDir, ctx.options.appId);
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const linkedState = readLinkedState(projectDir);
+  const baseVersion = linkedState?.app_id === appId && Number.isFinite(linkedState?.version)
+    ? linkedState.version
+    : undefined;
 
   // Build if needed
   if (!ctx.options.skipBuild) {
@@ -224,6 +1055,7 @@ async function appsDeployHandler(ctx) {
   if (ctx.options.direct) {
     await assertDirectDeployAccess(ctx.runtime, appId);
     const { version } = await directDeploy(projectDir, appId);
+    updateLinkedDeployState(projectDir, linkedState, appId, version);
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(' '),
       data: { app_id: appId, version, mode: 'direct' },
@@ -234,6 +1066,7 @@ async function appsDeployHandler(ctx) {
 
   // Standard deploy via backend server, with auto-fallback to direct
   const files = collectArtifactFiles(projectDir);
+  const sourceFiles = collectSourceFiles(projectDir);
   const manifest = readManifest(projectDir);
 
   let result;
@@ -244,7 +1077,9 @@ async function appsDeployHandler(ctx) {
       arguments_: {
         app_id: appId,
         files,
+        source_files: sourceFiles,
         manifest,
+        ...(baseVersion !== undefined ? { base_version: baseVersion } : {}),
       },
       mutating: true,
       idempotencyKey,
@@ -271,6 +1106,7 @@ async function appsDeployHandler(ctx) {
 
       try {
         const { version } = await directDeploy(projectDir, appId);
+        updateLinkedDeployState(projectDir, linkedState, appId, version);
         return ctx.output.emitSuccess({
           command: ctx.spec.command_path.join(' '),
           data: { app_id: appId, version, mode: 'direct-fallback' },
@@ -289,6 +1125,7 @@ async function appsDeployHandler(ctx) {
     throw error;
   }
 
+  updateLinkedDeployState(projectDir, linkedState, appId, Number(result.payload.version));
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
@@ -312,13 +1149,21 @@ async function appsDoctorHandler(ctx) {
     problems.push('Failed to load notis.config.ts');
   }
   const warnings = detectProjectWarnings(projectDir, appConfig);
+  let listing = null;
+  if (appConfig) {
+    try {
+      listing = inspectListingReadiness(projectDir, appConfig);
+    } catch (error) {
+      warnings.push(error instanceof Error ? error.message : String(error));
+    }
+  }
 
   const linkedState = readLinkedState(projectDir);
   const status = problems.length ? 'unhealthy' : warnings.length ? 'warnings' : 'healthy';
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
-    data: { status, problems, warnings, linked: linkedState, config: appConfig },
+    data: { status, problems, warnings, linked: linkedState, config: appConfig, listing },
     humanSummary: problems.length
       ? `Found ${problems.length} problems:\n${problems.map((p) => `  - ${p}`).join('\n')}`
       : warnings.length
@@ -346,21 +1191,40 @@ export const appsCommandSpecs = [
   {
     command_path: ['apps', 'init'],
     summary: 'Scaffold a new Notis app project.',
-    when_to_use: 'Start a new Notis app. Creates a Vite + React project with @notis/sdk pre-configured.',
+    when_to_use: 'Start a new Notis app. Use --from with a bundled scaffold when one is close to the desired app; otherwise creates the bare Vite + React project.',
     args_schema: {
       arguments: [
         { token: '<name>', description: 'Display name for the app.' },
         { token: '[dir]', key: 'dir', description: 'Target directory (defaults to kebab-case of name).' },
       ],
-      options: [],
+      options: [
+        { flags: '--from <slug>', description: 'Start from a bundled scaffold listed by `notis apps scaffolds list`.' },
+      ],
     },
-    examples: ['notis apps init "Mind the Flo"', 'notis apps init "My App" ./my-app'],
+    examples: [
+      'notis apps scaffolds list',
+      'notis apps init "Mind the Flo"',
+      'notis apps init "My CRM" --from notis-database',
+      'notis apps init "My App" ./my-app',
+    ],
     mutates: true,
     idempotent: false,
     require_auth: false,
     backend_call: { type: 'local', name: 'scaffold_project' },
     handler: appsInitHandler,
   },
+  {
+    command_path: ['apps', 'scaffolds', 'list'],
+    summary: 'List bundled Notis app scaffolds.',
+    when_to_use: 'Discover the fixed scaffold catalog shipped with the CLI before starting a new app.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis apps scaffolds list', 'notis apps init "My App" --from notis-database'],
+    mutates: false,
+    idempotent: true,
+    require_auth: false,
+    backend_call: { type: 'local', name: 'list_scaffolds' },
+    handler: appsScaffoldsListHandler,
+  },
   {
     command_path: ['apps', 'create'],
     summary: 'Create a new remote Notis app and optionally link a local project to it.',
@@ -370,14 +1234,11 @@ export const appsCommandSpecs = [
         { token: '<name>', description: 'Display name for the remote app.' },
         { token: '[dir]', key: 'dir', description: 'Project directory to link after creation (default: do not link).' },
       ],
-      options: [
-        { flags: '--description <text>', description: 'Optional app description.' },
-        { flags: '--icon <lucide:icon>', description: 'Optional Lucide icon, for example lucide:dices.' },
-      ],
+      options: [],
     },
     examples: [
       'notis apps create "My App"',
-      'notis apps create "My App" . --description "Internal tool" --icon lucide:layout-dashboard',
+      'notis apps create "My App" .',
     ],
     mutates: true,
     idempotent: false,
@@ -386,25 +1247,33 @@ export const appsCommandSpecs = [
   },
   {
     command_path: ['apps', 'dev'],
-    summary: 'Run the Vite dev server for local development.',
-    when_to_use: 'Iterate on app UI with hot reload. SDK hooks return mock data.',
+    summary: 'Develop Notis apps inside the Electron desktop Portal with automatic local bundle reloads.',
+    when_to_use:
+      'Run this inside a single app or a monorepo root with apps/<name>/notis.config.ts. It discovers every app, starts the local bundle server, registers desktop-local dev sessions, and opens the Electron Portal to the local development app.',
     args_schema: {
       arguments: [
-        { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
+        { token: '[dir]', key: 'dir', description: 'Project directory or monorepo root (default: current dir).' },
+      ],
+      options: [
+        { flags: '--port <number>', description: `Local bundle server port (default: ${DEFAULT_DEV_PORT}).` },
+        { flags: '--no-open', description: 'Do not auto-open the desktop Portal local development app.' },
       ],
-      options: [],
     },
-    examples: ['notis apps dev', 'notis apps dev ./my-app'],
-    mutates: false,
+    examples: [
+      'notis apps dev',
+      'notis apps dev ./my-app',
+      'notis apps dev ./workspace --port 5200',
+    ],
+    mutates: true,
     idempotent: true,
-    require_auth: false,
-    backend_call: { type: 'local', name: 'next_dev' },
+    require_auth: true,
+    backend_call: { type: 'tool', name: ENSURE_DEV_APP_INSTALLATION_TOOL },
     handler: appsDevHandler,
   },
   {
     command_path: ['apps', 'build'],
     summary: 'Build and package the app into .notis/output/.',
-    when_to_use: 'Prepare the app for preview or deployment.',
+    when_to_use: 'Prepare the app for verification or deployment.',
     args_schema: {
       arguments: [
         { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
@@ -419,23 +1288,35 @@ export const appsCommandSpecs = [
     handler: appsBuildHandler,
   },
   {
-    command_path: ['apps', 'preview'],
-    summary: 'Serve the built bundle locally for testing.',
-    when_to_use: 'Smoke-test the exact bundle that will be deployed. Databases use seed data.',
+    command_path: ['apps', 'verify'],
+    summary: 'Headless render smoke each route in a stub-runtime harness.',
+    when_to_use:
+      'After notis apps build, before deploy. Catches render-time crashes ' +
+      'and missing runtime calls that the build step cannot detect.',
     args_schema: {
       arguments: [
         { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
       ],
       options: [
-        { flags: '--port <number>', description: 'Server port (default: 8787).' },
+        { flags: '--routes <slugs>', description: 'Comma-separated route slugs. Default: every route in manifest.' },
+        { flags: '--port <n>', description: 'Loopback port. Default: auto-pick.' },
+        { flags: '--skip-build', description: 'Skip notis apps build; reuse existing .notis/output/.' },
+        { flags: '--mode <mode>', description: 'stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT.' },
+        { flags: '--no-browser', description: 'Start the harness server and print URLs; do not drive agent-browser.' },
+        { flags: '--keep-open', description: 'Leave server + browser session running after report (for manual triage).' },
       ],
     },
-    examples: ['notis apps preview', 'notis apps preview --port 3000'],
+    examples: [
+      'notis apps verify',
+      'notis apps verify --routes notes',
+      'notis apps verify --mode live',
+      'notis apps verify --no-browser  # start the harness, drive agent-browser yourself',
+    ],
     mutates: false,
     idempotent: true,
     require_auth: false,
-    backend_call: { type: 'local', name: 'preview_server' },
-    handler: appsPreviewHandler,
+    backend_call: { type: 'local', name: 'verify_harness' },
+    handler: appsVerifyHandler,
   },
   {
     command_path: ['apps', 'link'],
@@ -455,6 +1336,28 @@ export const appsCommandSpecs = [
     backend_call: { type: 'local', name: 'write_link_state' },
     handler: appsLinkHandler,
   },
+  {
+    command_path: ['apps', 'pull'],
+    summary: 'Download a Notis app source snapshot into a local project folder.',
+    when_to_use:
+      'Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.',
+    args_schema: {
+      arguments: [
+        { token: '<app-id>', description: 'Remote app ID to pull.' },
+        { token: '[dir]', key: 'dir', description: 'Target directory (defaults to the app slug).' },
+      ],
+      options: [
+        { flags: '--force', description: 'Overwrite a non-empty target directory.' },
+        { flags: '--version <n>', description: 'Pull a specific app source version (default: latest).' },
+      ],
+    },
+    examples: ['notis apps pull abc123', 'notis apps pull abc123 ./my-app --force'],
+    mutates: true,
+    idempotent: true,
+    require_auth: true,
+    backend_call: { type: 'http', name: 'portal_apps/source' },
+    handler: appsPullHandler,
+  },
   {
     command_path: ['apps', 'deploy'],
     summary: 'Build and upload the app to the linked Notis app.',