@notis_ai/cli 0.2.4 → 0.2.6

package/src/runtime/app-platform.js

@@ -9,12 +9,13 @@
 import { spawn } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
 
 import { usageError } from './errors.js';
 import { validateArtifactBoundary, validateProjectBoundary } from './app-boundary-validator.js';
+import { readAppChangelog } from './app-changelog.js';
 
 const NOTIS_DIR = '.notis';
 const STATE_FILE = join(NOTIS_DIR, 'state.json');
@@ -35,6 +36,7 @@ export const NOTIS_APP_CATEGORIES = [
   'Product & Engineering',
   'Personal',
 ];
+export const MIN_LISTING_SCREENSHOTS = 3;
 const SOURCE_COPY_EXCLUDES = new Set([
   'node_modules',
   '.notis',
@@ -236,7 +238,7 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
   if (appConfig) {
     try {
       const listing = inspectListingReadiness(projectDir, appConfig);
-      warnings.push(...listing.warnings);
+      warnings.push(...listing.errors, ...listing.warnings);
     } catch (error) {
       warnings.push(error instanceof Error ? error.message : String(error));
     }
@@ -291,11 +293,10 @@ function pngDimensions(buffer) {
   };
 }
 
-function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6 }) {
+function imageAssetMeta(projectDir, relPath, { maxBytes }) {
   const fullPath = join(projectDir, relPath);
   const content = readFileSync(fullPath);
   const dimensions = pngDimensions(content);
-  const ratio = dimensions?.height ? dimensions.width / dimensions.height : null;
   const errors = [];
   const warnings = [];
 
@@ -305,10 +306,10 @@ function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6
   if (content.length > maxBytes) {
     errors.push(`${relPath} must be ${Math.round(maxBytes / 1024 / 1024)} MB or smaller.`);
   }
-  if (ratio !== null && (ratio < 1.3 || ratio > 1.9)) {
-    errors.push(`${relPath} should be close to a 16:10 aspect ratio.`);
-  } else if (ratio !== null && Math.abs(ratio - recommendedRatio) > 0.08) {
-    warnings.push(`${relPath} is not 2000x1250; 16:10 PNG is recommended.`);
+  if (!dimensions) {
+    errors.push(`${relPath} is not a valid PNG file.`);
+  } else if (dimensions.width !== 2000 || dimensions.height !== 1250) {
+    errors.push(`${relPath} must be exactly 2000x1250 pixels.`);
   }
 
   return {
@@ -324,10 +325,6 @@ function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6
 
 export function discoverMetadataAssets(projectDir) {
   const metadataDir = join(projectDir, METADATA_DIR);
-  const coverPath = join(METADATA_DIR, 'cover.png');
-  const cover = existsSync(join(projectDir, coverPath))
-    ? imageAssetMeta(projectDir, coverPath, { maxBytes: 5 * 1024 * 1024 })
-    : null;
   const screenshots = [];
 
   if (existsSync(metadataDir)) {
@@ -346,44 +343,139 @@ export function discoverMetadataAssets(projectDir) {
 
   screenshots.sort((a, b) => a.index - b.index);
   return {
-    cover,
     screenshots: screenshots.slice(0, 6),
   };
 }
 
+function normalizeConfiguredScreenshots(appConfig = null) {
+  if (!Array.isArray(appConfig?.screenshots) || appConfig.screenshots.length === 0) {
+    return null;
+  }
+  if (appConfig.screenshots.length > 6) {
+    throw usageError('Configure at most six listing screenshots.');
+  }
+
+  const seenPaths = new Set();
+  return appConfig.screenshots.map((entry, index) => {
+    const path = typeof entry?.path === 'string' ? entry.path.trim().replace(/\\/g, '/') : '';
+    const alt = typeof entry?.alt === 'string' ? entry.alt.trim() : '';
+    const route = typeof entry?.route === 'string' ? entry.route.trim() : '';
+    const scenario = typeof entry?.scenario === 'string' ? entry.scenario.trim() : '';
+    const focus = typeof entry?.focus === 'string' ? entry.focus.trim() : '';
+    const theme = typeof entry?.theme === 'string' ? entry.theme.trim().toLowerCase() : '';
+    if (!/^metadata\/screenshot-\d+\.png$/i.test(path)) {
+      throw usageError(`screenshots[${index}].path must match metadata/screenshot-N.png.`);
+    }
+    const expectedPath = `metadata/screenshot-${index + 1}.png`;
+    if (path !== expectedPath) {
+      throw usageError(`screenshots[${index}].path must be ${expectedPath} so capture order stays stable.`);
+    }
+    if (seenPaths.has(path)) {
+      throw usageError(`Duplicate listing screenshot path: ${path}`);
+    }
+    if (theme && theme !== 'light' && theme !== 'dark') {
+      throw usageError(`screenshots[${index}].theme must be light or dark.`);
+    }
+    seenPaths.add(path);
+    return {
+      path,
+      alt,
+      route: route || null,
+      scenario: scenario || null,
+      focus: focus || null,
+      theme: theme || 'light',
+    };
+  });
+}
+
+/** Resolve listing screenshot files in their configured editorial order. */
+export function resolveListingScreenshots(projectDir, appConfig = null) {
+  const discovered = discoverMetadataAssets(projectDir).screenshots;
+  const configured = normalizeConfiguredScreenshots(appConfig);
+  if (!configured) {
+    return discovered.map((asset) => ({
+      ...asset,
+      alt: null,
+      route: null,
+      scenario: null,
+      focus: null,
+      theme: 'light',
+    }));
+  }
+
+  const byPath = new Map(discovered.map((asset) => [asset.path.replace(/\\/g, '/'), asset]));
+  return configured.map((entry) => {
+    const asset = byPath.get(entry.path);
+    if (!asset) {
+      return {
+        ...entry,
+        content_type: 'image/png',
+        bytes: null,
+        width: null,
+        height: null,
+        errors: [`${entry.path} is configured but the file does not exist.`],
+        warnings: [],
+      };
+    }
+    return { ...asset, ...entry };
+  });
+}
+
 export function inspectListingReadiness(projectDir, appConfig = null) {
   const config = appConfig || {};
   const warnings = [];
   const errors = [];
-  const metadata = discoverMetadataAssets(projectDir);
+  const screenshots = resolveListingScreenshots(projectDir, config);
+  const metadata = { screenshots };
   const categories = normalizeCategories(config.categories || []);
+  const changelog = readAppChangelog(projectDir);
+  errors.push(...changelog.errors);
+
+  const packagePath = join(projectDir, 'package.json');
+  if (!existsSync(packagePath)) {
+    errors.push('package.json is required for Store publication.');
+  } else {
+    try {
+      const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+      const notisAppVersion = String(packageJson.notisAppVersion || '').trim();
+      if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(notisAppVersion)) {
+        errors.push('package.json must include a semver `notisAppVersion` (for example, "0.1.0").');
+      }
+    } catch {
+      errors.push('package.json must contain valid JSON for Store publication.');
+    }
+  }
 
   if (!String(config.tagline || '').trim()) {
-    warnings.push('Listing tagline missing in notis.config.ts.');
+    errors.push('Listing tagline missing in notis.config.ts.');
   }
   if (categories.length === 0) {
-    warnings.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
-  }
-  if (!metadata.cover) {
-    warnings.push('Listing cover missing at metadata/cover.png.');
-  } else {
-    errors.push(...metadata.cover.errors);
-    warnings.push(...metadata.cover.warnings);
+    errors.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
   }
-  if (metadata.screenshots.length < 3) {
-    warnings.push(`Listing screenshots: ${metadata.screenshots.length}/3 minimum in metadata/screenshot-N.png.`);
+  if (metadata.screenshots.length < MIN_LISTING_SCREENSHOTS) {
+    errors.push(`Listing screenshots: ${metadata.screenshots.length}/${MIN_LISTING_SCREENSHOTS} minimum in metadata/screenshot-N.png. Run \`notis apps screenshot\` to generate them.`);
   }
   for (const screenshot of metadata.screenshots) {
     errors.push(...screenshot.errors);
     warnings.push(...screenshot.warnings);
+    if (!screenshot.alt) {
+      errors.push(`${screenshot.path} is missing descriptive alt text in notis.config.ts -> screenshots.`);
+    }
   }
 
   return {
-    ready: errors.length === 0 && Boolean(config.tagline) && categories.length > 0 && Boolean(metadata.cover) && metadata.screenshots.length >= 1,
+    ready:
+      errors.length === 0 &&
+      Boolean(String(config.tagline || '').trim()) &&
+      categories.length > 0 &&
+      metadata.screenshots.length >= MIN_LISTING_SCREENSHOTS &&
+      metadata.screenshots.every((screenshot) => Boolean(screenshot.alt)) &&
+      changelog.entries.length > 0,
     warnings,
     errors,
     metadata,
     categories,
+    changelog,
   };
 }
 
@@ -617,27 +709,43 @@ export function generateManifest(appConfig, projectDir) {
 
   const databases = appConfig.databases || [];
   const categories = normalizeCategories(appConfig.categories || []);
-  const metadata = discoverMetadataAssets(projectDir);
+  const metadata = { screenshots: resolveListingScreenshots(projectDir, appConfig) };
   const appSlug = safeKebab(appConfig.name);
   const displayTitle = appConfig.title || appConfig.displayName || appConfig.name;
+  const skills = (Array.isArray(appConfig.skills) ? appConfig.skills : []).map((skill) => ({
+    key: skill.key,
+    path: String(skill.path || '').replace(/^\.\/+/, ''),
+    name: skill.name,
+    description: skill.description || null,
+  }));
   const listingMedia = {
-    cover: metadata.cover
-      ? {
-          path: metadata.cover.path,
-          content_type: metadata.cover.content_type,
-          width: metadata.cover.width,
-          height: metadata.cover.height,
-          bytes: metadata.cover.bytes,
-        }
-      : null,
     screenshots: metadata.screenshots.map((screenshot) => ({
       path: screenshot.path,
       content_type: screenshot.content_type,
       width: screenshot.width,
       height: screenshot.height,
       bytes: screenshot.bytes,
+      alt: screenshot.alt || null,
+      theme: screenshot.theme || 'light',
     })),
   };
+  const changelog = readAppChangelog(projectDir);
+  if (changelog.exists && changelog.errors.length > 0) {
+    throw usageError(changelog.errors.join('\n'));
+  }
+  const latestChangelogEntry = changelog.entries[0] || null;
+  const legacyVersionNotes = latestChangelogEntry?.body
+    || appConfig.versionNotes
+    || appConfig.version_notes
+    || null;
+  let releaseVersion = null;
+  try {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+    releaseVersion = String(packageJson.notisAppVersion || '').trim() || null;
+  } catch {
+    // Store readiness reports missing or malformed package metadata. Ordinary
+    // development builds remain usable without a Store release version.
+  }
 
   return {
     version: 1,
@@ -647,18 +755,28 @@ export function generateManifest(appConfig, projectDir) {
       slug: appSlug || null,
       description: appConfig.description || null,
       icon: appConfig.icon || null,
+      accent: appConfig.accent || null,
       title: displayTitle,
       tagline: appConfig.tagline || null,
       categories,
       author: appConfig.author || null,
-      version_notes: appConfig.versionNotes || appConfig.version_notes || null,
+      release_version: releaseVersion,
+      version_notes: legacyVersionNotes,
     },
     listing: {
       title: displayTitle,
       tagline: appConfig.tagline || null,
       categories,
       author: appConfig.author || null,
-      version_notes: appConfig.versionNotes || appConfig.version_notes || null,
+      version_notes: legacyVersionNotes,
+      ...(changelog.exists
+        ? {
+            changelog: {
+              source_path: changelog.source_path,
+              entries: changelog.entries,
+            },
+          }
+        : {}),
       media: listingMedia,
     },
     metadata: listingMedia,
@@ -669,9 +787,47 @@ export function generateManifest(appConfig, projectDir) {
     },
     databases,
     tools: appConfig.tools || [],
+    skills,
+    onboarding: appConfig.onboarding || null,
   };
 }
 
+export function resolveConfiguredAppSkills(appConfig, projectDir) {
+  const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
+  const projectRoot = resolve(projectDir);
+  const seenKeys = new Set();
+
+  return configured.map((skill, index) => {
+    const key = typeof skill?.key === 'string' ? skill.key.trim() : '';
+    const sourcePath = typeof skill?.path === 'string' ? skill.path.trim() : '';
+    const name = typeof skill?.name === 'string' ? skill.name.trim() : '';
+    if (!key || !sourcePath || !name) {
+      throw usageError(`skills[${index}] must define non-empty key, path, and name values.`);
+    }
+    if (seenKeys.has(key)) {
+      throw usageError(`Duplicate app skill key: ${key}`);
+    }
+    seenKeys.add(key);
+
+    const absolutePath = resolve(projectRoot, sourcePath);
+    const relativePath = relative(projectRoot, absolutePath).replace(/\\/g, '/');
+    if (!relativePath || relativePath.startsWith('../') || relativePath === '..') {
+      throw usageError(`App skill path must stay inside the project: ${sourcePath}`);
+    }
+    if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
+
+    return {
+      key,
+      path: relativePath,
+      name,
+      description: typeof skill.description === 'string' ? skill.description.trim() : null,
+      skill_md: readFileSync(absolutePath, 'utf8'),
+    };
+  });
+}
+
 /**
  * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
  */
@@ -714,14 +870,18 @@ export function readManifest(projectDir) {
 
 function copyMetadataAssets(projectDir) {
   const metadataDir = join(projectDir, METADATA_DIR);
+  const outputMetadataDir = join(projectDir, OUTPUT_DIR, METADATA_DIR);
+  // Vite clears the bundle directory, not sibling listing media. Always make
+  // the packaged metadata an exact reflection of the source tree so removed
+  // placeholders can never survive into a later deploy.
+  rmSync(outputMetadataDir, { recursive: true, force: true });
   if (!existsSync(metadataDir)) {
     return;
   }
-  const outputMetadataDir = join(projectDir, OUTPUT_DIR, METADATA_DIR);
   mkdirSync(outputMetadataDir, { recursive: true });
   for (const entry of readdirSync(metadataDir, { withFileTypes: true })) {
     if (!entry.isFile()) continue;
-    if (entry.name !== 'cover.png' && !/^screenshot-\d+\.png$/i.test(entry.name)) {
+    if (!/^screenshot-\d+\.png$/i.test(entry.name)) {
       continue;
     }
     cpSync(join(metadataDir, entry.name), join(outputMetadataDir, entry.name));
@@ -1259,6 +1419,7 @@ async function updateAppVersion(supabaseUrl, supabaseKey, appId, newVersion, man
     },
     body: JSON.stringify({
       manifest: { ...manifest, version: newVersion },
+      accent: manifest?.app?.accent ?? null,
       updated_at: new Date().toISOString(),
     }),
   });

package/src/runtime/desktop-auth.js

@@ -0,0 +1,93 @@
+import { CliError, EXIT_CODES } from './errors.js';
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function quoteShellArgument(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function defaultDesktopAppName(apiBase) {
+  try {
+    return new URL(apiBase).hostname === 'api-beta.notis.ai' ? 'Notis Beta' : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function getDesktopAuthRecovery(runtime) {
+  const desktopRunning = isPidRunning(runtime.desktopPid);
+  const appName = runtime.desktopAppName || defaultDesktopAppName(runtime.apiBase);
+  let command = 'Start the Notis desktop app';
+  if (process.platform === 'darwin') {
+    command = `open -a ${quoteShellArgument(appName)}`;
+  }
+
+  return {
+    desktopRunning,
+    appName,
+    hints: [
+      {
+        command,
+        reason: desktopRunning
+          ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
+          : `Start ${appName} to renew expired CLI authentication, then retry`,
+      },
+      {
+        command: 'notis doctor',
+        reason: 'Retry the auth and API checks after the desktop app is ready',
+      },
+    ],
+  };
+}
+
+export function createExpiredAuthError(runtime) {
+  if (runtime.credentialSource === 'env') {
+    return new CliError({
+      code: 'auth_expired',
+      message: 'NOTIS_JWT is expired',
+      exitCode: EXIT_CODES.auth,
+      details: { credential_source: 'env' },
+      hints: [
+        {
+          command: 'Set NOTIS_JWT to a fresh token',
+          reason: 'The explicit environment credential overrides desktop-managed auth',
+        },
+      ],
+    });
+  }
+
+  const recovery = getDesktopAuthRecovery(runtime);
+  return new CliError({
+    code: 'auth_expired',
+    message: 'Notis CLI authentication has expired',
+    exitCode: EXIT_CODES.auth,
+    details: {
+      credential_source: 'desktop',
+      desktop_running: recovery.desktopRunning,
+      desktop_app_name: recovery.appName,
+    },
+    hints: recovery.hints,
+  });
+}
+
+export function createInvalidAuthHints(runtime) {
+  if (runtime?.credentialSource === 'env') {
+    return [
+      {
+        command: 'Set NOTIS_JWT to a fresh token',
+        reason: 'The explicit environment credential was rejected',
+      },
+    ];
+  }
+  return getDesktopAuthRecovery(runtime || {}).hints;
+}

package/src/runtime/profiles.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
+import { getDesktopAuthRecovery } from './desktop-auth.js';
 
 export const CONFIG_DIR = join(homedir(), '.notis');
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
@@ -37,6 +38,9 @@ export function normalizeConfig(rawConfig = {}) {
           typeof profile.access_expires_at === 'number' ? profile.access_expires_at : undefined,
         refresh_expires_at:
           typeof profile.refresh_expires_at === 'number' ? profile.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof profile.desktop_app_name === 'string' ? profile.desktop_app_name : undefined,
+        desktop_pid: typeof profile.desktop_pid === 'number' ? profile.desktop_pid : undefined,
       };
     }
 
@@ -65,6 +69,9 @@ export function normalizeConfig(rawConfig = {}) {
           typeof raw.access_expires_at === 'number' ? raw.access_expires_at : undefined,
         refresh_expires_at:
           typeof raw.refresh_expires_at === 'number' ? raw.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof raw.desktop_app_name === 'string' ? raw.desktop_app_name : undefined,
+        desktop_pid: typeof raw.desktop_pid === 'number' ? raw.desktop_pid : undefined,
       },
     },
   };
@@ -199,34 +206,30 @@ export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true }
   const timeoutMs = resolveTimeoutMs(globalOptions);
 
   if (requireAuth && !jwt) {
+    const recovery = getDesktopAuthRecovery({
+      apiBase,
+      desktopAppName: profile.desktop_app_name,
+      desktopPid: profile.desktop_pid,
+    });
     throw new CliError({
       code: 'auth_missing',
       message: `No JWT configured for profile ${profileName}`,
       exitCode: EXIT_CODES.auth,
-      hints: [
-        {
-          command: 'Open the Notis desktop app and sign in',
-          reason: 'Set NOTIS_JWT or sign in through the Notis desktop app',
-        },
-      ],
+      hints: recovery.hints,
     });
   }
 
-  // An explicit NOTIS_JWT is a complete credential override: use it verbatim and do
-  // NOT attempt a stored-profile dev_portal token refresh (whose refresh_token may be
-  // stale or belong to a different session). Without this, a long-lived shell with an
-  // expired profile refresh_token fails every command with invalid_grant even though
-  // the supplied NOTIS_JWT is valid.
+  // An explicit NOTIS_JWT is a complete credential override. Use it verbatim
+  // and never replace it with a token later synced by the desktop profile.
   const usingEnvJwt = Boolean(process.env.NOTIS_JWT);
   return {
     config,
     profileName,
     apiBase,
     jwt,
-    authMode: usingEnvJwt ? 'jwt' : profile.auth_mode,
-    refreshToken: usingEnvJwt ? undefined : profile.refresh_token,
-    accessExpiresAt: usingEnvJwt ? undefined : profile.access_expires_at,
-    refreshExpiresAt: usingEnvJwt ? undefined : profile.refresh_expires_at,
+    credentialSource: usingEnvJwt ? 'env' : 'profile',
+    desktopAppName: usingEnvJwt ? undefined : profile.desktop_app_name,
+    desktopPid: usingEnvJwt ? undefined : profile.desktop_pid,
     agentMode,
     nonInteractive,
     outputMode,
@@ -234,6 +237,25 @@ export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true }
   };
 }
 
+export function getJwtExpiration(jwt) {
+  if (typeof jwt !== 'string' || !jwt) {
+    return null;
+  }
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return typeof payload.exp === 'number' ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isJwtExpired(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const expiration = getJwtExpiration(jwt);
+  return expiration !== null && expiration <= nowSeconds;
+}
+
 export function workspacePath(appId) {
   return join(WORKSPACE_DIR, appId);
 }