@notis_ai/cli 0.2.9 → 0.2.11

package/src/command-specs/helpers.js

@@ -56,12 +56,18 @@ export async function runToolCommand({
   mutating = false,
   idempotencyKey,
   fileBindings = [],
+  sendIdempotencyKeyWhenReading = false,
 }) {
+  // The server owns effect classification and requires a key whenever *its*
+  // metadata says write or unknown — a client-side `mutating: false` hint does
+  // not exempt the call. Callers that knowingly dispatch through an
+  // unknown-classified wrapper (e.g. COMPOSIO_MULTI_EXECUTE_TOOL) opt in so the
+  // request carries a key instead of being rejected as idempotency_key_required.
   const result = await callTool({
     runtime: { ...runtime, mutating },
     toolName,
     arguments_,
-    idempotencyKey: mutating ? idempotencyKey : null,
+    idempotencyKey: mutating || sendIdempotencyKeyWhenReading ? idempotencyKey : null,
     fileBindings,
   });
   return result;

package/src/command-specs/index.js

@@ -5,16 +5,19 @@ import { onboardingCommandSpecs } from './onboarding.js';
 import { diagnosticCommandSpecs } from './diagnostics.js';
 import { smokeCommandSpecs } from './smoke.js';
 import { authCommandSpecs } from './auth.js';
+import { profileCommandSpecs } from './profile.js';
 
 export const GROUP_SUMMARIES = {
   apps: 'Develop, deploy, and submit Notis Apps.',
   tools: 'Discover and execute generic tools exposed through Notis.',
+  profile: 'Switch between signed-in accounts and their API endpoints.',
   debug: 'Inspect effective runtime context, worker identity, and trace costs.',
   smoke: 'Run deterministic connected-service smoke tests with guaranteed cleanup.',
 };
 
 export const COMMAND_SPECS = [
   ...authCommandSpecs,
+  ...profileCommandSpecs,
   ...onboardingCommandSpecs,
   ...appsCommandSpecs,
   ...toolsCommandSpecs,

package/src/command-specs/meta.js

@@ -1,9 +1,8 @@
 import { COMPOSIO_SEARCH_TOOLS, healthCheck, probeAuth } from './helpers.js';
 import { findCommandSpec, formatDescribe } from '../runtime/help.js';
-import { createExpiredAuthError, getDesktopAuthRecovery } from '../runtime/desktop-auth.js';
+import { createExpiredAuthError, getAuthRecovery } from '../runtime/auth-recovery.js';
 import {
   credentialIsExpired,
-  getJwtCanonicalUserId,
   getProfile,
   loadConfig,
 } from '../runtime/profiles.js';
@@ -22,7 +21,7 @@ async function doctorHandler(ctx) {
   const checks = {
     config: 'ok',
     auth: 'missing',
-    identity: 'ok',
+    routing: 'ok',
     health: 'unknown',
     tool_roundtrip: 'unknown',
   };
@@ -35,17 +34,23 @@ async function doctorHandler(ctx) {
       // refresh endpoint is unavailable or rejects the stored credential.
     }
   }
-  let profile = getProfile(loadConfig(ctx.runtime.worktreeRuntime), ctx.runtime.profileName);
+  let profile = getProfile(loadConfig(), ctx.runtime.profileName);
   checks.auth = ctx.runtime.jwt
     ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
     : 'missing';
-  const desktopUserId = getJwtCanonicalUserId(profile.jwt);
+  // A worktree whose ./dev.sh has stopped leaves commands with no local
+  // backend to reach. Say so here rather than letting every later command fail
+  // as an opaque network error.
   if (
-    desktopUserId
-    && profile.oauth_user_id
-    && desktopUserId !== profile.oauth_user_id
+    ctx.runtime.worktreeRuntimeUnavailable
+    && ctx.runtime.profileSource !== 'explicit'
   ) {
-    checks.identity = 'error';
+    checks.routing = 'dev_runtime_unavailable';
+  } else if (
+    ctx.runtime.detachedWorktreeRuntime
+    || (ctx.runtime.worktreeRuntimeUnavailable && ctx.runtime.profileSource === 'explicit')
+  ) {
+    checks.routing = 'detached';
   }
 
   try {
@@ -62,7 +67,7 @@ async function doctorHandler(ctx) {
       // 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);
+      profile = getProfile(loadConfig(), ctx.runtime.profileName);
       checks.auth = ctx.runtime.jwt
         ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
         : 'missing';
@@ -73,27 +78,31 @@ async function doctorHandler(ctx) {
 
   const hints = [];
   if (checks.auth === 'missing') {
-    hints.push(...getDesktopAuthRecovery(ctx.runtime, { mode: 'missing' }).hints);
+    hints.push(...getAuthRecovery(ctx.runtime, { mode: 'missing' }).hints);
   } else if (checks.auth === 'expired') {
     hints.push(...createExpiredAuthError(ctx.runtime).hints);
   }
+  if (checks.routing === 'dev_runtime_unavailable') {
+    hints.push(...ctx.runtime.worktreeRuntimeUnavailable.hints);
+  } else if (checks.routing === 'detached') {
+    hints.push({
+      message: ctx.runtime.detachedWorktreeRuntime?.profile
+        ? `This worktree's ./dev.sh profile is "${ctx.runtime.detachedWorktreeRuntime.profile}"; profile "${ctx.runtime.profileName}" bypasses it.`
+        : `Explicit profile "${ctx.runtime.profileName}" bypasses this stopped worktree runtime.`,
+    });
+  }
   if (checks.health === 'error' && checks.auth !== 'expired') {
-    hints.push({ command: 'Open the Notis desktop app and sign in again', reason: 'Refresh local CLI configuration' });
+    hints.push({ command: 'notis profile show', reason: 'Check which API endpoint this profile targets' });
   }
   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,
+      profile_source: ctx.runtime.profileSource,
       api_base: ctx.runtime.apiBase,
       credential_source: ctx.runtime.credentialKind || null,
       ...(ctx.runtime.credentialKind === 'oauth'
@@ -142,6 +151,7 @@ async function whoamiHandler(ctx) {
     command: ctx.spec.command_path.join(' '),
     data: {
       profile: ctx.runtime.profileName,
+      profile_source: ctx.runtime.profileSource,
       api_base: ctx.runtime.apiBase,
       credential_source: ctx.runtime.credentialKind || null,
       user_id: userId,
@@ -159,8 +169,8 @@ async function whoamiHandler(ctx) {
         `Version:   ${ctx.runtime.cliVersion}`,
       ].join('\n'),
     hints: [
+      { command: 'notis profile list', reason: 'See the other accounts this machine can switch to' },
       { command: 'notis tools toolkits', reason: 'List available toolkit namespaces and connection statuses' },
-      { command: 'notis doctor', reason: 'Run a full health check' },
     ],
   });
 }

package/src/command-specs/onboarding.js

@@ -3,17 +3,51 @@ 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 { getAuthRecovery } from '../runtime/auth-recovery.js';
 import {
   credentialIsExpired,
   getProfile,
   loadConfig,
 } from '../runtime/profiles.js';
 import { ensureFreshOAuthCredential, loginWithOAuth } from '../runtime/oauth.js';
+import { runToolCommand } from './helpers.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const BUNDLED_BRIEF_PATH = join(HERE, '..', '..', 'skills', 'notis-onboarding', 'BRIEF.md');
 
+/**
+ * Ask the account whether it has already been onboarded.
+ *
+ * The brief itself is served unauthenticated and is identical for everyone, so
+ * it can never answer this. Without the check `start` hands a year-old account
+ * the new-user script, and a compliant agent re-asks the user their own name
+ * and calls COMPLETE_TUTORIAL on someone who converted long ago.
+ *
+ * A failure here is not fatal: an unreachable tool bridge should not block
+ * sign-in. It resolves to null and the caller degrades to serving the brief,
+ * which is the previous behaviour.
+ */
+async function fetchOnboardingState(runtime) {
+  try {
+    const { payload } = await runToolCommand({
+      runtime,
+      toolName: 'LOCAL_NOTIS_GET_USER_SETTINGS',
+      arguments_: {},
+    });
+    const data = payload?.data ?? payload?.result ?? payload;
+    if (data && typeof data.onboarding_complete === 'boolean') {
+      return {
+        onboardingComplete: data.onboarding_complete,
+        settings: data.settings || {},
+        missingSettings: Array.isArray(data.missing_settings) ? data.missing_settings : [],
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 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
@@ -47,258 +81,146 @@ async function fetchBrief(apiBase, timeoutMs) {
   }
 }
 
-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);
+function isAuthenticated(runtime) {
+  return Boolean(runtime.jwt)
+    && !credentialIsExpired(runtime, getProfile(loadConfig(), runtime.profileName));
+}
 
-  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 || {},
+/**
+ * What an authenticated `start` reports.
+ *
+ * A returning user does not need an onboarding script — they need orientation:
+ * which account, which endpoint, and confirmation that nothing is expected of
+ * them. Only an account that has genuinely not finished onboarding gets the
+ * brief, so `brief: null` is a positive signal to the agent, not a failure.
+ */
+async function authenticatedResult(ctx) {
+  const state = await fetchOnboardingState(ctx.runtime);
+  const onboardingComplete = state?.onboardingComplete === true;
+  const base = {
+    authenticated: true,
+    profile: ctx.runtime.profileName,
+    api_base: ctx.runtime.apiBase,
+    credential_source: ctx.runtime.credentialKind,
+    onboarding_complete: onboardingComplete,
+    ...(state ? { known_settings: state.settings, missing_settings: state.missingSettings } : {}),
+  };
+
+  if (onboardingComplete) {
+    const name = state?.settings?.full_name;
+    return ctx.output.emitSuccess({
+      command: 'start',
+      data: { ...base, brief: null, brief_source: null },
+      humanSummary:
+        `Profile "${ctx.runtime.profileName}" is signed in and this account is already set up.`,
+      renderHuman: () =>
+        [
+          `Signed in${name ? ` as ${name}` : ''} on profile "${ctx.runtime.profileName}".`,
+          `API: ${ctx.runtime.apiBase}`,
+          '',
+          'This account has already completed onboarding. Do not run an onboarding',
+          'flow and do not call LOCAL_NOTIS_COMPLETE_TUTORIAL.',
+        ].join('\n'),
       hints: [
-        {
-          command: 'Open the newest Notis email on this machine',
-          reason: 'Requesting another link makes earlier links stop working',
-        },
+        { command: 'notis whoami', reason: 'Show the account and its connected toolkits' },
+        { command: 'notis tools search "<what you need>"', reason: 'Find a tool and get on with the task' },
       ],
     });
   }
 
-  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 || {};
+  const brief = await fetchBrief(ctx.runtime.apiBase, ctx.runtime.timeoutMs);
+  return ctx.output.emitSuccess({
+    command: 'start',
+    data: { ...base, brief: brief.markdown, brief_source: brief.source },
+    humanSummary: `Notis CLI is authenticated for profile "${ctx.runtime.profileName}". Onboarding is not complete.`,
+    renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+  });
 }
 
 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.
+      // starts may still authorize again; brief-only 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;
-    }
+  // Safe to re-run: an already-authorized profile skips straight to the brief.
+  if (isAuthenticated(runtime)) {
+    return authenticatedResult(ctx);
   }
 
-  if (!options.email) {
-    // The one point in the flow that has to stop and talk to the human.
+  if (options.briefOnly) {
     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',
-        },
-      ],
+      code: 'auth_missing',
+      message: `Profile "${runtime.profileName}" is not signed in to Notis yet.`,
+      exitCode: EXIT_CODES.auth,
+      hints: getAuthRecovery(runtime, { mode: 'missing' }).hints,
     });
   }
 
-  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) {
+  // Browser authorization is the whole signup path: it creates the account when
+  // the address is new and authorizes this machine either way. There is nothing
+  // for the CLI to collect up front, and nothing to wait on afterwards.
+  const authorization = await loginWithOAuth(runtime, { browser: true }, output);
+  if (authorization?.agentAuthorization) {
     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}.`,
+      data: {
+        authenticated: false,
+        profile: runtime.profileName,
+        ...authorization.agentAuthorization,
+      },
+      humanSummary: 'Open the authorization URL to create or access the Notis account.',
+      renderHuman: () => `Authorize Notis CLI: ${authorization.agentAuthorization.authorize_url}`,
     });
   }
 
-  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) {
+  // A failed authorization leaves whatever stale credential got us here in
+  // place, so re-apply the same expiry test rather than reporting a machine as
+  // signed in on the strength of a dead token.
+  if (!isAuthenticated(runtime)) {
     throw new CliError({
-      code: 'auth_timeout',
-      message: 'Timed out waiting for Notis Desktop to authenticate the CLI.',
+      code: 'auth_missing',
+      message: `Authorization did not complete for profile "${runtime.profileName}".`,
       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' },
-      ],
+      hints: getAuthRecovery(runtime, { mode: 'missing' }).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. Follow the onboarding brief below.',
-    renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
-  });
+  return authenticatedResult(ctx);
 }
 
 export const onboardingCommandSpecs = [
   {
     command_path: ['start'],
-    summary: 'Create or access a Notis account and authorize the CLI.',
+    summary: 'Create or access a Notis account and authorize this CLI profile.',
     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.',
+      'Run this first on a new machine, before anything that needs auth. Safe to re-run. An account that has already completed onboarding gets orientation instead of an 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',
+      'notis start --profile work',
       'notis start --brief-only',
-      'notis start --email you@example.com --json',
+      'notis start --json',
     ],
     output_schema:
-      'Returns {authenticated, brief, brief_source} once signed in, or {next_action, cooldown_seconds, desktop_download_url} while waiting.',
+      'Returns {authenticated, profile, api_base, onboarding_complete, known_settings, missing_settings, brief, brief_source} once signed in — brief is null when onboarding_complete is true — or {authorize_url, expires_in, redeem_command} while waiting for browser authorization.',
     mutates: true,
     idempotent: true,
     require_auth: false,
-    related_commands: ['notis doctor', 'notis tools link'],
-    backend_call: { type: 'http', name: 'POST /signup/agent' },
+    allow_unknown_profile: true,
+    related_commands: ['notis login', 'notis profile list', 'notis doctor', 'notis tools link'],
+    backend_call: { type: 'oauth', name: 'authorization_code+pkce' },
     handler: startHandler,
   },
 ];