@notis_ai/cli 0.2.6 → 0.2.8

package/src/command-specs/tools.js

@@ -17,7 +17,7 @@ import {
   validateArguments,
 } from './helpers.js';
 
-async function resolveJsonInput(value, label) {
+export async function resolveJsonInput(value, label) {
   if (!value) return undefined;
 
   if (value === '-') {
@@ -39,6 +39,159 @@ async function resolveJsonInput(value, label) {
   return parseJson(value, label);
 }
 
+const READ_ACTIONS = new Set([
+  'CHECK',
+  'DESCRIBE',
+  'DOWNLOAD',
+  'FETCH',
+  'FIND',
+  'GET',
+  'INSPECT',
+  'LIST',
+  'LOOKUP',
+  'PREVIEW',
+  'QUERY',
+  'READ',
+  'SEARCH',
+  'STATUS',
+  'VERIFY',
+]);
+const WRITE_ACTIONS = new Set([
+  'AUTHENTIFY',
+  'CANCEL',
+  'CONNECT',
+  'COPY',
+  'CREATE',
+  'DELETE',
+  'DEPLOY',
+  'DISCARD',
+  'EDIT',
+  'GRANT',
+  'INCREMENT',
+  'INSERT',
+  'LINK',
+  'MOVE',
+  'POST',
+  'PUBLISH',
+  'REFUND',
+  'REMOVE',
+  'RENAME',
+  'SAVE',
+  'SEND',
+  'SUBMIT',
+  'UPDATE',
+  'UPLOAD',
+  'UPSERT',
+]);
+
+function splitSqlStatements(query) {
+  const statements = [];
+  let current = '';
+  let quote = null;
+  let dollarTag = null;
+  for (let index = 0; index < query.length; index += 1) {
+    const char = query[index];
+    if (dollarTag) {
+      if (query.startsWith(dollarTag, index)) {
+        current += dollarTag;
+        index += dollarTag.length - 1;
+        dollarTag = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (quote) {
+      current += char;
+      if (char === quote) {
+        if (query[index + 1] === quote) {
+          current += query[index + 1];
+          index += 1;
+        } else {
+          quote = null;
+        }
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === '$') {
+      const match = query.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/);
+      if (match) {
+        dollarTag = match[0];
+        current += dollarTag;
+        index += dollarTag.length - 1;
+        continue;
+      }
+    }
+    if (char === ';') {
+      if (current.trim()) statements.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) statements.push(current.trim());
+  return statements;
+}
+
+function classifySqlMutation(query) {
+  const statements = splitSqlStatements(query);
+  if (statements.length > 1) {
+    const classifications = statements.map(classifySqlMutation);
+    if (classifications.includes(true)) return true;
+    if (classifications.every((classification) => classification === false)) return false;
+    return null;
+  }
+  const statement = statements[0] || '';
+  if (statement) {
+    const normalizedStatement = statement.toUpperCase();
+    if (/^EXPLAIN\b/.test(normalizedStatement)) {
+      const executes = /^EXPLAIN\s+(?:\([^)]*\bANALYZE\b[^)]*\)\s*|ANALYZE\s+)/.test(normalizedStatement);
+      if (!executes) return false;
+      return /\b(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement);
+    }
+    if (/^SHOW\b/.test(normalizedStatement)) return false;
+    // PostgreSQL SELECT can call side-effecting functions. Without catalog
+    // knowledge it is not provably read-only, so preserve idempotency and report
+    // an unknown classification instead of claiming mutating=false.
+    if (/^SELECT\b/.test(normalizedStatement)) return null;
+    if (/^WITH\b/.test(normalizedStatement)) {
+      return /\b(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement)
+        ? true
+        : null;
+    }
+    if (/^(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement)) {
+      return true;
+    }
+  }
+  return null;
+}
+
+export function classifyToolMutation(toolName, args = {}) {
+  const normalized = localNotisToolSlug(toolName).toUpperCase();
+  if (normalized.includes('EXECUTE_SQL') && typeof args.query === 'string') {
+    const query = args.query
+      .replace(/\/\*[\s\S]*?\*\//g, ' ')
+      .replace(/--[^\n]*/g, ' ')
+      .trim();
+    const sqlClassification = classifySqlMutation(query);
+    if (sqlClassification !== null) return sqlClassification;
+  }
+  if (/(?:^|_)(?:FIND|GET|LOOKUP|SEARCH)_OR_(?:CREATE|INSERT|SAVE|UPDATE|UPSERT)(?:_|$)/.test(normalized)) {
+    return true;
+  }
+  const tokens = normalized.split(/[^A-Z0-9]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (WRITE_ACTIONS.has(token)) return true;
+    if (READ_ACTIONS.has(token)) return false;
+  }
+  return null;
+}
+
 const LONG_RUNNING_TOOL_TIMEOUT_MS = 600000;
 const LONG_RUNNING_TOOL_NAMES = new Set([
   'LOCAL_NOTIS_GENERATE_IMAGE_OPENAI',
@@ -67,7 +220,7 @@ function guessContentType(filePath) {
   return EXTENSION_CONTENT_TYPES.get(lower.slice(dotIndex)) || 'application/octet-stream';
 }
 
-async function hashFileSha256(localPath) {
+export async function hashFileSha256(localPath) {
   const hash = createHash('sha256');
   for await (const chunk of createReadStream(localPath)) {
     hash.update(chunk);
@@ -123,7 +276,7 @@ async function parseFileBindingSpec(spec, index) {
   };
 }
 
-async function parseFileBindings(rawFileOptions) {
+export async function parseFileBindings(rawFileOptions) {
   const values = Array.isArray(rawFileOptions)
     ? rawFileOptions
     : (rawFileOptions ? [rawFileOptions] : []);
@@ -227,7 +380,12 @@ async function toolsDescribeHandler(ctx) {
 
 async function toolsExecHandler(ctx) {
   const requestedToolName = localNotisToolSlug(ctx.args.toolName);
+  let targetMutating = classifyToolMutation(requestedToolName);
   ensureLongRunningToolTimeout(ctx, requestedToolName);
+  ctx.output.emitProgress({
+    phase: 'prepare',
+    message: `Resolving ${requestedToolName}`,
+  });
   const fileBindings = await parseFileBindings(ctx.options.file);
 
   if (ctx.options.getSchema) {
@@ -243,10 +401,16 @@ async function toolsExecHandler(ctx) {
     });
   }
 
-  const rawArguments = ctx.options.arguments || '{}';
+  if (ctx.options.argumentsFile && ctx.options.arguments) {
+    throw usageError('Use either --arguments or --arguments-file, not both.');
+  }
+  const rawArguments = ctx.options.argumentsFile
+    ? `@${ctx.options.argumentsFile}`
+    : (ctx.options.arguments || '{}');
   const args = rawArguments === '-' || rawArguments.startsWith('@')
     ? await resolveJsonInput(rawArguments, 'arguments') || {}
     : parseMaybeJson(rawArguments, 'arguments') || {};
+  targetMutating = classifyToolMutation(requestedToolName, args);
 
   if (ctx.options.dryRun) {
     if (fileBindings.length) {
@@ -278,6 +442,10 @@ async function toolsExecHandler(ctx) {
   }
 
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  ctx.output.emitProgress({
+    phase: 'execute',
+    message: `Calling ${requestedToolName}`,
+  });
 
   const result = await runToolCommand({
     runtime: ctx.runtime,
@@ -285,16 +453,30 @@ async function toolsExecHandler(ctx) {
     arguments_: {
       tools: [{ tool_slug: requestedToolName, arguments: args }],
     },
+    // The server is authoritative about provider/MCP effects. A tool name that
+    // looks like a read is not proof of read-only behavior, so generic
+    // executions always carry a key and use mutation-safe transport retries.
+    // Proven reads are still executed in the read lane by hosted MCP.
     mutating: true,
     idempotencyKey,
     fileBindings,
   });
+  ctx.output.emitProgress({
+    phase: 'complete',
+    message: `Finished ${requestedToolName}`,
+    requestId: result.requestId,
+  });
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: result.payload,
     humanSummary: `Executed tool ${requestedToolName}`,
-    meta: { mutating: true, idempotency_key: idempotencyKey },
+    requestId: result.requestId,
+    meta: {
+      mutating: targetMutating,
+      mutation_classification: targetMutating === null ? 'unknown' : 'name_hint_only',
+      idempotency_key: idempotencyKey,
+    },
     renderHuman: () => JSON.stringify(result.payload, null, 2),
   });
 }
@@ -441,6 +623,7 @@ export const toolsCommandSpecs = [
       arguments: [{ token: '<tool-name>', description: 'Tool name returned by `notis tools search`.' }],
       options: [
         { flags: '--arguments <json>', description: 'JSON object, @file path, or - for stdin.' },
+        { flags: '--arguments-file <path>', description: 'Read the JSON arguments object from a file.' },
         { flags: '--file <argument-path=local-path>', description: 'Upload a local file into a file-uploadable tool argument. Repeatable.', collect: true },
         { flags: '--get-schema', description: 'Display the tool parameter schema without executing.' },
         { flags: '--dry-run', description: 'Validate arguments against the tool schema without executing.' },
@@ -452,6 +635,7 @@ export const toolsCommandSpecs = [
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --get-schema',
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments \'{"database_slug":"tasks","query":{}}\'',
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments @query.json',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments-file query.json',
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments - < query.json',
       'notis tools exec composio-dropbox-upload_file --arguments \'{"path":"/target/in/dropbox.pdf"}\' --file content=./Invoice.pdf',
     ],

package/src/runtime/app-platform.js

@@ -231,7 +231,13 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
     warnings.push('Missing Tailwind config.');
   }
 
-  if (appConfig && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)) {
+  const readsWorkspaceDatabases =
+    appConfig?.capabilities?.workspaceDatabases === 'read';
+  if (
+    appConfig
+    && !readsWorkspaceDatabases
+    && (!Array.isArray(appConfig.databases) || appConfig.databases.length === 0)
+  ) {
     warnings.push('No database references declared in notis.config.ts.');
   }
 
@@ -490,13 +496,24 @@ export async function runProjectScript({ projectDir, scriptName, env = {}, stdio
       stdio,
       env: { ...process.env, ...env },
     });
+    let capturedOutput = '';
+    for (const stream of [child.stdout, child.stderr]) {
+      stream?.on('data', (chunk) => {
+        capturedOutput += chunk.toString();
+      });
+    }
     child.on('error', rejectPromise);
     child.on('exit', (code) => {
       if (code === 0) {
         resolvePromise();
         return;
       }
-      rejectPromise(new Error(`npm run ${scriptName} failed with exit code ${code}`));
+      const detail = capturedOutput.trim();
+      rejectPromise(
+        new Error(
+          `npm run ${scriptName} failed with exit code ${code}${detail ? `:\n${detail}` : ''}`,
+        ),
+      );
     });
   });
 }
@@ -707,7 +724,14 @@ export function generateManifest(appConfig, projectDir) {
     return entry;
   });
 
-  const databases = appConfig.databases || [];
+  // Database entries may be a bare slug (structure only) or an object opting
+  // into shipping rows to installers. Normalize to the manifest's snake_case.
+  const databases = (appConfig.databases || []).map((entry) => {
+    if (typeof entry === 'string') return entry;
+    if (!entry || typeof entry !== 'object' || !entry.slug) return entry;
+    const seedDocuments = entry.seedDocuments ?? entry.seed_documents;
+    return seedDocuments === true ? { slug: entry.slug, seed_documents: true } : entry.slug;
+  });
   const categories = normalizeCategories(appConfig.categories || []);
   const metadata = { screenshots: resolveListingScreenshots(projectDir, appConfig) };
   const appSlug = safeKebab(appConfig.name);
@@ -786,12 +810,29 @@ export function generateManifest(appConfig, projectDir) {
       css: 'bundle/app.css',
     },
     databases,
+    capabilities: normalizeAppCapabilities(appConfig.capabilities),
     tools: appConfig.tools || [],
     skills,
     onboarding: appConfig.onboarding || null,
   };
 }
 
+/**
+ * Keeps only capabilities the platform actually understands, at the exact
+ * values it accepts. An unknown key or value is dropped rather than passed
+ * through, so a typo can never reach the server as a permission grant.
+ */
+export function normalizeAppCapabilities(capabilities) {
+  if (!capabilities || typeof capabilities !== 'object') {
+    return {};
+  }
+  const normalized = {};
+  if (capabilities.workspaceDatabases === 'read') {
+    normalized.workspaceDatabases = 'read';
+  }
+  return normalized;
+}
+
 export function resolveConfiguredAppSkills(appConfig, projectDir) {
   const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
   const projectRoot = resolve(projectDir);
@@ -831,13 +872,14 @@ export function resolveConfiguredAppSkills(appConfig, projectDir) {
 /**
  * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
  */
-export async function buildArtifact(projectDir) {
+export async function buildArtifact(projectDir, { stdio = 'inherit' } = {}) {
   await prepareArtifactBuild(projectDir);
 
   // Run Vite build
   await runProjectScript({
     projectDir,
     scriptName: 'build',
+    stdio,
   });
 
   // Verify the canonical `.notis/output/bundle` packaging contract.
@@ -948,8 +990,13 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
   if (existsSync(pkgPath)) {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
     pkg.name = appName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+    // A scaffold creates a new app identity, even when its source comes from a
+    // versioned Store example. New apps must therefore start their own release
+    // history instead of inheriting the example app's registry version.
+    pkg.notisAppVersion = '0.1.0';
     ensureScaffoldLocalSdk(projectDir, pkg);
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    normalizeScaffoldLockfile(projectDir, pkg);
   }
 
   // Update notis.config.ts with the app name
@@ -983,6 +1030,20 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
   return { projectDir };
 }
 
+function normalizeScaffoldLockfile(projectDir, pkg) {
+  const lockPath = join(projectDir, 'package-lock.json');
+  if (!existsSync(lockPath)) {
+    return;
+  }
+
+  const lockfile = JSON.parse(readFileSync(lockPath, 'utf-8'));
+  lockfile.name = pkg.name;
+  if (lockfile.packages?.['']) {
+    lockfile.packages[''].name = pkg.name;
+  }
+  writeFileSync(lockPath, JSON.stringify(lockfile, null, 2) + '\n');
+}
+
 function ensureScaffoldLocalSdk(projectDir, pkg) {
   let shouldInstallLocalSdk = false;
   for (const dependencyGroup of ['dependencies', 'devDependencies']) {

package/src/runtime/desktop-auth.js

@@ -24,7 +24,15 @@ function defaultDesktopAppName(apiBase) {
   }
 }
 
-export function getDesktopAuthRecovery(runtime) {
+/**
+ * Recovery hints for an unusable desktop-managed credential.
+ *
+ * `mode` distinguishes the two cases an agent has to act on differently:
+ * "expired" means a session existed and the desktop app can renew it, while
+ * "missing" means this machine was never signed in — telling that caller to
+ * renew something is misleading.
+ */
+export function getDesktopAuthRecovery(runtime, { mode = 'expired' } = {}) {
   const desktopRunning = isPidRunning(runtime.desktopPid);
   const appName = runtime.desktopAppName || defaultDesktopAppName(runtime.apiBase);
   let command = 'Start the Notis desktop app';
@@ -32,22 +40,63 @@ export function getDesktopAuthRecovery(runtime) {
     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',
-      },
-    ],
-  };
+  let reason;
+  if (mode === 'missing') {
+    reason = desktopRunning
+      ? `Sign in to ${appName} to authenticate the CLI on this machine, then retry`
+      : `Install and sign in to ${appName} to authenticate the CLI on this machine, then retry`;
+  } else {
+    reason = desktopRunning
+      ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
+      : `Start ${appName} to renew expired CLI authentication, then retry`;
+  }
+
+  const hints = [{ command, reason }];
+  if (mode === 'missing') {
+    // Leads the list: a machine that was never signed in may not even have an
+    // account yet, and `notis start` covers both cases.
+    hints.unshift({
+      command: 'notis start --email <address>',
+      reason: 'Create or access a Notis account and sign this machine in',
+    });
+  }
+  hints.push({
+    command: 'notis doctor',
+    reason: 'Retry the auth and API checks after the desktop app is ready',
+  });
+
+  return { desktopRunning, appName, hints };
+}
+
+/**
+ * Block until the desktop app writes an unexpired JWT into the CLI profile.
+ *
+ * Polls the local config file only — never the server. The desktop app is what
+ * mints the credential, and `transport.js` re-reads the profile before every
+ * request, so this loop exists purely so the caller's process can wait rather
+ * than fail and make the user re-run the command.
+ */
+export async function waitForDesktopAuth({
+  loadConfig,
+  getJwt,
+  isJwtExpired,
+  profileName = 'default',
+  timeoutMs = 300_000,
+  intervalMs = 2_000,
+  onTick,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const jwt = getJwt(loadConfig(), profileName);
+    if (jwt && !isJwtExpired(jwt)) {
+      return jwt;
+    }
+    if (Date.now() >= deadline) {
+      return null;
+    }
+    if (onTick) onTick(Math.max(0, deadline - Date.now()));
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
 }
 
 export function createExpiredAuthError(runtime) {

package/src/runtime/errors.js

@@ -6,6 +6,7 @@ export const EXIT_CODES = {
   conflict: 5,
   backend: 6,
   unexpected: 7,
+  payment: 8,
 };
 
 export class CliError extends Error {

package/src/runtime/output.js

@@ -22,6 +22,13 @@ function formatTable(rows, columns) {
   return [header, divider, ...body].join('\n');
 }
 
+function formatHint(hint) {
+  if (typeof hint?.message === 'string' && hint.message) {
+    return `  ${hint.message}`;
+  }
+  return `  ${hint?.command || ''}  ${hint?.reason || ''}`.trimEnd();
+}
+
 function yamlScalar(value) {
   if (value === null || value === undefined) {
     return 'null';
@@ -94,6 +101,14 @@ export class OutputManager {
     process.stderr.write(`${message}\n`);
   }
 
+  emitProgress({ phase, message, requestId = null }) {
+    if (this.runtime.quiet) {
+      return;
+    }
+    const suffix = requestId ? ` (${requestId})` : '';
+    process.stderr.write(`[${phase}] ${message}${suffix}\n`);
+  }
+
   emitSuccess({
     ok = true,
     command,
@@ -116,7 +131,10 @@ export class OutputManager {
       meta: {
         profile: this.runtime.profileName,
         api_base: this.runtime.apiBase,
-        mutating: Boolean(meta.mutating),
+        mutating:
+          meta.mutating === true
+            ? true
+            : (meta.mutating === false ? false : null),
         ...meta,
       },
     };
@@ -142,7 +160,7 @@ export class OutputManager {
     }
 
     if (hints.length) {
-      const lines = hints.map((hint) => `  ${hint.command}  ${hint.reason}`);
+      const lines = hints.map(formatHint);
       process.stdout.write(`\nNext:\n${lines.join('\n')}\n`);
     }
 
@@ -171,7 +189,7 @@ export class OutputManager {
 
     process.stderr.write(`Error: ${error.message}\n`);
     for (const hint of error.hints || []) {
-      process.stderr.write(`  ${hint.command}  ${hint.reason}\n`);
+      process.stderr.write(`${formatHint(hint)}\n`);
     }
     return error.exitCode || EXIT_CODES.unexpected;
   }