@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.160.1

package/src/command-specs/meta.js

@@ -1,15 +1,91 @@
-import { healthCheck, probeAuth } from './helpers.js';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { COMPOSIO_SEARCH_TOOLS, healthCheck, probeAuth } from './helpers.js';
 import { findCommandSpec, formatDescribe } from '../runtime/help.js';
+import { createExpiredAuthError, getAuthRecovery } from '../runtime/auth-recovery.js';
+import { cliCommandForChannel, resolveChannelSwitch } from '../runtime/channel.js';
+import {
+  credentialIsExpired,
+  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),
+  };
+}
+
+export function doctorChannelSummary(
+  runtime,
+  moduleDirectory = dirname(fileURLToPath(import.meta.url)),
+) {
+  const decision = resolveChannelSwitch({
+    runningVersion: runtime.cliVersion,
+    profile: {
+      channel: runtime.channel,
+      api_base: runtime.apiBase,
+    },
+    moduleDirectory,
+  });
+  const mismatch = Boolean(
+    decision.targetChannel
+    && decision.targetChannel !== decision.runningChannel,
+  );
+  const releaseChannel = runtime.worktreeRuntime ? 'dev' : runtime.channel;
+  return {
+    decision,
+    mismatch,
+    releaseChannel,
+    status: runtime.worktreeRuntime
+      ? 'dev'
+      : mismatch
+        ? `mismatch:${decision.reason}`
+        : decision.runningChannel,
+  };
+}
 
 async function doctorHandler(ctx) {
   const checks = {
     config: 'ok',
     auth: 'missing',
+    channel: 'unknown',
+    routing: 'ok',
     health: 'unknown',
     tool_roundtrip: 'unknown',
   };
 
-  checks.auth = ctx.runtime.jwt ? 'configured' : 'missing';
+  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.profileName);
+  checks.auth = ctx.runtime.jwt
+    ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
+    : 'missing';
+  // 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 (
+    ctx.runtime.worktreeRuntimeUnavailable
+    && ctx.runtime.profileSource !== 'explicit'
+  ) {
+    checks.routing = 'dev_runtime_unavailable';
+  } else if (
+    ctx.runtime.detachedWorktreeRuntime
+    || (ctx.runtime.worktreeRuntimeUnavailable && ctx.runtime.profileSource === 'explicit')
+  ) {
+    checks.routing = 'detached';
+  }
 
   try {
     await healthCheck(ctx.runtime);
@@ -20,19 +96,54 @@ async function doctorHandler(ctx) {
 
   if (ctx.runtime.jwt) {
     try {
-      const payload = await probeAuth(ctx.runtime);
-      checks.tool_roundtrip = Array.isArray(payload.toolkits) ? 'ok' : 'error';
+      // 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.profileName);
+      checks.auth = ctx.runtime.jwt
+        ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
+        : 'missing';
     } catch {
       checks.tool_roundtrip = 'error';
     }
   }
 
+  // A mismatch here means the automatic hand-off could not happen: a source
+  // checkout, an explicit opt-out, or a switch that could not reach npm. The
+  // profile still routes to the right API, so this reports rather than fails.
+  const {
+    decision: channelDecision,
+    mismatch: channelMismatch,
+    releaseChannel,
+    status: channelStatus,
+  } = doctorChannelSummary(ctx.runtime);
+  checks.channel = channelStatus;
+
   const hints = [];
+  if (channelMismatch) {
+    hints.push({
+      command: `${cliCommandForChannel(channelDecision.targetChannel)} doctor`,
+      reason: `Profile "${ctx.runtime.profileName}" belongs to the ${channelDecision.targetChannel} CLI channel`,
+    });
+  }
   if (checks.auth === 'missing') {
-    hints.push({ command: 'notis auth login --jwt <token>', reason: 'Configure credentials' });
+    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') {
-    hints.push({ command: 'notis auth status', reason: 'Check API base URL configuration' });
+  if (checks.health === 'error' && checks.auth !== 'expired') {
+    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' });
@@ -42,7 +153,19 @@ async function doctorHandler(ctx) {
     command: ctx.spec.command_path.join(' '),
     data: {
       profile: ctx.runtime.profileName,
+      profile_source: ctx.runtime.profileSource,
       api_base: ctx.runtime.apiBase,
+      release_channel: releaseChannel || null,
+      cli_version: ctx.runtime.cliVersion || null,
+      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}`,
@@ -66,19 +189,27 @@ 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.toolkits || [];
-  const userId = decodeJwtUserId(ctx.runtime.jwt);
+  const toolkits = payload.toolkit_connection_statuses || [];
+  const userId = activeRuntimeUserId(ctx.runtime);
 
   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,
       user_id: userId,
       toolkit_count: toolkits.length,
-      toolkits: toolkits.map((t) => t.id),
+      toolkits: toolkits.map((t) => t.toolkit),
       cli_version: ctx.runtime.cliVersion,
     },
     humanSummary: `Logged in as ${userId || 'unknown'} via profile "${ctx.runtime.profileName}"`,
@@ -91,8 +222,8 @@ async function whoamiHandler(ctx) {
         `Version:   ${ctx.runtime.cliVersion}`,
       ].join('\n'),
     hints: [
-      { command: 'notis tools toolkits', reason: 'List available toolkit namespaces' },
-      { command: 'notis doctor', reason: 'Run a full health check' },
+      { 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' },
     ],
   });
 }
@@ -110,15 +241,15 @@ async function describeHandler(ctx) {
 export const metaCommandSpecs = [
   {
     command_path: ['whoami'],
-    summary: 'Display the active profile, user, and available toolkits.',
+    summary: 'Display the active profile, user, and available toolkit connection statuses.',
     when_to_use: 'Use this to quickly confirm which account and environment a command will target.',
     args_schema: { arguments: [], options: [] },
     examples: ['notis whoami', 'notis whoami --json'],
     output_schema: 'Returns profile, api_base, user_id, toolkit count, and CLI version.',
     mutates: false,
     idempotent: true,
-    related_commands: ['notis auth status --verify', 'notis doctor'],
-    backend_call: { type: 'tool', name: 'notis_find_toolkits' },
+    related_commands: ['notis doctor'],
+    backend_call: { type: 'tool', name: COMPOSIO_SEARCH_TOOLS },
     handler: whoamiHandler,
   },
   {
@@ -130,7 +261,8 @@ export const metaCommandSpecs = [
     output_schema: 'Returns config, auth, health, and roundtrip check statuses.',
     mutates: false,
     idempotent: true,
-    related_commands: ['notis auth status --verify', 'notis tools toolkits'],
+    require_auth: false,
+    related_commands: ['notis tools toolkits'],
     backend_call: { type: 'health+tool_roundtrip' },
     handler: doctorHandler,
   },
@@ -139,10 +271,10 @@ export const metaCommandSpecs = [
     summary: 'Describe a first-class CLI command in detail.',
     when_to_use: 'Use this when an agent or human needs the exact shape, examples, and semantics of a command.',
     args_schema: {
-      arguments: [{ token: '<command...>', key: 'commandPath', description: 'Command path to describe, such as "apps push".' }],
+      arguments: [{ token: '<command...>', key: 'commandPath', description: 'Command path to describe, such as "apps deploy".' }],
       options: [],
     },
-    examples: ['notis describe apps push', 'notis describe db query'],
+    examples: ['notis describe apps deploy', 'notis describe tools exec'],
     output_schema: 'Returns the command spec metadata for the requested command.',
     mutates: false,
     idempotent: true,

package/src/command-specs/onboarding.js

@@ -0,0 +1,290 @@
+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 { 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';
+import { loginAgentAuthorizationPresentation } from './auth.js';
+import { installLocalAgentContext } from './agents.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
+ * 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 };
+  }
+}
+
+function isAuthenticated(runtime) {
+  return Boolean(runtime.jwt)
+    && !credentialIsExpired(runtime, getProfile(loadConfig(), runtime.profileName));
+}
+
+function renderAgentSetup(results) {
+  const configured = (results || []).filter((result) => result?.agent && result?.instructions);
+  if (!configured.length) return '';
+  const lines = configured.map((result) => {
+    const label = result.agent === 'claude-code' ? 'Claude Code' : 'Codex';
+    const instructions = result.instructions?.status || 'skipped';
+    const memoryStatus = result.memory_hook?.status || 'skipped';
+    const memory = memoryStatus === 'preserved'
+      ? 'memory hooks not changed'
+      : `memory recall and capture ${memoryStatus}`;
+    return `- ${label}: instructions ${instructions}; ${memory}`;
+  });
+  if (configured.some((result) => (
+    result.agent === 'codex'
+    && ['installed', 'updated', 'unchanged'].includes(result.memory_hook?.status)
+  ))) {
+    lines.push('- Codex: open /hooks once and trust the Notis hooks before they can run.');
+  }
+  return ['## Coding-agent setup', ...lines].join('\n');
+}
+
+function agentSetupHints(results) {
+  const hints = [];
+  if ((results || []).some((result) => (
+    result.agent === 'codex'
+    && ['installed', 'updated', 'unchanged'].includes(result.memory_hook?.status)
+  ))) {
+    hints.push({ message: 'In Codex, open /hooks once and trust the Notis hooks.' });
+  }
+  if ((results || []).some((result) => result.status === 'not_detected')) {
+    hints.push({ command: 'notis agents install', reason: 'Configure Codex and Claude Code later if they were not detected now' });
+  }
+  if ((results || []).some((result) => result.memory_hook?.status === 'preserved')) {
+    hints.push({ command: 'notis agents install', reason: 'Explicitly enable Notis memory recall and completed-turn capture' });
+  }
+  return hints;
+}
+
+/**
+ * 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 } : {}),
+  };
+  try {
+    base.agent_setup = installLocalAgentContext(ctx, {
+      onlyExisting: true,
+      memoryHooks: null,
+    });
+  } catch {
+    // Authentication and onboarding remain usable if a local vendor config is
+    // malformed or read-only. `notis agents install` reports the exact path.
+    base.agent_setup = [];
+  }
+
+  if (onboardingComplete) {
+    const name = state?.settings?.first_name;
+    const setupSummary = renderAgentSetup(base.agent_setup);
+    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.',
+          ...(setupSummary ? ['', setupSummary] : []),
+        ].join('\n'),
+      hints: [
+        { 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' },
+        ...agentSetupHints(base.agent_setup),
+      ],
+    });
+  }
+
+  const brief = await fetchBrief(ctx.runtime.apiBase, ctx.runtime.timeoutMs);
+  const setupSummary = renderAgentSetup(base.agent_setup);
+  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.',
+      setupSummary,
+    ].filter(Boolean).join('\n\n'),
+    hints: agentSetupHints(base.agent_setup),
+  });
+}
+
+async function startHandler(ctx) {
+  const { runtime, options, output } = ctx;
+  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 runs surface the normal
+      // authentication recovery below.
+    }
+  }
+
+  // Safe to re-run: an already-authorized profile skips straight to the brief.
+  if (isAuthenticated(runtime)) {
+    return authenticatedResult(ctx);
+  }
+
+  if (options.briefOnly) {
+    throw new CliError({
+      code: 'auth_missing',
+      message: `Profile "${runtime.profileName}" is not signed in to Notis yet.`,
+      exitCode: EXIT_CODES.auth,
+      hints: getAuthRecovery(runtime, { mode: 'missing' }).hints,
+    });
+  }
+
+  // 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, mode: options.mode, reusePersistedCredential: true },
+    output,
+  );
+  if (authorization?.agentAuthorization) {
+    const presentation = loginAgentAuthorizationPresentation(authorization.agentAuthorization);
+    return output.emitSuccess({
+      command: 'start',
+      data: {
+        authenticated: false,
+        profile: runtime.profileName,
+        ...authorization.agentAuthorization,
+      },
+      ...presentation,
+    });
+  }
+
+  // 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_missing',
+      message: `Authorization did not complete for profile "${runtime.profileName}".`,
+      exitCode: EXIT_CODES.auth,
+      hints: getAuthRecovery(runtime, { mode: 'missing' }).hints,
+    });
+  }
+
+  return authenticatedResult(ctx);
+}
+
+export const onboardingCommandSpecs = [
+  {
+    command_path: ['start'],
+    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 account that has already completed onboarding gets orientation instead of an onboarding brief.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--brief-only', description: 'Print the onboarding brief for an already-signed-in profile.' },
+        { flags: '--mode <mode>', description: 'auto (default) hands the browser callback to a background listener when this command cannot wait; browser waits in-process; code shows a one-time code to copy.' },
+      ],
+    },
+    examples: [
+      'notis start',
+      'notis start --profile work',
+      'notis start --mode browser',
+      'notis start --brief-only',
+      'notis start --json',
+    ],
+    output_schema:
+      'Returns {authenticated, profile, api_base, onboarding_complete, known_settings, missing_settings, agent_setup, brief, brief_source} once signed in — brief is null when onboarding_complete is true — or {authorize_url, expires_in, hand_off, ...} while waiting for browser authorization. hand_off is "browser_callback" when signing in finishes the login by itself (re-run confirm_command to see it land) or "code" when the user must be asked for the code the page shows and it redeemed with redeem_command.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    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,
+  },
+];