@notis_ai/cli 0.2.8 → 0.2.10

package/src/command-specs/apps.js

@@ -44,15 +44,18 @@ import {
   runHarnessRoute,
 } from '../runtime/agent-browser.js';
 import {
+  getAppDevSessionsFile,
   heartbeatAppDevSession,
   removeAppDevSession,
   upsertAppDevSessions,
   waitForAppDevSessionMountAcknowledgements,
+  waitForAppDevSessionRenderAcknowledgements,
 } from '../runtime/app-dev-sessions.js';
 import { getAvailablePort } from '../runtime/ports.js';
 import { getCliMode } from '../runtime/cli-mode.js';
 import { composeStoreScreenshot } from '../runtime/store-screenshot.js';
 import { httpRequest } from '../runtime/transport.js';
+import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
 import {
   localNotisToolSlug,
   nextIdempotencyKey,
@@ -140,13 +143,24 @@ function decodeJwtSub(jwt) {
   }
 }
 
-function openInBrowser(url) {
-  const platform = process.platform;
+export function developmentDesktopOpenCommand(
+  url,
+  {
+    platform = process.platform,
+    appName = null,
+    bundleId = null,
+    scheme = 'notis',
+  } = {},
+) {
   let command;
   let args;
   if (platform === 'darwin') {
     command = 'open';
-    args = [url];
+    args = bundleId && scheme === 'notis'
+      ? ['-b', bundleId, url]
+      : appName && scheme === 'notis'
+        ? ['-a', appName, url]
+        : [url];
   } else if (platform === 'win32') {
     command = 'cmd';
     args = ['/c', 'start', '', url];
@@ -154,10 +168,14 @@ function openInBrowser(url) {
     command = 'xdg-open';
     args = [url];
   }
+  return { command, args };
+}
+
+function openInBrowser(url, options = {}) {
+  const { command, args } = developmentDesktopOpenCommand(url, options);
   try {
-    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    const child = spawn(command, args, { stdio: 'ignore' });
     child.on('error', () => {});
-    child.unref();
   } catch {
     // Non-fatal. The URL is printed in the CLI output.
   }
@@ -207,21 +225,55 @@ function pickDefaultRouteSlug(manifest) {
 
 const DESKTOP_DEEP_LINK_SCHEME_PATTERN = /^[a-z][a-z0-9-]*$/;
 
-export function resolveDevelopmentDesktopScheme(env = process.env) {
+export function resolveDevelopmentDesktopScheme(env = process.env, worktreeRuntime = null) {
   // Mirror the desktop app's own scheme resolution (electron main + forge config):
   // local dev launches register `notis-dev`, while installed prod/beta builds claim
   // `notis`. Hardcoding `notis` here is what made `apps dev` open the installed
   // prod/beta app instead of the local dev app.
-  const scheme = (env.NOTIS_DESKTOP_DEEP_LINK_SCHEME || '').trim();
+  const scheme = (
+    worktreeRuntime?.desktop_deep_link_scheme
+    || env.NOTIS_DESKTOP_DEEP_LINK_SCHEME
+    || ''
+  ).trim();
   return DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
 }
 
+export function resolveDevelopmentDesktopAppName(runtime = {}) {
+  const explicit = String(
+    runtime.desktopAppName
+    || runtime.worktreeRuntime?.desktop_app_name
+    || '',
+  ).trim();
+  if (explicit) {
+    return explicit;
+  }
+  try {
+    return new URL(runtime.apiBase).hostname === 'api-beta.notis.ai'
+      ? 'Notis Beta'
+      : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function resolveDevelopmentDesktopBundleId(runtime = {}) {
+  return resolveDevelopmentDesktopAppName(runtime) === 'Notis Beta'
+    ? 'ai.notis.desktop.beta'
+    : 'ai.notis.desktop';
+}
+
 export function buildDevelopmentDesktopUrl(appHref = null, scheme = 'notis') {
   const route = String(appHref || '/store').replace(/^\/+/, '');
   const normalizedScheme = DESKTOP_DEEP_LINK_SCHEME_PATTERN.test(scheme) ? scheme : 'notis';
   return `${normalizedScheme}://${route || 'store'}`;
 }
 
+export function buildMountedDevelopmentDesktopUrl(appHref, scheme, sessionId) {
+  const url = new URL(buildDevelopmentDesktopUrl(appHref, scheme));
+  url.searchParams.set('notis_dev_session', sessionId);
+  return url.toString();
+}
+
 export function shouldOpenDevelopmentTab(options = {}) {
   // Commander stores the negatable `--no-open` flag as `options.open === false`;
   // it never sets `options.noOpen`. Reading the non-existent `noOpen` key meant
@@ -230,8 +282,17 @@ export function shouldOpenDevelopmentTab(options = {}) {
   return options.open !== false;
 }
 
-function buildAppHref({ appSlug, appId, manifest }) {
-  const originlessBase = `/apps/${appSlug}-${appId}`;
+export function buildDevelopmentAppHref({
+  appSlug,
+  appId,
+  devSlug,
+  targetAppId = null,
+  targetAppSlug = null,
+  manifest,
+}) {
+  const routeAppId = `${targetAppId || appId}__local_dev__${devSlug}`;
+  const routeAppSlug = targetAppSlug || devSlug || appSlug;
+  const originlessBase = `/apps/${routeAppSlug}-${routeAppId}`;
   const routeSlug = pickDefaultRouteSlug(manifest);
   return routeSlug ? `${originlessBase}/${routeSlug}` : originlessBase;
 }
@@ -499,8 +560,23 @@ export async function ensureDevInstall({
   const manifest = buildManifestForDev(appConfig);
   const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   let linkedState = readLinkedState(projectDir);
+  let linkedApp = null;
+  if (linkedState?.dev_app_id) {
+    // Stale cross-runtime / deleted dev apps often surface as PostgREST PGRST116
+    // zero-row errors from LOCAL_NOTIS_GET_APP (.single()), not exact "App not found".
+    // Treat those as absence so ensure can clear and reprovision. Installed app_id
+    // verification below stays fail-closed on unstructured DB errors.
+    const devApp = await getAccessibleApp(ctx.runtime, linkedState.dev_app_id, runTool, {
+      treatPostgrestAbsenceAsMissing: true,
+    });
+    if (!devApp || devApp.manifest?.is_dev !== true) {
+      const { dev_app_id: _devAppId, dev_linked_at: _devLinkedAt, ...rest } = linkedState;
+      linkedState = rest;
+      writeLinkedState(projectDir, linkedState);
+    }
+  }
   if (linkedState?.app_id) {
-    const linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
+    linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
     if (linkedApp?.manifest?.is_dev === true) {
       const { app_id: legacyDevAppId, linked_at: _linkedAt, deployed_at: _deployedAt, version: _version, ...rest } = linkedState;
       const devAppId = linkedState.dev_app_id || legacyDevAppId;
@@ -512,6 +588,7 @@ export async function ensureDevInstall({
         } : {}),
       };
       writeLinkedState(projectDir, linkedState);
+      linkedApp = null;
     }
   }
   const ensureArguments = buildEnsureDevInstallArguments({ appConfig, manifest, linkedState, skills });
@@ -544,6 +621,7 @@ export async function ensureDevInstall({
     created: ensureResult.payload.created || false,
     linkedAppId: linkedState?.app_id || null,
     targetAppId: linkedState?.app_id || null,
+    targetAppSlug: linkedApp?.slug || null,
     databaseMaterialization: ensureResult.payload.database_materialization || { created: [], unresolved: [] },
   };
 }
@@ -563,11 +641,19 @@ function databaseMaterializationWarnings(apps) {
   return warnings;
 }
 
-async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
+function isPostgrestNoRowsMessage(message) {
+  const text = String(message || '');
+  return /\bPGRST116\b/.test(text)
+    || /\b0 rows\b/i.test(text)
+    || /no rows returned/i.test(text);
+}
+
+async function getAccessibleApp(runtime, appId, runTool = runToolCommand, options = {}) {
+  const { treatPostgrestAbsenceAsMissing = false } = options;
   const result = await runTool({
     runtime,
     toolName: GET_APP_TOOL,
-    arguments_: { app_id: appId },
+    arguments_: { app_id: appId, include_documents: false },
   });
   if (result.payload?.app) {
     return {
@@ -576,7 +662,15 @@ async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
     };
   }
   const message = typeof result.payload?.message === 'string' ? result.payload.message : '';
-  if (result.payload?.status === 'error' && /PGRST116|0 rows|no rows|not found/i.test(message)) {
+  const errorCode = result.payload?.code || result.payload?.error?.code;
+  if (
+    result.payload?.status === 'error'
+    && (
+      errorCode === 'app_not_found'
+      || /^App not found\.?$/i.test(message.trim())
+      || (treatPostgrestAbsenceAsMissing && isPostgrestNoRowsMessage(message))
+    )
+  ) {
     return null;
   }
   throw usageError(`Could not verify access to app ${appId}${message ? `: ${message}` : '.'}`);
@@ -725,6 +819,15 @@ async function appsDevHandler(ctx) {
     throw usageError('Could not determine the current user from the CLI auth token. Open the Notis desktop app, sign in, and retry.');
   }
   const apiBase = String(ctx.runtime.apiBase || '').replace(/\/$/, '');
+  const sessionsFilePath = getAppDevSessionsFile(
+    ctx.runtime.worktreeRuntime?.app_dev_sessions_file,
+  );
+  const desktopScheme = resolveDevelopmentDesktopScheme(
+    process.env,
+    ctx.runtime.worktreeRuntime,
+  );
+  const desktopAppName = resolveDevelopmentDesktopAppName(ctx.runtime);
+  const desktopBundleId = resolveDevelopmentDesktopBundleId(ctx.runtime);
   const sessionId = randomUUID();
 
   const candidates = [];
@@ -780,16 +883,25 @@ async function appsDevHandler(ctx) {
       ...app,
       bundleBaseUrl,
       mountNonce: randomUUID(),
-      appHref: buildAppHref({
+      appHref: buildDevelopmentAppHref({
         appSlug: app.slug,
         appId: app.appId,
+        devSlug: app.devSlug,
+        targetAppId: app.targetAppId,
+        targetAppSlug: app.targetAppSlug,
         manifest: app.manifest,
       }),
     };
   });
   const developmentTabUrl = buildDevelopmentDesktopUrl(
     apps[0]?.appHref,
-    resolveDevelopmentDesktopScheme(),
+    desktopScheme,
+  );
+  const desktopWakeUrl = buildDevelopmentDesktopUrl('/manage', desktopScheme);
+  const mountedDevelopmentTabUrl = buildMountedDevelopmentDesktopUrl(
+    apps[0]?.appHref,
+    desktopScheme,
+    sessionId,
   );
   const warnings = databaseMaterializationWarnings(apps);
 
@@ -802,6 +914,7 @@ async function appsDevHandler(ctx) {
       userId: identity,
     })),
     port,
+    sessionsFilePath,
   });
 
   try {
@@ -818,7 +931,8 @@ async function appsDevHandler(ctx) {
       projectDir: app.projectDir,
       startedAt: now,
       lastHeartbeatAt: now,
-    })));
+      desktopAppName,
+    })), sessionsFilePath);
   } catch (error) {
     try {
       await devServer.close();
@@ -830,7 +944,7 @@ async function appsDevHandler(ctx) {
 
   let heartbeatTimer = setInterval(() => {
     try {
-      heartbeatAppDevSession(sessionId, new Date().toISOString());
+      heartbeatAppDevSession(sessionId, new Date().toISOString(), sessionsFilePath);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       process.stderr.write(`[notis apps dev] heartbeat failed: ${message}\n`);
@@ -852,6 +966,8 @@ async function appsDevHandler(ctx) {
       development_url: developmentTabUrl,
       session_id: sessionId,
       mount_status: 'serving',
+      render_status: 'waiting_for_route',
+      desktop_target: desktopAppName,
       identity,
       apps: apps.map((app) => ({
         slug: app.devSlug,
@@ -869,36 +985,67 @@ async function appsDevHandler(ctx) {
     warnings,
     humanSummary: [
       `Running apps dev against ${apiBase} as ${identity} (mode: ${mode})`,
+      `Target desktop: ${desktopAppName}`,
       '',
       `Open in desktop: ${developmentTabUrl}`,
       '',
       ...apps.map((app) => `  ${app.name.padEnd(24)} ${app.bundleBaseUrl} -> ${app.appHref}`),
       '',
-      `Serving locally; waiting for Notis to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
+      `Serving locally; waiting for ${desktopAppName} to mount ${apps.length === 1 ? 'the app' : `${apps.length} apps`}.`,
       '',
       'Press Ctrl-C to stop.',
     ].join('\n'),
   });
 
   if (shouldOpenDevelopmentTab(ctx.options)) {
-    openInBrowser(developmentTabUrl);
+    openInBrowser(desktopWakeUrl, {
+      appName: desktopAppName,
+      bundleId: desktopBundleId,
+      scheme: desktopScheme,
+    });
   }
 
   void (async () => {
-    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements);
+    let result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+      sessionsFilePath,
+    });
     if (!result.mounted) {
       process.stderr.write(
-        `[notis apps dev] Serving locally, but Notis has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open Notis.\n`,
+        `[notis apps dev] Serving locally, but ${desktopAppName} has not acknowledged ${result.missing.length === 1 ? 'the app' : `${result.missing.length} apps`} in its Local development sidebar yet. Keep this command running and open ${desktopAppName}.\n`,
       );
     }
     while (!result.mounted) {
       result = await waitForAppDevSessionMountAcknowledgements(expectedMountAcknowledgements, {
+        sessionsFilePath,
         timeoutMs: 60_000,
         pollIntervalMs: 250,
       });
     }
     process.stderr.write(
-      `[notis apps dev] Mounted in Notis: ${apps.map((app) => app.name).join(', ')}.\n`,
+      `[notis apps dev] Mounted in ${desktopAppName}: ${apps.map((app) => app.name).join(', ')}.\n`,
+    );
+    if (shouldOpenDevelopmentTab(ctx.options)) {
+      openInBrowser(mountedDevelopmentTabUrl, {
+        appName: desktopAppName,
+        bundleId: desktopBundleId,
+        scheme: desktopScheme,
+      });
+    }
+
+    const firstAppRender = expectedMountAcknowledgements.slice(0, 1);
+    let renderResult = await waitForAppDevSessionRenderAcknowledgements(firstAppRender, {
+      sessionsFilePath,
+      timeoutMs: 0,
+    });
+    while (!renderResult.mounted) {
+      renderResult = await waitForAppDevSessionRenderAcknowledgements(firstAppRender, {
+        sessionsFilePath,
+        timeoutMs: 60_000,
+        pollIntervalMs: 250,
+      });
+    }
+    process.stderr.write(
+      `[notis apps dev] Rendered in ${desktopAppName}: ${apps[0].name}.\n`,
     );
   })().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
@@ -915,7 +1062,7 @@ async function appsDevHandler(ctx) {
       heartbeatTimer = null;
     }
     try {
-      removeAppDevSession(sessionId);
+      removeAppDevSession(sessionId, sessionsFilePath);
     } catch {
       // ignore cleanup failures during shutdown
     }
@@ -971,6 +1118,12 @@ async function appsVerifyHandler(ctx) {
 
   let linkedState = null;
   if (mode === 'live') {
+    if (
+      ctx.runtime.credentialKind === 'oauth'
+      && !await ensureFreshOAuthCredential(ctx.runtime)
+    ) {
+      throw usageError('Live verify mode requires a current OAuth grant. Run `notis login` and retry.');
+    }
     if (!ctx.runtime.jwt) {
       throw usageError('Live verify mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
@@ -1185,6 +1338,12 @@ async function appsScreenshotHandler(ctx) {
 
   let linkedState = null;
   if (mode === 'live') {
+    if (
+      ctx.runtime.credentialKind === 'oauth'
+      && !await ensureFreshOAuthCredential(ctx.runtime)
+    ) {
+      throw usageError('Live mode requires a current OAuth grant. Run `notis login` and retry.');
+    }
     if (!ctx.runtime.jwt) {
       throw usageError('Live mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
@@ -1423,6 +1582,12 @@ async function appsPullHandler(ctx) {
     toolName: GET_APP_TOOL,
     arguments_: { app_id: appId },
   });
+  if (
+    ctx.runtime.credentialKind === 'oauth'
+    && !await ensureFreshOAuthCredential(ctx.runtime)
+  ) {
+    throw usageError('Pulling app source requires a current OAuth grant. Run `notis login` and retry.');
+  }
   const app = result.payload?.app || {};
   const defaultDir = app.slug || slugify(app.name) || appId;
   const targetDir = resolveProjectDir(ctx.args.dir || defaultDir);

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/diagnostics.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { usageError } from '../runtime/errors.js';
 import {
@@ -178,6 +178,11 @@ async function executeReadOnlySql(ctx, query, phase) {
       tools: [{ tool_slug: toolName, arguments: { query } }],
     },
     mutating: false,
+    // Always a fresh key, never the operator's --idempotency-key: a diagnostic
+    // must observe current state rather than replay a cached response, and two
+    // different queries under one reused key would collide on the request hash.
+    idempotencyKey: randomUUID(),
+    sendIdempotencyKeyWhenReading: true,
   });
   if (result.payload?.successful === false || result.payload?.error) {
     throw usageError(

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

@@ -4,6 +4,7 @@ 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.',
@@ -13,6 +14,7 @@ export const GROUP_SUMMARIES = {
 };
 
 export const COMMAND_SPECS = [
+  ...authCommandSpecs,
   ...onboardingCommandSpecs,
   ...appsCommandSpecs,
   ...toolsCommandSpecs,