@notis_ai/cli 0.2.7 → 0.2.8

package/src/command-specs/onboarding.js

@@ -0,0 +1,216 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { CliError, EXIT_CODES } from '../runtime/errors.js';
+import { getDesktopAuthRecovery, waitForDesktopAuth } from '../runtime/desktop-auth.js';
+import { getJwt, isJwtExpired, loadConfig } from '../runtime/profiles.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_BRIEF_PATH = join(HERE, '..', '..', 'skills', 'notis-onboarding', 'BRIEF.md');
+
+/**
+ * The brief is served rather than bundled so it tracks the deployed server. The
+ * bundled copy is a fallback for an offline or unreachable API, and the payload
+ * says which one the caller got so a stale brief is diagnosable.
+ */
+async function fetchBrief(apiBase, timeoutMs) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.min(timeoutMs || 30_000, 30_000));
+    try {
+      const response = await fetch(`${apiBase.replace(/\/$/, '')}/signup/onboarding-brief`, {
+        signal: controller.signal,
+      });
+      if (response.ok) {
+        const payload = await response.json();
+        if (payload?.markdown) {
+          return { markdown: payload.markdown, source: 'server' };
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    // fall through to the bundled copy
+  }
+
+  try {
+    return { markdown: readFileSync(BUNDLED_BRIEF_PATH, 'utf-8'), source: 'bundled' };
+  } catch {
+    return { markdown: null, source: null };
+  }
+}
+
+async function requestSignupLink(apiBase, { email, useCases }) {
+  const response = await fetch(`${apiBase.replace(/\/$/, '')}/signup/agent`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      email,
+      ...(useCases && useCases.length ? { preferred_use_cases: useCases } : {}),
+    }),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (response.status === 429) {
+    // Requesting another link invalidates the previous one, so retrying is
+    // actively harmful. Surface the cooldown and stop.
+    throw new CliError({
+      code: 'signup_throttled',
+      message: payload?.message || 'A sign-in link was just sent to this address.',
+      exitCode: EXIT_CODES.usage,
+      details: payload || {},
+      hints: [
+        {
+          command: 'Open the newest Notis email on this machine',
+          reason: 'Requesting another link makes earlier links stop working',
+        },
+      ],
+    });
+  }
+
+  if (!response.ok) {
+    throw new CliError({
+      code: 'signup_failed',
+      message: payload?.message || `Signup failed with status ${response.status}`,
+      exitCode: EXIT_CODES.backend,
+      details: payload || {},
+    });
+  }
+
+  return payload || {};
+}
+
+async function startHandler(ctx) {
+  const { runtime, options, output } = ctx;
+  const apiBase = runtime.apiBase;
+  const authenticated = Boolean(runtime.jwt) && !isJwtExpired(runtime.jwt);
+
+  // Safe to re-run: an already-authenticated machine skips straight to the brief.
+  // Agents retry commands, and a second signup would invalidate the first email.
+  if (authenticated || options.briefOnly) {
+    if (!authenticated) {
+      const recovery = getDesktopAuthRecovery(runtime, { mode: 'missing' });
+      throw new CliError({
+        code: 'auth_missing',
+        message: 'This machine is not signed in to Notis yet.',
+        exitCode: EXIT_CODES.auth,
+        hints: recovery.hints,
+      });
+    }
+    const brief = await fetchBrief(apiBase, runtime.timeoutMs);
+    return output.emitSuccess({
+      command: 'start',
+      data: { authenticated: true, brief: brief.markdown, brief_source: brief.source },
+      humanSummary: 'Notis CLI is authenticated on this machine.',
+      renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+    });
+  }
+
+  if (!options.email) {
+    // The one point in the flow that has to stop and talk to the human.
+    throw new CliError({
+      code: 'signup_email_required',
+      message: 'An email address is required to create or access a Notis account.',
+      exitCode: EXIT_CODES.usage,
+      hints: [
+        {
+          command: 'Ask the user for their email address, then rerun with --email <address>',
+          reason: 'Notis sends a sign-in link there to prove they own the address',
+        },
+      ],
+    });
+  }
+
+  const signup = await requestSignupLink(apiBase, {
+    email: options.email,
+    useCases: options.useCase,
+  });
+
+  // Commander stores the negatable `--no-wait` flag as `options.wait === false`
+  // and never sets `options.noWait` — the same footgun already fixed for
+  // `--no-open` in apps.js. Reading `noWait` made the flag a no-op, so an agent
+  // that asked not to wait blocked for the full timeout instead.
+  if (options.wait === false) {
+    return output.emitSuccess({
+      command: 'start',
+      data: { authenticated: false, next_action: 'open_email_link', ...signup },
+      humanSummary: `A sign-in link is on its way to ${options.email}.`,
+    });
+  }
+
+  const timeoutMs = Number(options.waitTimeoutMs) > 0 ? Number(options.waitTimeoutMs) : 300_000;
+  const jwt = await waitForDesktopAuth({
+    loadConfig,
+    getJwt,
+    isJwtExpired,
+    profileName: runtime.profileName,
+    timeoutMs,
+    onTick: (remaining) => {
+      if (runtime.outputMode !== 'json' && remaining % 15_000 < 2_000) {
+        output.note?.(`Waiting for Notis Desktop to sign in (${Math.round(remaining / 1000)}s left)...`);
+      }
+    },
+  });
+
+  if (!jwt) {
+    throw new CliError({
+      code: 'auth_timeout',
+      message: 'Timed out waiting for Notis Desktop to authenticate the CLI.',
+      exitCode: EXIT_CODES.auth,
+      details: { desktop_download_url: signup.desktop_download_url || null },
+      hints: [
+        {
+          command: `Install Notis Desktop: ${signup.desktop_download_url || 'https://notis.ai/channels/desktop-app'}`,
+          reason: 'The desktop app is what writes the CLI credential',
+        },
+        { command: 'notis start --brief-only', reason: 'Resume once the desktop app is signed in' },
+        { command: 'notis doctor', reason: 'Re-check config, auth, and API reachability' },
+      ],
+    });
+  }
+
+  const brief = await fetchBrief(apiBase, runtime.timeoutMs);
+  return output.emitSuccess({
+    command: 'start',
+    data: { authenticated: true, brief: brief.markdown, brief_source: brief.source },
+    humanSummary: 'Notis CLI is authenticated. Follow the onboarding brief below.',
+    renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+  });
+}
+
+export const onboardingCommandSpecs = [
+  {
+    command_path: ['start'],
+    summary: 'Create or access a Notis account and wait for the desktop app to sign the CLI in.',
+    when_to_use:
+      'Run this first on a new machine, before anything that needs auth. Safe to re-run: an already-signed-in machine just reprints the onboarding brief.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--email <email>', description: 'Email to create or sign in the Notis account with.' },
+        { flags: '--use-case <slug>', description: 'Primary use case (repeatable).', collect: true },
+        {
+          flags: '--wait-timeout-ms <n>',
+          description: 'How long to wait for the desktop sign-in (default 300000).',
+        },
+        { flags: '--no-wait', description: 'Send the link and exit without waiting.' },
+        { flags: '--brief-only', description: 'Print the onboarding brief for an already-signed-in profile.' },
+      ],
+    },
+    examples: [
+      'notis start --email you@example.com',
+      'notis start --brief-only',
+      'notis start --email you@example.com --json',
+    ],
+    output_schema:
+      'Returns {authenticated, brief, brief_source} once signed in, or {next_action, cooldown_seconds, desktop_download_url} while waiting.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis doctor', 'notis tools link'],
+    backend_call: { type: 'http', name: 'POST /signup/agent' },
+    handler: startHandler,
+  },
+];

package/src/command-specs/tools.js

@@ -453,8 +453,12 @@ async function toolsExecHandler(ctx) {
     arguments_: {
       tools: [{ tool_slug: requestedToolName, arguments: args }],
     },
-    mutating: targetMutating !== false,
-    idempotencyKey: targetMutating === false ? null : idempotencyKey,
+    // 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({
@@ -470,8 +474,8 @@ async function toolsExecHandler(ctx) {
     requestId: result.requestId,
     meta: {
       mutating: targetMutating,
-      mutation_classification: targetMutating === null ? 'unknown' : 'inferred',
-      idempotency_key: targetMutating === false ? null : idempotencyKey,
+      mutation_classification: targetMutating === null ? 'unknown' : 'name_hint_only',
+      idempotency_key: idempotencyKey,
     },
     renderHuman: () => JSON.stringify(result.payload, null, 2),
   });

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';
@@ -153,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`);
     }
 
@@ -182,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;
   }