@notis_ai/cli 0.2.7 → 0.2.9

package/src/command-specs/auth.js

@@ -0,0 +1,107 @@
+import { loginWithOAuth, logoutOAuth } from '../runtime/oauth.js';
+
+async function loginHandler(ctx) {
+  const result = await loginWithOAuth(ctx.runtime, ctx.options, ctx.output);
+  if (result.desktopFastPath) {
+    return ctx.output.emitSuccess({
+      command: 'login',
+      data: {
+        authenticated: true,
+        credential_source: result.credentialSource || 'desktop',
+      },
+      humanSummary: 'Notis Desktop already provides a valid CLI credential.',
+    });
+  }
+  if (result.agentAuthorization) {
+    return ctx.output.emitSuccess({
+      command: 'login',
+      data: result.agentAuthorization,
+      humanSummary: 'Open the authorization URL in a browser to continue.',
+    });
+  }
+  return ctx.output.emitSuccess({
+    command: 'login',
+    data: {
+      authenticated: true,
+      credential_source: 'oauth',
+      profile: ctx.runtime.profileName,
+      user_id: result.profile.oauth_user_id,
+      scopes: result.profile.oauth_scopes,
+      access_expires_at: result.profile.oauth_access_expires_at,
+      refresh_expires_at: result.profile.oauth_refresh_expires_at,
+    },
+    humanSummary: `Notis CLI is authorized for profile "${ctx.runtime.profileName}".`,
+  });
+}
+
+async function logoutHandler(ctx) {
+  const result = await logoutOAuth(ctx.runtime, {
+    allProfiles: Boolean(ctx.options.allProfiles),
+  });
+  return ctx.output.emitSuccess({
+    command: 'logout',
+    data: {
+      oauth_connected: false,
+      cleared_profiles: result.profiles,
+    },
+    humanSummary: ctx.options.allProfiles
+      ? 'OAuth credentials were removed from all CLI profiles.'
+      : `OAuth credentials were removed from profile "${ctx.runtime.profileName}".`,
+  });
+}
+
+export const authCommandSpecs = [
+  {
+    command_path: ['login'],
+    summary: 'Authorize the Notis CLI in a browser with scoped OAuth access.',
+    when_to_use:
+      'Use this on a machine where Notis Desktop is unavailable, signed out, or should not own CLI authentication.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--no-browser', description: 'Print the authorization URL without opening a browser.' },
+        { flags: '--print-url', description: 'Print the authorization URL even when opening a browser.' },
+        { flags: '--paste-code', description: 'Use the copy-paste callback for SSH and headless machines.' },
+        { flags: '--force', description: 'Create an independent OAuth grant even when Desktop is signed in.' },
+        { flags: '--timeout-seconds <n>', description: 'How long to wait for authorization (default 300).' },
+        { flags: '--scope <scope>', description: 'OAuth permission to request (repeatable).', collect: true },
+        { flags: '--code <code>', description: 'Redeem the code shown in the browser after a non-interactive login.' },
+      ],
+    },
+    examples: [
+      'notis login',
+      'notis login --no-browser --print-url',
+      'notis login --paste-code',
+      'notis login --code 4f3c2b1a',
+      'notis login --force',
+    ],
+    output_schema:
+      'Returns credential_source, profile, user_id, scopes, and credential expiries; agent mode returns authorize_url and expires_in.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis logout', 'notis doctor', 'notis whoami'],
+    backend_call: { type: 'oauth', name: 'authorization_code+pkce' },
+    handler: loginHandler,
+  },
+  {
+    command_path: ['logout'],
+    summary: 'Revoke and remove the scoped OAuth credential for the active CLI profile.',
+    when_to_use:
+      'Use this to disconnect the command line without signing Notis Desktop out.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--all-profiles', description: 'Remove OAuth credentials from every CLI profile.' },
+      ],
+    },
+    examples: ['notis logout', 'notis logout --all-profiles'],
+    output_schema: 'Returns oauth_connected=false and the profiles whose OAuth credentials were removed.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis login', 'notis doctor'],
+    backend_call: { type: 'oauth', name: 'revocation' },
+    handler: logoutHandler,
+  },
+];

package/src/command-specs/index.js

@@ -1,8 +1,10 @@
 import { appsCommandSpecs } from './apps.js';
 import { toolsCommandSpecs } from './tools.js';
 import { metaCommandSpecs } from './meta.js';
+import { onboardingCommandSpecs } from './onboarding.js';
 import { diagnosticCommandSpecs } from './diagnostics.js';
 import { smokeCommandSpecs } from './smoke.js';
+import { authCommandSpecs } from './auth.js';
 
 export const GROUP_SUMMARIES = {
   apps: 'Develop, deploy, and submit Notis Apps.',
@@ -12,6 +14,8 @@ export const GROUP_SUMMARIES = {
 };
 
 export const COMMAND_SPECS = [
+  ...authCommandSpecs,
+  ...onboardingCommandSpecs,
   ...appsCommandSpecs,
   ...toolsCommandSpecs,
   ...diagnosticCommandSpecs,

package/src/command-specs/meta.js

@@ -1,19 +1,52 @@
 import { COMPOSIO_SEARCH_TOOLS, healthCheck, probeAuth } from './helpers.js';
 import { findCommandSpec, formatDescribe } from '../runtime/help.js';
-import { createExpiredAuthError } from '../runtime/desktop-auth.js';
-import { isJwtExpired } from '../runtime/profiles.js';
+import { createExpiredAuthError, getDesktopAuthRecovery } from '../runtime/desktop-auth.js';
+import {
+  credentialIsExpired,
+  getJwtCanonicalUserId,
+  getProfile,
+  loadConfig,
+} from '../runtime/profiles.js';
+import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
+
+export const DOCTOR_TOOL_ROUNDTRIP_TIMEOUT_MS = 90_000;
+
+export function doctorToolRoundtripRuntime(runtime) {
+  return {
+    ...runtime,
+    timeoutMs: Math.max(runtime.timeoutMs || 0, DOCTOR_TOOL_ROUNDTRIP_TIMEOUT_MS),
+  };
+}
 
 async function doctorHandler(ctx) {
   const checks = {
     config: 'ok',
     auth: 'missing',
+    identity: 'ok',
     health: 'unknown',
     tool_roundtrip: 'unknown',
   };
 
+  if (ctx.runtime.credentialKind === 'oauth') {
+    try {
+      await ensureFreshOAuthCredential(ctx.runtime);
+    } catch {
+      // Doctor still reports the remaining health and recovery checks when a
+      // refresh endpoint is unavailable or rejects the stored credential.
+    }
+  }
+  let profile = getProfile(loadConfig(ctx.runtime.worktreeRuntime), ctx.runtime.profileName);
   checks.auth = ctx.runtime.jwt
-    ? (isJwtExpired(ctx.runtime.jwt) ? 'expired' : 'configured')
+    ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
     : 'missing';
+  const desktopUserId = getJwtCanonicalUserId(profile.jwt);
+  if (
+    desktopUserId
+    && profile.oauth_user_id
+    && desktopUserId !== profile.oauth_user_id
+  ) {
+    checks.identity = 'error';
+  }
 
   try {
     await healthCheck(ctx.runtime);
@@ -24,8 +57,15 @@ async function doctorHandler(ctx) {
 
   if (ctx.runtime.jwt) {
     try {
-      const payload = await probeAuth(ctx.runtime);
+      // Tool discovery may have to query several connected MCP servers on a
+      // cold local backend. A diagnostic must not report a false failure just
+      // because that legitimate roundtrip exceeds the general 30s default.
+      const payload = await probeAuth(doctorToolRoundtripRuntime(ctx.runtime));
       checks.tool_roundtrip = Array.isArray(payload.toolkit_connection_statuses) ? 'ok' : 'error';
+      profile = getProfile(loadConfig(ctx.runtime.worktreeRuntime), ctx.runtime.profileName);
+      checks.auth = ctx.runtime.jwt
+        ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
+        : 'missing';
     } catch {
       checks.tool_roundtrip = 'error';
     }
@@ -33,7 +73,7 @@ async function doctorHandler(ctx) {
 
   const hints = [];
   if (checks.auth === 'missing') {
-    hints.push({ command: 'Open the Notis desktop app and sign in', reason: 'Configure CLI credentials' });
+    hints.push(...getDesktopAuthRecovery(ctx.runtime, { mode: 'missing' }).hints);
   } else if (checks.auth === 'expired') {
     hints.push(...createExpiredAuthError(ctx.runtime).hints);
   }
@@ -43,12 +83,27 @@ async function doctorHandler(ctx) {
   if (checks.tool_roundtrip === 'error') {
     hints.push({ command: 'notis whoami', reason: 'Verify your account and permissions' });
   }
+  if (checks.identity === 'error') {
+    hints.push({
+      command: 'notis logout',
+      reason: 'Desktop and OAuth credentials identify different accounts; remove the independent OAuth grant or sign Desktop back into the same account',
+    });
+  }
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
       profile: ctx.runtime.profileName,
       api_base: ctx.runtime.apiBase,
+      credential_source: ctx.runtime.credentialKind || null,
+      ...(ctx.runtime.credentialKind === 'oauth'
+        ? {
+            oauth_client_id: profile.oauth_client_id || null,
+            oauth_scopes: profile.oauth_scopes || [],
+            oauth_access_expires_at: profile.oauth_access_expires_at || null,
+            oauth_refresh_expires_at: profile.oauth_refresh_expires_at || null,
+          }
+        : {}),
       checks,
     },
     humanSummary: `Doctor checks completed for profile ${ctx.runtime.profileName}`,
@@ -72,16 +127,23 @@ function decodeJwtUserId(jwt) {
   }
 }
 
+export function activeRuntimeUserId(runtime) {
+  return runtime.credentialKind === 'oauth'
+    ? runtime.oauthUserId
+    : decodeJwtUserId(runtime.jwt);
+}
+
 async function whoamiHandler(ctx) {
   const payload = await probeAuth(ctx.runtime);
   const toolkits = payload.toolkit_connection_statuses || [];
-  const userId = decodeJwtUserId(ctx.runtime.jwt);
+  const userId = activeRuntimeUserId(ctx.runtime);
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
       profile: ctx.runtime.profileName,
       api_base: ctx.runtime.apiBase,
+      credential_source: ctx.runtime.credentialKind || null,
       user_id: userId,
       toolkit_count: toolkits.length,
       toolkits: toolkits.map((t) => t.toolkit),

package/src/command-specs/onboarding.js

@@ -0,0 +1,304 @@
+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 {
+  credentialIsExpired,
+  getProfile,
+  loadConfig,
+} from '../runtime/profiles.js';
+import { ensureFreshOAuthCredential, loginWithOAuth } from '../runtime/oauth.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;
+  if (runtime.credentialKind === 'oauth') {
+    try {
+      await ensureFreshOAuthCredential(runtime);
+    } catch {
+      // A failed refresh is equivalent to no usable session here. Interactive
+      // starts may still authorize again; brief-only and agent runs surface
+      // the normal authentication recovery below.
+    }
+  }
+  let authenticated = Boolean(runtime.jwt)
+    && !credentialIsExpired(
+      runtime,
+      getProfile(loadConfig(runtime.worktreeRuntime), runtime.profileName),
+    );
+
+  // 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
+    && !runtime.agentMode
+    && !runtime.nonInteractive
+    && options.wait !== false
+  ) {
+    let authorization;
+    let authorizationError;
+    try {
+      authorization = await loginWithOAuth(runtime, { browser: true }, output);
+    } catch (error) {
+      // Keep the original OAuth failure while checking whether another process
+      // completed authentication before this attempt failed.
+      authorizationError = error;
+      authorization = null;
+    }
+    if (authorization?.agentAuthorization) {
+      return output.emitSuccess({
+        command: 'start',
+        data: { authenticated: false, ...authorization.agentAuthorization },
+        humanSummary: 'Open the authorization URL to finish signing in.',
+        renderHuman: () => `Authorize Notis CLI: ${authorization.agentAuthorization.authorize_url}`,
+      });
+    }
+    // A failed authorization leaves the stale credential that got us here in
+    // place, so re-apply the same expiry test used above rather than reporting
+    // a machine as signed in on the strength of a dead token.
+    authenticated = Boolean(runtime.jwt)
+      && !credentialIsExpired(runtime, getProfile(loadConfig(runtime.worktreeRuntime), runtime.profileName));
+    if (authenticated) {
+      const brief = await fetchBrief(apiBase, runtime.timeoutMs);
+      return output.emitSuccess({
+        command: 'start',
+        data: {
+          authenticated: true,
+          credential_source: runtime.credentialKind,
+          brief: brief.markdown,
+          brief_source: brief.source,
+        },
+        humanSummary: 'Notis CLI is authenticated. Follow the onboarding brief below.',
+        renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+      });
+    }
+    if (authorizationError) {
+      throw authorizationError;
+    }
+  }
+
+  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: (config, profileName) => {
+      const profile = getProfile(config, profileName);
+      if (
+        profile.jwt
+        && !credentialIsExpired(
+          { credentialKind: 'desktop', jwt: profile.jwt },
+          profile,
+        )
+      ) {
+        return profile.jwt;
+      }
+      if (
+        profile.oauth_access_token
+        && !credentialIsExpired(
+          { credentialKind: 'oauth', jwt: profile.oauth_access_token },
+          profile,
+        )
+      ) {
+        return profile.oauth_access_token;
+      }
+      return undefined;
+    },
+    isJwtExpired: () => false,
+    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 login', reason: 'Authorize this machine directly in a browser' },
+        { command: 'notis start --brief-only', reason: 'Resume once authentication is complete' },
+        { 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 authorize the CLI.',
+    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-dev-server.js

@@ -288,12 +288,13 @@ function renderHarnessHtml({ state, manifest, appConfig, route, harnessOptions,
 /**
  * Start the dev server for one or more apps.
  *
- * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string}>, port: number, watch?: boolean, harness?: { mode?: string, apiBase?: string, jwt?: string }, log?: (m: string) => void, logError?: (m: string) => void}} options
+ * @param {{apps: Array<{slug: string, projectDir: string, appId?: string, targetAppId?: string, userId?: string}>, port: number, watch?: boolean, sessionsFilePath?: string, harness?: { mode?: string, apiBase?: string, jwt?: string }, log?: (m: string) => void, logError?: (m: string) => void}} options
  */
 export async function startAppDevServer({
   apps,
   port,
   watch = true,
+  sessionsFilePath,
   harness = {},
   log = (msg) => process.stdout.write(`${msg}\n`),
   logError = (msg) => process.stderr.write(`${msg}\n`),
@@ -466,7 +467,7 @@ export async function startAppDevServer({
                 devSlug: state.slug,
                 targetAppId: appId,
                 lastHeartbeatAt: now,
-              });
+              }, sessionsFilePath);
               const response = {
                 ok: true,
                 app_id: appId,