@notis_ai/cli 0.2.12 → 0.2.14

package/src/runtime/app-platform.js

@@ -7,7 +7,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -15,7 +15,7 @@ import { gunzipSync } from 'node:zlib';
 
 import { usageError } from './errors.js';
 import { validateArtifactBoundary, validateProjectBoundary } from './app-boundary-validator.js';
-import { readAppChangelog } from './app-changelog.js';
+import { CHANGELOG_MERGE_DATE, readAppChangelog } from './app-changelog.js';
 
 const NOTIS_DIR = '.notis';
 const STATE_FILE = join(NOTIS_DIR, 'state.json');
@@ -44,6 +44,9 @@ const SOURCE_COPY_EXCLUDES = new Set([
   'dist',
   'tsconfig.tsbuildinfo',
   '.DS_Store',
+  // Interpreter droppings: a stray `python -m py_compile` in a skill's
+  // scripts/ directory must not ship version-specific bytecode in the bundle.
+  '__pycache__',
 ]);
 const SCAFFOLD_COPY_EXCLUDES = new Set([
   ...SOURCE_COPY_EXCLUDES,
@@ -51,6 +54,17 @@ const SCAFFOLD_COPY_EXCLUDES = new Set([
   '.next',
   '.turbo',
 ]);
+// Listing media describes the scaffold's own Store entry, so a new project must
+// never inherit it. Scaffold packaging still ships these files -- only the
+// `apps init` copy drops them. Screenshots only: `screenshot-fixtures.json` is
+// not listing media, it is the stub data the dev harness serves, and dropping
+// it would make every route of a fresh project render its empty state.
+const SCAFFOLD_LISTING_MEDIA = /^metadata\/screenshot-\d+\.png$/i;
+// A directory-declared skill ships every supporting file to the sandbox, so it
+// needs a ceiling of its own. Kept well above the 512 KB SKILL.md limit so a
+// handful of scripts always fits, and far below the bundle machinery's own
+// limits so an accidental asset dump fails on the client with a clear message.
+export const MAX_APP_SKILL_BUNDLE_BYTES = 5 * 1024 * 1024;
 let appConfigImportNonce = 0;
 
 // ---------------------------------------------------------------------------
@@ -427,6 +441,39 @@ export function resolveListingScreenshots(projectDir, appConfig = null) {
   });
 }
 
+/**
+ * Screenshot scenarios named in notis.config.ts that metadata/screenshot-fixtures.json
+ * does not define. A missing scenario is silent at capture time -- the harness
+ * simply falls back to the default fixtures -- so it is reported as a warning.
+ */
+export function findUnknownScreenshotScenarios(projectDir, screenshots = []) {
+  const named = screenshots.filter((entry) => entry?.scenario);
+  if (named.length === 0) {
+    return [];
+  }
+  const fixturesPath = join(projectDir, METADATA_DIR, 'screenshot-fixtures.json');
+  if (!existsSync(fixturesPath)) {
+    return ['metadata/screenshot-fixtures.json is missing, so screenshot scenarios cannot be applied.'];
+  }
+  let defined;
+  try {
+    const parsed = JSON.parse(readFileSync(fixturesPath, 'utf-8'));
+    const scenarios = parsed?.scenarios && typeof parsed.scenarios === 'object' ? parsed.scenarios : {};
+    defined = new Set(Object.keys(scenarios));
+  } catch {
+    return ['metadata/screenshot-fixtures.json is not valid JSON, so screenshot scenarios cannot be applied.'];
+  }
+  const warnings = [];
+  for (const entry of named) {
+    if (!defined.has(entry.scenario)) {
+      warnings.push(
+        `${entry.path} names scenario "${entry.scenario}", which metadata/screenshot-fixtures.json does not define.`,
+      );
+    }
+  }
+  return warnings;
+}
+
 export function inspectListingReadiness(projectDir, appConfig = null) {
   const config = appConfig || {};
   const warnings = [];
@@ -738,7 +785,7 @@ export function generateManifest(appConfig, projectDir) {
   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(/^\.\/+/, ''),
+    path: normalizeAppSkillManifestPath(skill.path),
     name: skill.name,
     description: skill.description || null,
   }));
@@ -830,12 +877,54 @@ export function normalizeAppCapabilities(capabilities) {
   if (capabilities.workspaceDatabases === 'read') {
     normalized.workspaceDatabases = 'read';
   }
+  if (capabilities.cloudComputer === 'read' || capabilities.cloudComputer === 'shell') {
+    normalized.cloudComputer = capabilities.cloudComputer;
+  }
   return normalized;
 }
 
+/**
+ * Manifest form of a declared skill path: no leading `./`, no trailing slash.
+ * A directory declaration is the same string as the source-tree prefix the
+ * server matches the uploaded source files against.
+ */
+export function normalizeAppSkillManifestPath(sourcePath) {
+  return String(sourcePath || '').replace(/\\/g, '/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+}
+
+/**
+ * Every packageable file under a declared skill directory, relative to that
+ * directory, in stable order. Excludes match `readSourceFiles` so the files a
+ * dev session sends inline are exactly the ones a deploy uploads as source.
+ */
+function readAppSkillDirectoryFiles(skillDir) {
+  const entries = [];
+
+  function walk(dir, prefix) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (shouldExcludeSourceEntry(entry.name) || entry.isSymbolicLink()) {
+        continue;
+      }
+      const fullPath = join(dir, entry.name);
+      const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (entry.isFile()) {
+        entries.push({ path: relPath, absolutePath: fullPath });
+      }
+    }
+  }
+
+  walk(skillDir, '');
+  // Byte order, not locale order: the server sorts the same file set the same
+  // way before hashing it, so a dev session and a deploy agree on the hash.
+  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
 export function resolveConfiguredAppSkills(appConfig, projectDir) {
   const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
   const projectRoot = resolve(projectDir);
+  const realProjectRoot = realpathSync(projectRoot);
   const seenKeys = new Set();
 
   return configured.map((skill, index) => {
@@ -855,7 +944,49 @@ export function resolveConfiguredAppSkills(appConfig, projectDir) {
     if (!relativePath || relativePath.startsWith('../') || relativePath === '..') {
       throw usageError(`App skill path must stay inside the project: ${sourcePath}`);
     }
-    if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+    if (!existsSync(absolutePath)) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
+    if (lstatSync(absolutePath).isSymbolicLink()) {
+      throw usageError(`App skill entrypoint cannot be a symbolic link: ${sourcePath}`);
+    }
+    const realAbsolutePath = realpathSync(absolutePath);
+    const realRelativePath = relative(realProjectRoot, realAbsolutePath).replace(/\\/g, '/');
+    if (!realRelativePath || realRelativePath.startsWith('../') || realRelativePath === '..') {
+      throw usageError(`App skill path must stay inside the project after resolving links: ${sourcePath}`);
+    }
+
+    const description = typeof skill.description === 'string' ? skill.description.trim() : null;
+    const stats = statSync(absolutePath);
+    if (stats.isDirectory()) {
+      const entries = readAppSkillDirectoryFiles(absolutePath);
+      if (!entries.some((entry) => entry.path === 'SKILL.md')) {
+        throw usageError(`App skill directory must contain SKILL.md: ${sourcePath}`);
+      }
+      const bundleFiles = entries.map((entry) => ({
+        path: entry.path,
+        content: readFileSync(entry.absolutePath),
+      }));
+      const totalBytes = bundleFiles.reduce((total, entry) => total + entry.content.length, 0);
+      if (totalBytes > MAX_APP_SKILL_BUNDLE_BYTES) {
+        throw usageError(
+          `App skill "${key}" bundles ${totalBytes} bytes, above the ${MAX_APP_SKILL_BUNDLE_BYTES} byte limit.`,
+        );
+      }
+      const skillMd = bundleFiles.find((entry) => entry.path === 'SKILL.md');
+      return {
+        key,
+        path: relativePath,
+        name,
+        description,
+        skill_md: skillMd.content.toString('utf8'),
+        bundle_files: bundleFiles.map((entry) => ({
+          path: entry.path,
+          content_b64: entry.content.toString('base64'),
+        })),
+      };
+    }
+    if (!stats.isFile()) {
       throw usageError(`App skill entrypoint not found: ${sourcePath}`);
     }
 
@@ -863,7 +994,7 @@ export function resolveConfiguredAppSkills(appConfig, projectDir) {
       key,
       path: relativePath,
       name,
-      description: typeof skill.description === 'string' ? skill.description.trim() : null,
+      description,
       skill_md: readFileSync(absolutePath, 'utf8'),
     };
   });
@@ -1024,12 +1155,85 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
         config = config.replace(/'My Notis App'/, displayName);
       }
     }
+    config = removeConfigArrayProperty(config, 'screenshots');
     writeFileSync(configPath, config);
   }
 
+  resetScaffoldChangelog(projectDir, appName);
+
   return { projectDir };
 }
 
+/**
+ * Drop `property: [ ... ]` from a notis.config.ts source.
+ *
+ * The scan tracks bracket depth while skipping string literals, so entries
+ * whose text contains a bracket (alt text, selectors) cannot end the array
+ * early. When the array cannot be resolved the source is returned untouched --
+ * a stale screenshots list is a warning at verify time, a broken config is not.
+ */
+function removeConfigArrayProperty(source, property) {
+  const start = source.search(new RegExp(`^[ \\t]*${property}[ \\t]*:[ \\t]*\\[`, 'm'));
+  if (start === -1) {
+    return source;
+  }
+  let index = source.indexOf('[', start);
+  let depth = 0;
+  let quote = null;
+  for (; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (char === '\\') {
+        index += 1;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '\'' || char === '"' || char === '`') {
+      quote = char;
+      continue;
+    }
+    if (char === '[') {
+      depth += 1;
+    } else if (char === ']') {
+      depth -= 1;
+      if (depth === 0) {
+        break;
+      }
+    }
+  }
+  if (depth !== 0) {
+    return source;
+  }
+  let end = index + 1;
+  if (source[end] === ',') {
+    end += 1;
+  }
+  while (end < source.length && (source[end] === ' ' || source[end] === '\t')) {
+    end += 1;
+  }
+  if (source[end] === '\n') {
+    end += 1;
+  }
+  return source.slice(0, start) + source.slice(end);
+}
+
+/**
+ * A new project starts its own release history: the scaffold's entries describe
+ * releases of a different app.
+ */
+function resetScaffoldChangelog(projectDir, appName) {
+  const changelogPath = join(projectDir, 'CHANGELOG.md');
+  if (!existsSync(changelogPath)) {
+    return;
+  }
+  writeFileSync(
+    changelogPath,
+    `# ${appName} Changelog\n\n## [Initial Release] - ${CHANGELOG_MERGE_DATE}\n\n- First Store release.\n`,
+  );
+}
+
 function normalizeScaffoldLockfile(projectDir, pkg) {
   const lockPath = join(projectDir, 'package-lock.json');
   if (!existsSync(lockPath)) {
@@ -1126,6 +1330,9 @@ function copyScaffoldSource(sourceDir, targetDir) {
   function shouldCopy(path) {
     const name = path.split(/[\\/]/).pop();
     if (!name) return true;
+    if (SCAFFOLD_LISTING_MEDIA.test(relative(sourceDir, path).replace(/\\/g, '/'))) {
+      return false;
+    }
     return !SCAFFOLD_COPY_EXCLUDES.has(name)
       && !name.startsWith('.env')
       && !/\.(test|spec)\.[cm]?[jt]sx?$/i.test(name);
@@ -1187,7 +1394,12 @@ export function collectArtifactFiles(projectDir) {
 }
 
 function shouldExcludeSourceEntry(name) {
-  return SOURCE_COPY_EXCLUDES.has(name) || name.startsWith('.env');
+  return (
+    SOURCE_COPY_EXCLUDES.has(name)
+    || name.startsWith('.env')
+    || name.endsWith('.pyc')
+    || name.endsWith('.pyo')
+  );
 }
 
 function readSourceFiles(projectDir) {

package/src/runtime/auth-recovery.js

@@ -1,6 +1,14 @@
 import { CliError, EXIT_CODES } from './errors.js';
+import { channelFromProfile, cliCommandForChannel } from './channel.js';
 
-const CLI_NPX = 'npx --package @notis_ai/cli@latest -- notis';
+// Recovery is only useful when the printed command is the one that will run:
+// telling a beta profile to reinstall `@latest` sends it back to the build it
+// just failed on.
+function cliNpx(runtime = {}) {
+  return cliCommandForChannel(
+    runtime.channel || channelFromProfile({ api_base: runtime.apiBase }),
+  );
+}
 
 export function quoteShellArgument(value) {
   return `'${String(value).replace(/'/g, `'"'"'`)}'`;
@@ -19,8 +27,9 @@ function profileSuffix(profileName) {
  * "expired" means the profile holds a grant the browser can renew, while
  * "missing" means this profile has never been authorized at all.
  */
-export function getAuthRecovery({ profileName } = {}, { mode = 'expired' } = {}) {
-  const suffix = profileSuffix(profileName);
+export function getAuthRecovery(runtime = {}, { mode = 'expired' } = {}) {
+  const CLI_NPX = cliNpx(runtime);
+  const suffix = profileSuffix(runtime.profileName);
   const hints = [
     {
       command: `${CLI_NPX} login${suffix}`,
@@ -41,6 +50,7 @@ export function getAuthRecovery({ profileName } = {}, { mode = 'expired' } = {})
 }
 
 export function createExpiredAuthError(runtime) {
+  const CLI_NPX = cliNpx(runtime || {});
   if (runtime?.credentialKind === 'worktree') {
     return new CliError({
       code: 'auth_expired',

package/src/runtime/channel.js

@@ -0,0 +1,133 @@
+/**
+ * Which published CLI build a profile should run.
+ *
+ * The npm tag has to be chosen before the CLI starts, and the CLI only learns
+ * which Notis it talks to after it reads the profile — so a single documented
+ * install command can never be right for both environments on its own. The
+ * deployment answers the question at login (`notis_cli_channel` in the CLI
+ * protected-resource metadata), the answer is pinned on the profile, and every
+ * later run re-executes the matching build. `@notis_ai/cli@latest` therefore
+ * stays the one command worth documenting, including for beta accounts.
+ */
+
+export const RELEASE_CHANNELS = ['stable', 'beta'];
+const CHANNEL_TAGS = { stable: 'latest', beta: 'beta' };
+export const CLI_PACKAGE_NAME = '@notis_ai/cli';
+// Set on the child so a build that disagrees about its own channel — a bad
+// version string, a half-published tag — cannot bounce the process forever.
+export const CHANNEL_SWITCH_ENV = 'NOTIS_CLI_CHANNEL_SWITCHED';
+export const CHANNEL_DISABLE_ENV = 'NOTIS_CLI_AUTO_CHANNEL';
+
+export function isReleaseChannel(value) {
+  return RELEASE_CHANNELS.includes(value);
+}
+
+export function packageTagForChannel(channel) {
+  return CHANNEL_TAGS[channel] || CHANNEL_TAGS.stable;
+}
+
+export function cliCommandForChannel(channel) {
+  return `npx --package ${CLI_PACKAGE_NAME}@${packageTagForChannel(channel)} -- notis`;
+}
+
+/**
+ * The channel of the build that is currently running.
+ *
+ * The publish pipeline stamps beta releases as prereleases
+ * (`0.2.0-beta.129.1`) and production releases as plain semver (`0.2.10`), so
+ * the manifest version is the only channel marker that cannot drift from what
+ * npm actually served.
+ */
+export function channelFromVersion(version) {
+  return String(version || '').includes('-') ? 'beta' : 'stable';
+}
+
+/**
+ * The channel a profile is pinned to.
+ *
+ * `channel` is written at login from the deployment's own metadata. The
+ * `beta` flag and the endpoint host are the fallbacks that let a profile
+ * authorized by an older CLI resolve without a second login.
+ */
+export function channelFromProfile(profile = {}) {
+  if (isReleaseChannel(profile.channel)) {
+    return profile.channel;
+  }
+  if (profile.beta === true) return 'beta';
+  if (profile.beta === false) return 'stable';
+  for (const candidate of [profile.oauth_api_base, profile.api_base]) {
+    if (typeof candidate !== 'string' || !candidate) continue;
+    try {
+      const { hostname } = new URL(candidate);
+      if (hostname === 'api-beta.notis.ai') return 'beta';
+      if (hostname === 'api.notis.ai') return 'stable';
+    } catch {
+      // A malformed endpoint says nothing about the channel.
+    }
+  }
+  return null;
+}
+
+/**
+ * A profile served by `./dev.sh` runs the CLI from that worktree on purpose.
+ * Re-executing it into a published build would swap both the code under test
+ * and the credential the worktree minted.
+ */
+export function isDevManagedProfile(profile = {}) {
+  if (profile.dev_access_token || profile.dev_workspace_root) {
+    return true;
+  }
+  if (typeof profile.api_base !== 'string' || !profile.api_base) {
+    return false;
+  }
+  try {
+    const { hostname } = new URL(profile.api_base);
+    return ['localhost', '127.0.0.1', '::1', '[::1]'].includes(hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A checkout run through `node bin/notis.js` is someone testing this source
+ * tree. Only an installed copy — one that npm placed under node_modules — may
+ * hand its invocation to a different published build.
+ */
+export function isInstalledPackage(moduleDirectory) {
+  return String(moduleDirectory || '').split(/[\\/]/).includes('node_modules');
+}
+
+/**
+ * Decide whether this process should hand over to another published build.
+ *
+ * Returns the reason in every case: the caller reports it under `--verbose`
+ * and the tests assert on it, so a switch that silently does not happen is
+ * still explainable.
+ */
+export function resolveChannelSwitch({
+  runningVersion,
+  profile = {},
+  moduleDirectory = '',
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const runningChannel = channelFromVersion(runningVersion);
+  const targetChannel = channelFromProfile(profile);
+  const stay = (reason) => ({ switch: false, reason, runningChannel, targetChannel });
+
+  if (env[CHANNEL_SWITCH_ENV] === '1') return stay('already_switched');
+  if (env[CHANNEL_DISABLE_ENV] === '0') return stay('disabled');
+  if (!targetChannel) return stay('profile_channel_unknown');
+  if (targetChannel === runningChannel) return stay('channel_matches');
+  if (isDevManagedProfile(profile)) return stay('dev_managed_profile');
+  if (!isInstalledPackage(moduleDirectory)) return stay('source_checkout');
+
+  return {
+    switch: true,
+    reason: 'channel_mismatch',
+    runningChannel,
+    targetChannel,
+    command: platform === 'win32' ? 'npx.cmd' : 'npx',
+    args: ['--yes', '--package', `${CLI_PACKAGE_NAME}@${packageTagForChannel(targetChannel)}`, '--', 'notis'],
+  };
+}

package/src/runtime/delegated-context.js

@@ -0,0 +1,68 @@
+/**
+ * Detect that this CLI is running *as* a Notis agent rather than for a person.
+ *
+ * Hand-over is the one command where that distinction matters: an agent Notis
+ * is already running has no business handing the same work back to Notis, and
+ * nothing about the loop it would create is self-limiting.
+ *
+ * This is the polite half of the guard. The server refuses the same call unless
+ * it carries a purpose-scoped CLI/MCP OAuth token, which a delegated runtime
+ * never has -- that is the half that actually holds. What this adds is a clear
+ * message at the point of the mistake, instead of a permission error the agent
+ * will try to work around.
+ */
+
+import { existsSync } from 'node:fs';
+import { CliError, EXIT_CODES } from './errors.js';
+
+// The cloud computer's root. Present only inside the user's Vercel sandbox.
+const SANDBOX_ROOT = '/vercel/sandbox';
+
+export function delegatedContextReason(env = process.env, { fileExists = existsSync } = {}) {
+  if (env.NOTIS_DELEGATED_CONTEXT === '1') {
+    // Set by Notis Desktop on every coding agent it spawns. Those runs use the
+    // user's own OAuth profile, so nothing else distinguishes them.
+    return 'this process was started by Notis as a delegated coding agent';
+  }
+  if (fileExists(SANDBOX_ROOT)) {
+    return 'this process is running on the Notis cloud computer';
+  }
+  if (env.NOTIS_AGENT === '1' && env.NOTIS_JWT) {
+    return 'this process is authenticated as a Notis agent, not as you';
+  }
+  return null;
+}
+
+export function assertNotDelegated(commandLabel, env = process.env) {
+  const reason = delegatedContextReason(env);
+  if (!reason) {
+    return;
+  }
+  throw new CliError({
+    code: 'handover_from_delegated_context',
+    message:
+      `\`notis ${commandLabel}\` hands work to a Notis agent, and ${reason}. ` +
+      'An agent cannot hand its own task back to Notis.',
+    exitCode: EXIT_CODES.usage,
+    hints: [
+      { message: 'Run the hand-over from the terminal on your own machine.' },
+      { message: 'If you are the agent: just do the work here, in this workspace.' },
+    ],
+  });
+}
+
+/**
+ * Tools that hand work to a Notis agent, by canonical name.
+ *
+ * `notis handover` is not the only way to reach these: `notis tools exec` takes
+ * any tool name, and `tools exec-parallel` takes a list of them. Guarding only
+ * the friendly command would leave the escape hatch it exists to wrap.
+ */
+export const HANDOVER_TOOL_NAMES = new Set(['LOCAL_NOTIS_HAND_OVER']);
+
+export function assertToolNotDelegated(toolName, env = process.env) {
+  if (!HANDOVER_TOOL_NAMES.has(String(toolName || '').toUpperCase())) {
+    return;
+  }
+  assertNotDelegated(`tools exec ${toolName}`, env);
+}