@notis_ai/cli 0.2.5 → 0.2.7

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, mkdirSync, readdirSync, rmSync } from 'node:fs';
-import { join, relative, 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,8 +28,10 @@ import {
   scaffoldProject,
   loadScaffoldCatalog,
   inspectListingReadiness,
+  resolveListingScreenshots,
   collectArtifactFiles,
   collectSourceFiles,
+  resolveConfiguredAppSkills,
   directDeploy,
   pullAppSource,
 } from '../runtime/app-platform.js';
@@ -43,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,
@@ -435,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;
@@ -467,20 +481,24 @@ export async function ensureDevInstall({
   }
 
   const manifest = buildManifestForDev(appConfig);
+  const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   let linkedState = readLinkedState(projectDir);
   if (linkedState?.app_id) {
-    const linkedApp = await assertDirectDeployAccess(ctx.runtime, linkedState.app_id, runTool);
-    if (!linkedState.dev_app_id && linkedApp?.manifest?.is_dev === true) {
+    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,
-        dev_app_id: legacyDevAppId,
-        dev_linked_at: linkedState.dev_linked_at || linkedState.linked_at || new Date().toISOString(),
+        ...(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 });
+  const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState, skills });
   const ensureResult = await runTool({
     runtime: ctx.runtime,
     toolName: ENSURE_DEV_APP_INSTALLATION_TOOL,
@@ -529,16 +547,47 @@ function databaseMaterializationWarnings(apps) {
   return warnings;
 }
 
-async function assertDirectDeployAccess(runtime, appId, runTool = 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 app = apps.find((candidate) => (candidate.app_id || candidate.id) === appId) || null;
+  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;
 }
 
@@ -714,6 +763,7 @@ async function appsDevHandler(ctx) {
     return {
       ...app,
       bundleBaseUrl,
+      mountNonce: randomUUID(),
       appHref: buildAppHref({
         appSlug: app.slug,
         appId: app.appId,
@@ -746,6 +796,7 @@ async function appsDevHandler(ctx) {
       apiBase,
       appId: app.appId,
       targetAppId: app.targetAppId || undefined,
+      mountNonce: app.mountNonce,
       devSlug: app.devSlug,
       bundleBaseUrl: app.bundleBaseUrl,
       projectDir: app.projectDir,
@@ -770,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: {
@@ -777,6 +835,7 @@ async function appsDevHandler(ctx) {
       api_base: apiBase,
       development_url: developmentTabUrl,
       session_id: sessionId,
+      mount_status: 'serving',
       identity,
       apps: apps.map((app) => ({
         slug: app.devSlug,
@@ -799,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'),
   });
@@ -807,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;
@@ -1115,6 +1197,38 @@ async function appsScreenshotHandler(ctx) {
   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;
 
@@ -1135,20 +1249,53 @@ async function appsScreenshotHandler(ctx) {
 
     mkdirSync(outputDir, { recursive: true });
     const results = [];
-    let index = 0;
-    for (const route of routes) {
-      index += 1;
-      const slotIndex = screenshotSlots.get(route.slug) || index;
-      const fileName = `screenshot-${slotIndex}.png`;
+    for (const capture of captures) {
+      const { route, scenario, focus, theme, fileName } = capture;
       const screenshotPath = join(outputDir, fileName);
-      const result = await captureHarnessScreenshot({
-        url: `${baseUrl}/harness?route=${encodeURIComponent(route.slug)}`,
-        sessionName: browserSessionName,
-        screenshotPath,
+      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,
@@ -1157,6 +1304,9 @@ async function appsScreenshotHandler(ctx) {
         errors: result.errors || [],
         timed_out: Boolean(result.timed_out),
         tool_error: result.tool_error,
+        framing: result.framing || null,
+        theme: theme || 'light',
+        presentation,
       });
     }
 
@@ -1167,7 +1317,7 @@ async function appsScreenshotHandler(ctx) {
     // 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, routes.length);
+      pruneStaleScreenshotFiles(outputDir, captures.length);
     }
     if (failed.length) {
       warnings.push(`${failed.length}/${results.length} routes failed to capture; see results.`);
@@ -1180,6 +1330,7 @@ async function appsScreenshotHandler(ctx) {
         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,
@@ -1192,11 +1343,13 @@ async function appsScreenshotHandler(ctx) {
     return screenshotExitCode(failed.length);
   } finally {
     if (browserTouched) {
-      try {
-        await closeAgentBrowserSession(browserSessionName);
-      } catch {
-        // Ignore browser cleanup failures.
-      }
+      await Promise.all(browserSessionNames.map(async (sessionName) => {
+        try {
+          await closeAgentBrowserSession(sessionName);
+        } catch {
+          // Ignore browser cleanup failures.
+        }
+      }));
     }
     if (devServer) {
       try {
@@ -1205,6 +1358,9 @@ async function appsScreenshotHandler(ctx) {
         // Ignore server cleanup failures.
       }
     }
+    if (rawOutputDir) {
+      rmSync(rawOutputDir, { recursive: true, force: true });
+    }
   }
 }
 
@@ -1212,6 +1368,8 @@ 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(),
@@ -1375,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);
@@ -1526,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).' },
@@ -1557,29 +1804,32 @@ export const appsCommandSpecs = [
   },
   {
     command_path: ['apps', 'screenshot'],
-    summary: 'Capture listing screenshots of each route via the headless harness.',
+    summary: 'Capture configured listing route/scenario states via the headless harness.',
     when_to_use:
-      'Generate metadata/screenshot-N.png for the App Store listing. Apps are ' +
+      '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 route in manifest.' },
+        { 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',
+      '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,
@@ -1648,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.',