@notis_ai/cli 0.2.4 → 0.2.6

package/src/command-specs/apps.js

@@ -2,15 +2,16 @@
  * Notis apps CLI commands.
  *
  * Canonical Notis app workflow:
- *   init -> dev -> build -> deploy
+ *   init -> dev -> build -> deploy -> publish (after explicit approval)
  *
- * Supporting commands: list, link, doctor.
+ * Supporting commands: list, link, doctor, pull.
  */
 
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, relative, resolve } from 'node:path';
 
 import { EXIT_CODES, usageError } from '../runtime/errors.js';
 import { formatTable } from '../runtime/output.js';
@@ -27,13 +28,16 @@ import {
   scaffoldProject,
   loadScaffoldCatalog,
   inspectListingReadiness,
+  resolveListingScreenshots,
   collectArtifactFiles,
   collectSourceFiles,
+  resolveConfiguredAppSkills,
   directDeploy,
   pullAppSource,
 } from '../runtime/app-platform.js';
 import { startAppDevServer } from '../runtime/app-dev-server.js';
 import {
+  captureHarnessScreenshot,
   closeAgentBrowserSession,
   isAgentBrowserAvailable,
   runHarnessRoute,
@@ -42,9 +46,12 @@ import {
   heartbeatAppDevSession,
   removeAppDevSession,
   upsertAppDevSessions,
+  waitForAppDevSessionMountAcknowledgements,
 } from '../runtime/app-dev-sessions.js';
 import { getAvailablePort } from '../runtime/ports.js';
 import { getCliMode } from '../runtime/cli-mode.js';
+import { composeStoreScreenshot } from '../runtime/store-screenshot.js';
+import { httpRequest } from '../runtime/transport.js';
 import {
   localNotisToolSlug,
   nextIdempotencyKey,
@@ -236,6 +243,15 @@ function parsePort(value) {
   return port;
 }
 
+function parsePositiveInt(value) {
+  if (!value) return null;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw usageError('Expected a positive integer.');
+  }
+  return parsed;
+}
+
 function parseRouteSlugs(value) {
   if (!value) return null;
   const slugs = String(value)
@@ -277,6 +293,36 @@ function routeSelection(manifest, rawRouteSlugs) {
   return selected;
 }
 
+export function pruneStaleScreenshotFiles(outputDir, keepCount) {
+  for (const entry of readdirSync(outputDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const match = /^screenshot-(\d+)\.png$/i.exec(entry.name);
+    if (match && Number.parseInt(match[1], 10) > keepCount) {
+      rmSync(join(outputDir, entry.name), { force: true });
+    }
+  }
+}
+
+export function shouldPruneStaleScreenshotFiles(selectedRouteSlugs, failedCount) {
+  return failedCount === 0 && !selectedRouteSlugs;
+}
+
+export function screenshotIndexByRouteSlug(manifest) {
+  const routes = Array.isArray(manifest?.routes) ? manifest.routes : [];
+  return new Map(routes.map((route, index) => [route.slug, index + 1]));
+}
+
+export function appRowFieldsFromManifest(manifest) {
+  const app = manifest?.app && typeof manifest.app === 'object' ? manifest.app : {};
+  return {
+    accent: app.accent ?? null,
+  };
+}
+
+export function screenshotExitCode(failedCount) {
+  return failedCount === 0 ? EXIT_CODES.ok : EXIT_CODES.unexpected;
+}
+
 function declaredDatabaseSlugs(appConfig, manifest, route) {
   const slugs = new Set();
   for (const entry of appConfig?.databases || manifest?.databases || []) {
@@ -395,15 +441,23 @@ function buildManifestForDev(appConfig) {
     },
     databases: appConfig.databases || [],
     tools: appConfig.tools || [],
+    skills: (appConfig.skills || []).map((skill) => ({
+      key: skill.key,
+      path: String(skill.path || '').replace(/^\.\/+/, ''),
+      name: skill.name,
+      description: skill.description || null,
+    })),
+    onboarding: appConfig.onboarding || null,
   };
 }
 
-export function buildEnsureDevInstallArguments({ appConfig, manifest, linkedState }) {
+export function buildEnsureDevInstallArguments({ appConfig, manifest, linkedState, skills }) {
   const devSlug = buildDevInstallSlug(appConfig.name);
   const arguments_ = {
     dev_slug: devSlug,
     name: appConfig.name,
     manifest,
+    skills,
   };
   if (linkedState?.dev_app_id) {
     arguments_.app_id = linkedState.dev_app_id;
@@ -427,8 +481,24 @@ export async function ensureDevInstall({
   }
 
   const manifest = buildManifestForDev(appConfig);
-  const linkedState = readLinkedState(projectDir);
-  const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState });
+  const skills = resolveConfiguredAppSkills(appConfig, projectDir);
+  let linkedState = readLinkedState(projectDir);
+  if (linkedState?.app_id) {
+    const linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
+    if (!linkedApp || linkedApp.manifest?.is_dev === true) {
+      const { app_id: legacyDevAppId, linked_at: _linkedAt, deployed_at: _deployedAt, version: _version, ...rest } = linkedState;
+      const devAppId = linkedState.dev_app_id || (linkedApp ? legacyDevAppId : null);
+      linkedState = {
+        ...rest,
+        ...(devAppId ? { dev_app_id: devAppId } : {}),
+        ...(devAppId ? {
+          dev_linked_at: linkedState.dev_linked_at || linkedState.linked_at || new Date().toISOString(),
+        } : {}),
+      };
+      writeLinkedState(projectDir, linkedState);
+    }
+  }
+  const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState, skills });
   const ensureResult = await runTool({
     runtime: ctx.runtime,
     toolName: ENSURE_DEV_APP_INSTALLATION_TOOL,
@@ -440,6 +510,14 @@ export async function ensureDevInstall({
   if (!appId) {
     throw usageError('Dev installation tool did not return an app_id.');
   }
+  if (linkedState?.dev_app_id !== appId) {
+    const now = new Date().toISOString();
+    writeLinkedState(projectDir, {
+      ...(linkedState || {}),
+      dev_app_id: appId,
+      dev_linked_at: linkedState?.dev_linked_at || now,
+    });
+  }
   return {
     slug: ensureResult.payload.slug || devSlug,
     devSlug,
@@ -449,6 +527,7 @@ export async function ensureDevInstall({
     manifest,
     created: ensureResult.payload.created || false,
     linkedAppId: linkedState?.app_id || null,
+    targetAppId: linkedState?.app_id || null,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
   };
 }
@@ -468,16 +547,48 @@ function databaseMaterializationWarnings(apps) {
   return warnings;
 }
 
-async function assertDirectDeployAccess(runtime, appId) {
-  const result = await runToolCommand({
+async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
+  const result = await runTool({
     runtime,
-    toolName: LIST_APPS_TOOL,
+    toolName: GET_APP_TOOL,
+    arguments_: { app_id: appId },
   });
-  const apps = result.payload.apps || [];
-  const hasAccess = apps.some((app) => (app.app_id || app.id) === appId);
-  if (!hasAccess) {
+  if (result.payload?.app) {
+    return {
+      ...result.payload.app,
+      apps_access: result.payload.apps_access,
+    };
+  }
+  const message = typeof result.payload?.message === 'string' ? result.payload.message : '';
+  if (result.payload?.status === 'error' && /PGRST116|0 rows|no rows|not found/i.test(message)) {
+    return null;
+  }
+  throw usageError(`Could not verify access to app ${appId}${message ? `: ${message}` : '.'}`);
+}
+
+export async function assertDirectDeployAccess(runtime, appId, runTool = runToolCommand) {
+  const app = await getAccessibleApp(runtime, appId, runTool);
+  if (!app) {
     throw usageError(`Direct deploy requires access to app ${appId}.`);
   }
+  if (app.apps_access?.has_access !== true) {
+    throw usageError('Notis Apps require a PRO+ or ULTRA plan after your trial.');
+  }
+  return app;
+}
+
+export async function assertLinkTarget(runtime, appId, runTool = runToolCommand) {
+  const app = await getAccessibleApp(runtime, appId, runTool);
+  if (!app) {
+    throw usageError(`Cannot link to inaccessible app ${appId}.`);
+  }
+  if (app.manifest?.is_dev === true) {
+    throw usageError(
+      `Cannot link to development runtime app ${appId}. ` +
+      'Link to an installed workspace app, or run `notis apps dev` without a target.',
+    );
+  }
+  return app;
 }
 
 // ---------------------------------------------------------------------------
@@ -540,6 +651,7 @@ async function appsCreateHandler(ctx) {
       name: ctx.args.name,
       description: appConfig?.description || undefined,
       icon: appConfig?.icon || undefined,
+      accent: appConfig?.accent ?? undefined,
     },
     mutating: true,
     idempotencyKey,
@@ -651,6 +763,7 @@ async function appsDevHandler(ctx) {
     return {
       ...app,
       bundleBaseUrl,
+      mountNonce: randomUUID(),
       appHref: buildAppHref({
         appSlug: app.slug,
         appId: app.appId,
@@ -669,6 +782,7 @@ async function appsDevHandler(ctx) {
       slug: app.devSlug,
       projectDir: app.projectDir,
       appId: app.appId,
+      targetAppId: app.targetAppId || null,
       userId: identity,
     })),
     port,
@@ -681,6 +795,8 @@ async function appsDevHandler(ctx) {
       userId: identity,
       apiBase,
       appId: app.appId,
+      targetAppId: app.targetAppId || undefined,
+      mountNonce: app.mountNonce,
       devSlug: app.devSlug,
       bundleBaseUrl: app.bundleBaseUrl,
       projectDir: app.projectDir,
@@ -705,6 +821,13 @@ async function appsDevHandler(ctx) {
     }
   }, DEV_HEARTBEAT_INTERVAL_MS);
 
+  const expectedMountAcknowledgements = apps.map((app) => ({
+    sessionId,
+    appId: app.appId,
+    devSlug: app.devSlug,
+    mountNonce: app.mountNonce,
+  }));
+
   ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
@@ -712,10 +835,12 @@ async function appsDevHandler(ctx) {
       api_base: apiBase,
       development_url: developmentTabUrl,
       session_id: sessionId,
+      mount_status: 'serving',
       identity,
       apps: apps.map((app) => ({
         slug: app.devSlug,
         app_id: app.appId,
+        target_app_id: app.targetAppId,
         name: app.name,
         project_dir: app.projectDir,
         bundle_base_url: app.bundleBaseUrl,
@@ -733,6 +858,8 @@ async function appsDevHandler(ctx) {
       '',
       ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
       '',
+      `Serving locally; waiting for Notis to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
+      '',
       'Press Ctrl-C to stop.',
     ].join('\n'),
   });
@@ -741,6 +868,27 @@ async function appsDevHandler(ctx) {
     openInBrowser(developmentTabUrl);
   }
 
+  void (async () => {
+    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements);
+    if (!result.mounted) {
+      process.stderr.write(
+        `[notis apps dev] Serving locally, but Notis has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open Notis.\n`,
+      );
+    }
+    while (!result.mounted) {
+      result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+        timeoutMs: 60_000,
+        pollIntervalMs: 250,
+      });
+    }
+    process.stderr.write(
+      `[notis apps dev] Mounted in Notis: ${apps.map((app) => app.name).join(', ')}.\n`,
+    );
+  })().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[notis apps dev] mount acknowledgement check failed: ${message}\n`);
+  });
+
   let shuttingDown = false;
   const shutdown = async (signal) => {
     if (shuttingDown) return;
@@ -999,10 +1147,229 @@ async function appsVerifyHandler(ctx) {
   }
 }
 
+async function appsScreenshotHandler(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')}`);
+  }
+
+  if (!isAgentBrowserAvailable()) {
+    throw usageError('agent-browser is not available on PATH. It ships with the Notis desktop app; open it once, then retry.');
+  }
+
+  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 mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
+    }
+    linkedState = readLinkedState(projectDir);
+    if (!linkedState?.app_id) {
+      throw usageError('Live mode requires a linked app. Run `notis apps link <app-id> .` first.');
+    }
+  }
+
+  if (!ctx.options.skipBuild) {
+    await buildArtifact(projectDir);
+  }
+
+  const manifest = readManifest(projectDir);
+  const appConfig = await loadAppConfig(projectDir);
+  const selectedRouteSlugs = parseRouteSlugs(ctx.options.routes);
+  const routes = routeSelection(manifest, selectedRouteSlugs);
+  const screenshotSlots = screenshotIndexByRouteSlug(manifest);
+  if (!routes.length) {
+    throw usageError('No routes to screenshot.');
+  }
+
+  const width = parsePositiveInt(ctx.options.width) || 2000;
+  const height = parsePositiveInt(ctx.options.height) || 1250;
+  const outputDir = ctx.options.outputDir
+    ? resolveProjectDir(ctx.options.outputDir)
+    : join(projectDir, 'metadata');
+
+  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-screenshot-${process.pid}`;
+  const browserSessionNames = [];
+  const configuredScreenshots = resolveListingScreenshots(projectDir, appConfig)
+    .filter((screenshot) => screenshot.route)
+    .filter((screenshot) => !selectedRouteSlugs || selectedRouteSlugs.includes(screenshot.route));
+  const routeBySlug = new Map(routes.map((route) => [route.slug, route]));
+  const captures = configuredScreenshots.length > 0
+    ? configuredScreenshots.map((screenshot) => {
+      const route = routeBySlug.get(screenshot.route);
+      if (!route) {
+        throw usageError(
+          `Screenshot ${screenshot.path} references unavailable route slug "${screenshot.route}".`,
+          { available_routes: routes.map((entry) => entry.slug) },
+        );
+      }
+      return {
+        route,
+        scenario: screenshot.scenario,
+        focus: screenshot.focus,
+        theme: screenshot.theme || 'light',
+        fileName: basename(screenshot.path),
+      };
+    })
+    : routes.map((route, index) => ({
+      route,
+      scenario: null,
+      focus: null,
+      theme: 'light',
+      fileName: `screenshot-${screenshotSlots.get(route.slug) || index + 1}.png`,
+    }));
+  const rawOutputDir = ctx.options.raw
+    ? null
+    : mkdtempSync(join(tmpdir(), 'notis-store-screenshots-'));
+  let devServer = null;
+  let browserTouched = false;
+
+  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`),
+    });
+    browserTouched = true;
+
+    mkdirSync(outputDir, { recursive: true });
+    const results = [];
+    for (const capture of captures) {
+      const { route, scenario, focus, theme, fileName } = capture;
+      const screenshotPath = join(outputDir, fileName);
+      const browserScreenshotPath = rawOutputDir
+        ? join(rawOutputDir, fileName)
+        : screenshotPath;
+      const scenarioParam = scenario ? `&scenario=${encodeURIComponent(scenario)}` : '';
+      const themeParam = `&theme=${encodeURIComponent(theme || 'light')}`;
+      // Keep scenario captures on independent pages. Chromium can otherwise
+      // reuse stale compositor layers when the next screenshot changes the
+      // same app route into a substantially different state.
+      const captureSessionName = `${browserSessionName}-${results.length + 1}`;
+      browserSessionNames.push(captureSessionName);
+      let result = await captureHarnessScreenshot({
+        url: `${baseUrl}/harness?route=${encodeURIComponent(route.slug)}${scenarioParam}${themeParam}`,
+        sessionName: captureSessionName,
+        screenshotPath: browserScreenshotPath,
+        focusSelector: ctx.options.raw ? null : focus,
+        width,
+        height,
+        timeoutMs: Number.parseInt(ctx.globalOptions.timeoutMs || '', 10) || 15_000,
+      });
+      let presentation = { mode: 'raw' };
+      if (result.ok && rawOutputDir) {
+        try {
+          presentation = await composeStoreScreenshot({
+            inputPath: browserScreenshotPath,
+            outputPath: screenshotPath,
+            width,
+            height,
+            accent: appConfig.accent,
+            seed: appConfig.name || manifest.app?.name || appSlug,
+            focused: Boolean(focus),
+            theme: theme || 'light',
+          });
+        } catch (error) {
+          result = {
+            ...result,
+            ok: false,
+            screenshotPath: null,
+            tool_error: {
+              phase: 'compose',
+              message: error instanceof Error ? error.message : String(error),
+            },
+          };
+        }
+      }
+      results.push({
+        route: route.slug,
+        path: route.path,
+        file: relative(projectDir, screenshotPath),
+        ok: result.ok,
+        errors: result.errors || [],
+        timed_out: Boolean(result.timed_out),
+        tool_error: result.tool_error,
+        framing: result.framing || null,
+        theme: theme || 'light',
+        presentation,
+      });
+    }
+
+    const captured = results.filter((r) => r.ok);
+    const failed = results.filter((r) => !r.ok);
+    const warnings = [];
+
+    // Drop stale screenshots only after a full refresh. A selected-route
+    // capture intentionally leaves other listing screenshots untouched.
+    if (shouldPruneStaleScreenshotFiles(selectedRouteSlugs, failed.length)) {
+      pruneStaleScreenshotFiles(outputDir, captures.length);
+    }
+    if (failed.length) {
+      warnings.push(`${failed.length}/${results.length} routes failed to capture; see results.`);
+    }
+
+    ctx.output.emitSuccess({
+      ok: failed.length === 0,
+      command: ctx.spec.command_path.join(' '),
+      data: {
+        project_dir: projectDir,
+        output_dir: outputDir,
+        mode,
+        presentation: ctx.options.raw ? 'raw' : 'framed',
+        viewport: { width, height },
+        summary: { total: results.length, captured: captured.length, failed: failed.length },
+        results,
+      },
+      humanSummary: failed.length === 0
+        ? `Captured ${captured.length} screenshot(s) to ${relative(projectDir, outputDir) || 'metadata'}/.`
+        : `Captured ${captured.length}/${results.length} screenshots; ${failed.length} failed.`,
+      warnings,
+    });
+    return screenshotExitCode(failed.length);
+  } finally {
+    if (browserTouched) {
+      await Promise.all(browserSessionNames.map(async (sessionName) => {
+        try {
+          await closeAgentBrowserSession(sessionName);
+        } catch {
+          // Ignore browser cleanup failures.
+        }
+      }));
+    }
+    if (devServer) {
+      try {
+        await devServer.close();
+      } catch {
+        // Ignore server cleanup failures.
+      }
+    }
+    if (rawOutputDir) {
+      rmSync(rawOutputDir, { recursive: true, force: true });
+    }
+  }
+}
+
 async function appsLinkHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
   const appId = ctx.args.appId;
 
+  await assertLinkTarget(ctx.runtime, appId);
+
   writeLinkedState(projectDir, {
     app_id: appId,
     linked_at: new Date().toISOString(),
@@ -1106,6 +1473,7 @@ async function appsDeployHandler(ctx) {
         files,
         source_files: sourceFiles,
         manifest,
+        ...appRowFieldsFromManifest(manifest),
         ...(baseVersion !== undefined ? { base_version: baseVersion } : {}),
       },
       mutating: true,
@@ -1165,6 +1533,95 @@ async function appsDeployHandler(ctx) {
   });
 }
 
+function deployedAppVersion(app) {
+  const value = app?.current_version ?? app?.manifest?.version;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+async function appsPublishHandler(ctx) {
+  if (ctx.options.confirmReady !== true) {
+    throw usageError(
+      'Store submission requires explicit user confirmation that App Details is ready. ' +
+      'After confirmation, rerun with --confirm-ready.',
+    );
+  }
+
+  const projectDir = resolveProjectDir(ctx.args.dir || '.');
+  const appId = requireLinkedAppId(projectDir, ctx.options.appId);
+  const linkedState = readLinkedState(projectDir);
+  const appConfig = await loadAppConfig(projectDir);
+  const readiness = inspectListingReadiness(projectDir, appConfig);
+  if (!readiness.ready) {
+    throw usageError(
+      `Store listing is not ready:\n${readiness.errors.map((error) => `  - ${error}`).join('\n')}`,
+    );
+  }
+
+  const detailResult = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: GET_APP_TOOL,
+    arguments_: { app_id: appId },
+  });
+  const detail = detailResult.payload || {};
+  const app = detail.app || {};
+  if (!app.id) {
+    throw usageError(`Could not load deployed app ${appId}.`);
+  }
+  if (!['team', 'public_store_hidden'].includes(app.visibility)) {
+    throw usageError('Set the app visibility to Team or Public before Store submission.');
+  }
+
+  const remoteVersion = deployedAppVersion(app);
+  if (remoteVersion <= 0) {
+    throw usageError('App has no deployed source. Run `notis apps deploy` first.');
+  }
+  if (
+    linkedState?.app_id !== appId
+    || !Number.isFinite(linkedState?.version)
+    || linkedState.version !== remoteVersion
+  ) {
+    throw usageError(
+      `Local project is not confirmed at deployed version ${remoteVersion}. ` +
+      'Run `notis apps deploy` from this project before submitting it.',
+    );
+  }
+
+  const activeSubmission = detail.active_submission || app.active_submission || null;
+  if (activeSubmission?.status === 'pending_review') {
+    throw usageError(
+      `A Store submission is already in review${activeSubmission.github_pr_url ? `: ${activeSubmission.github_pr_url}` : '.'}`,
+    );
+  }
+  if (activeSubmission?.status === 'removal_pending_review') {
+    throw usageError('Store removal is currently in review. Wait for it to finish before submitting an update.');
+  }
+
+  const result = await httpRequest({
+    runtime: ctx.runtime,
+    method: 'POST',
+    path: '/portal_apps/publish',
+    body: { app_id: appId },
+  });
+  const submission = result.payload.submission || result.payload;
+  const reviewStatus = submission.status || 'pending_review';
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: {
+      app_id: appId,
+      source_version: submission.source_version || remoteVersion,
+      submission,
+    },
+    humanSummary: reviewStatus === 'merged'
+      ? `Published app ${appId} to the Store at version ${submission.source_version || remoteVersion}`
+      : `Submitted app ${appId} version ${submission.source_version || remoteVersion} for Store review`,
+    hints: submission.github_pr_url
+      ? [{ command: submission.github_pr_url, reason: 'Review the Store registry pull request' }]
+      : [],
+    meta: { mutating: true, request_id: result.requestId },
+  });
+}
+
 async function appsDoctorHandler(ctx) {
   const projectDir = resolveProjectDir(ctx.args.dir || '.');
   const problems = detectProjectProblems(projectDir);
@@ -1316,10 +1773,10 @@ export const appsCommandSpecs = [
   },
   {
     command_path: ['apps', 'verify'],
-    summary: 'Headless render smoke each route in a stub-runtime harness.',
+    summary: 'Validate every route and the production Store listing contract.',
     when_to_use:
-      'After notis apps build, before deploy. Catches render-time crashes ' +
-      'and missing runtime calls that the build step cannot detect.',
+      'After notis apps screenshot, before deploy. Catches render-time crashes, ' +
+      'missing runtime calls, and incomplete listing media that the build step cannot detect.',
     args_schema: {
       arguments: [
         { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
@@ -1345,6 +1802,41 @@ export const appsCommandSpecs = [
     backend_call: { type: 'local', name: 'verify_harness' },
     handler: appsVerifyHandler,
   },
+  {
+    command_path: ['apps', 'screenshot'],
+    summary: 'Capture configured listing route/scenario states via the headless harness.',
+    when_to_use:
+      'Generate the 3–6 declared metadata/screenshot-N.png files for the App Store listing. Apps are ' +
+      'icon-led (like Raycast) — there is no cover image, only these screenshots. ' +
+      'Each screenshot may set a focus selector to remove empty canvas and a light or dark theme that also controls its Store frame. ' +
+      'Run before notis apps verify / deploy / publish.',
+    args_schema: {
+      arguments: [
+        { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
+      ],
+      options: [
+        { flags: '--routes <slugs>', description: 'Comma-separated route slugs. Default: every configured screenshot state.' },
+        { flags: '--port <n>', description: 'Loopback port. Default: auto-pick.' },
+        { flags: '--width <px>', description: 'Viewport width. Default: 2000.' },
+        { flags: '--height <px>', description: 'Viewport height. Default: 1250 (16:10).' },
+        { flags: '--output-dir <dir>', description: 'Where to write screenshot-N.png. Default: metadata/.' },
+        { flags: '--mode <mode>', description: 'stub | live. Default stub. Live renders against real data via the CLI JWT (requires a linked app), so screenshots show actual content instead of empty states.' },
+        { flags: '--raw', description: 'Write the unframed harness capture instead of the default Store presentation.' },
+        { flags: '--skip-build', description: 'Skip notis apps build; reuse existing .notis/output/.' },
+      ],
+    },
+    examples: [
+      'notis apps screenshot  # honors notis.config.ts screenshot scenarios',
+      'notis apps screenshot --routes home,history',
+      'notis apps screenshot --mode live  # populated screenshots from real data',
+      'notis apps screenshot --raw  # diagnostic capture without Store framing',
+    ],
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    backend_call: { type: 'local', name: 'screenshot_routes' },
+    handler: appsScreenshotHandler,
+  },
   {
     command_path: ['apps', 'link'],
     summary: 'Link a local project to a remote Notis app.',
@@ -1406,6 +1898,27 @@ export const appsCommandSpecs = [
     backend_call: { type: 'tool', name: SAVE_APP_FILES_TOOL },
     handler: appsDeployHandler,
   },
+  {
+    command_path: ['apps', 'publish'],
+    summary: 'Submit the deployed app for Store review.',
+    when_to_use:
+      'After the user explicitly confirms the App Details page and Store listing are ready. Requires the current local project to match the latest deployed version.',
+    args_schema: {
+      arguments: [
+        { token: '[dir]', key: 'dir', description: 'Project directory (default: current dir).' },
+      ],
+      options: [
+        { flags: '--app-id <id>', description: 'Override linked app ID.' },
+        { flags: '--confirm-ready', description: 'Confirm the user approved the current App Details page for Store submission.' },
+      ],
+    },
+    examples: ['notis apps publish --confirm-ready', 'notis apps publish ./my-app --confirm-ready'],
+    mutates: true,
+    idempotent: false,
+    require_auth: true,
+    backend_call: { type: 'http', name: 'portal_apps/publish' },
+    handler: appsPublishHandler,
+  },
   {
     command_path: ['apps', 'doctor'],
     summary: 'Check project health and readiness.',