@notis_ai/cli 0.2.0-beta.102.1

package/src/runtime/cli-mode.generated.js

@@ -0,0 +1,4 @@
+// Auto-generated on npm publish.
+// Committed value is 'local' so in-repo runs target localhost.
+// scripts/set-cli-mode.js rewrites this to 'published' before the npm publish step.
+export const MODE = 'local';

package/src/runtime/cli-mode.js

@@ -0,0 +1,29 @@
+/**
+ * CLI mode detection for `notis apps dev`.
+ *
+ * The repo-local CLI package targets localhost; the published npm CLI package
+ * targets app.notis.ai. Mode is baked into `cli-mode.generated.js` at publish
+ * time — no runtime flag is needed (and none is exposed to end users, so a
+ * crafted env var can't trick a published CLI into opening a localhost portal
+ * that isn't running).
+ *
+ * The `NOTIS_CLI_MODE` env var is honored for internal testing only.
+ */
+
+import { MODE as BAKED_MODE } from './cli-mode.generated.js';
+
+export function getCliMode() {
+  const override = process.env.NOTIS_CLI_MODE;
+  if (override === 'local' || override === 'published') {
+    return override;
+  }
+  return BAKED_MODE === 'published' ? 'published' : 'local';
+}
+
+export function getDefaultApiBase(mode = getCliMode()) {
+  return mode === 'local' ? 'http://localhost:3001' : 'https://api.notis.ai';
+}
+
+export function getDefaultPortalOrigin(mode = getCliMode()) {
+  return mode === 'local' ? 'http://localhost:3000' : 'https://app.notis.ai';
+}

package/src/runtime/desktop-auth.js

@@ -0,0 +1,93 @@
+import { CliError, EXIT_CODES } from './errors.js';
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function quoteShellArgument(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function defaultDesktopAppName(apiBase) {
+  try {
+    return new URL(apiBase).hostname === 'api-beta.notis.ai' ? 'Notis Beta' : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function getDesktopAuthRecovery(runtime) {
+  const desktopRunning = isPidRunning(runtime.desktopPid);
+  const appName = runtime.desktopAppName || defaultDesktopAppName(runtime.apiBase);
+  let command = 'Start the Notis desktop app';
+  if (process.platform === 'darwin') {
+    command = `open -a ${quoteShellArgument(appName)}`;
+  }
+
+  return {
+    desktopRunning,
+    appName,
+    hints: [
+      {
+        command,
+        reason: desktopRunning
+          ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
+          : `Start ${appName} to renew expired CLI authentication, then retry`,
+      },
+      {
+        command: 'notis doctor',
+        reason: 'Retry the auth and API checks after the desktop app is ready',
+      },
+    ],
+  };
+}
+
+export function createExpiredAuthError(runtime) {
+  if (runtime.credentialSource === 'env') {
+    return new CliError({
+      code: 'auth_expired',
+      message: 'NOTIS_JWT is expired',
+      exitCode: EXIT_CODES.auth,
+      details: { credential_source: 'env' },
+      hints: [
+        {
+          command: 'Set NOTIS_JWT to a fresh token',
+          reason: 'The explicit environment credential overrides desktop-managed auth',
+        },
+      ],
+    });
+  }
+
+  const recovery = getDesktopAuthRecovery(runtime);
+  return new CliError({
+    code: 'auth_expired',
+    message: 'Notis CLI authentication has expired',
+    exitCode: EXIT_CODES.auth,
+    details: {
+      credential_source: 'desktop',
+      desktop_running: recovery.desktopRunning,
+      desktop_app_name: recovery.appName,
+    },
+    hints: recovery.hints,
+  });
+}
+
+export function createInvalidAuthHints(runtime) {
+  if (runtime?.credentialSource === 'env') {
+    return [
+      {
+        command: 'Set NOTIS_JWT to a fresh token',
+        reason: 'The explicit environment credential was rejected',
+      },
+    ];
+  }
+  return getDesktopAuthRecovery(runtime || {}).hints;
+}

package/src/runtime/errors.js

@@ -0,0 +1,55 @@
+export const EXIT_CODES = {
+  ok: 0,
+  usage: 2,
+  auth: 3,
+  network: 4,
+  conflict: 5,
+  backend: 6,
+  unexpected: 7,
+};
+
+export class CliError extends Error {
+  constructor({
+    code,
+    message,
+    exitCode = EXIT_CODES.unexpected,
+    retryable = false,
+    details = {},
+    hints = [],
+    warnings = [],
+    cause,
+  }) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.exitCode = exitCode;
+    this.retryable = retryable;
+    this.details = details;
+    this.hints = hints;
+    this.warnings = warnings;
+    this.cause = cause;
+  }
+}
+
+export function asCliError(error) {
+  if (error instanceof CliError) {
+    return error;
+  }
+
+  return new CliError({
+    code: 'unexpected_error',
+    message: error instanceof Error ? error.message : String(error),
+    exitCode: EXIT_CODES.unexpected,
+    cause: error,
+  });
+}
+
+export function usageError(message, details = {}) {
+  return new CliError({
+    code: 'usage_error',
+    message,
+    details,
+    exitCode: EXIT_CODES.usage,
+  });
+}
+

package/src/runtime/help.js

@@ -0,0 +1,60 @@
+import { usageError } from './errors.js';
+
+export function canonicalCommandName(spec) {
+  return spec.display_name || spec.command_path.join(' ');
+}
+
+export function formatDescribe(spec) {
+  const lines = [
+    `${canonicalCommandName(spec)}`,
+    '',
+    spec.summary,
+    '',
+    'When to use:',
+    `  ${spec.when_to_use}`,
+    '',
+    `Mutates state: ${spec.mutates ? 'yes' : 'no'}`,
+    `Idempotent: ${spec.idempotent ? 'yes' : 'no'}`,
+    '',
+    'Arguments and options:',
+  ];
+
+  const args = spec.args_schema?.arguments || [];
+  const options = spec.args_schema?.options || [];
+  if (!args.length && !options.length) {
+    lines.push('  None');
+  } else {
+    for (const arg of args) {
+      lines.push(`  ${arg.token}  ${arg.description}`);
+    }
+    for (const option of options) {
+      lines.push(`  ${option.flags}  ${option.description}`);
+    }
+  }
+
+  lines.push('', 'Examples:');
+  for (const example of spec.examples || []) {
+    lines.push(`  ${example}`);
+  }
+
+  lines.push('', 'Output shape:', `  ${spec.output_schema}`);
+  lines.push('', 'Backend call:', `  ${JSON.stringify(spec.backend_call)}`);
+
+  if (spec.related_commands?.length) {
+    lines.push('', 'Related commands:');
+    for (const related of spec.related_commands) {
+      lines.push(`  ${related}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function findCommandSpec(specs, inputPath) {
+  const normalized = inputPath.join(' ').trim().toLowerCase();
+  const spec = specs.find((entry) => entry.command_path.join(' ').toLowerCase() === normalized);
+  if (!spec) {
+    throw usageError(`Unknown command path: ${inputPath.join(' ')}`);
+  }
+  return spec;
+}

package/src/runtime/output.js

@@ -0,0 +1,180 @@
+import { inspect } from 'node:util';
+import { EXIT_CODES } from './errors.js';
+
+function pad(value, width) {
+  return String(value).padEnd(width);
+}
+
+function formatTable(rows, columns) {
+  if (!rows.length) {
+    return '';
+  }
+
+  const widths = columns.map((column) => {
+    const headerWidth = column.label.length;
+    const valueWidth = Math.max(...rows.map((row) => String(column.value(row) ?? '').length), 0);
+    return Math.max(headerWidth, valueWidth);
+  });
+
+  const header = columns.map((column, index) => pad(column.label, widths[index])).join('  ');
+  const divider = columns.map((_, index) => '-'.repeat(widths[index])).join('  ');
+  const body = rows.map((row) => columns.map((column, index) => pad(column.value(row) ?? '', widths[index])).join('  '));
+  return [header, divider, ...body].join('\n');
+}
+
+function yamlScalar(value) {
+  if (value === null || value === undefined) {
+    return 'null';
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  return JSON.stringify(String(value));
+}
+
+function toYaml(value, indent = 0) {
+  const prefix = ' '.repeat(indent);
+
+  if (Array.isArray(value)) {
+    if (!value.length) {
+      return `${prefix}[]`;
+    }
+    return value
+      .map((item) => {
+        if (item && typeof item === 'object') {
+          const nested = toYaml(item, indent + 2);
+          return `${prefix}-\n${nested}`;
+        }
+        return `${prefix}- ${yamlScalar(item)}`;
+      })
+      .join('\n');
+  }
+
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (!entries.length) {
+      return `${prefix}{}`;
+    }
+    return entries
+      .map(([key, nestedValue]) => {
+        if (nestedValue && typeof nestedValue === 'object') {
+          return `${prefix}${key}:\n${toYaml(nestedValue, indent + 2)}`;
+        }
+        return `${prefix}${key}: ${yamlScalar(nestedValue)}`;
+      })
+      .join('\n');
+  }
+
+  return `${prefix}${yamlScalar(value)}`;
+}
+
+function serializeMachineEnvelope(envelope, outputMode) {
+  if (outputMode === 'yaml') {
+    return `${toYaml(envelope)}\n`;
+  }
+  if (outputMode === 'ndjson') {
+    return `${JSON.stringify(envelope)}\n`;
+  }
+  return `${JSON.stringify(envelope, null, 2)}\n`;
+}
+
+export class OutputManager {
+  constructor(runtime) {
+    this.runtime = runtime;
+  }
+
+  isMachineMode() {
+    return this.runtime.outputMode !== 'table';
+  }
+
+  writeWarning(message) {
+    if (this.isMachineMode()) {
+      return;
+    }
+    process.stderr.write(`${message}\n`);
+  }
+
+  emitSuccess({
+    ok = true,
+    command,
+    data = {},
+    humanSummary,
+    hints = [],
+    warnings = [],
+    requestId = null,
+    meta = {},
+    renderHuman,
+  }) {
+    const envelope = {
+      ok: Boolean(ok),
+      command,
+      data,
+      human_summary: humanSummary,
+      hints,
+      warnings,
+      request_id: requestId,
+      meta: {
+        profile: this.runtime.profileName,
+        api_base: this.runtime.apiBase,
+        mutating: Boolean(meta.mutating),
+        ...meta,
+      },
+    };
+
+    if (this.isMachineMode()) {
+      process.stdout.write(serializeMachineEnvelope(envelope, this.runtime.outputMode));
+      return EXIT_CODES.ok;
+    }
+
+    for (const warning of warnings) {
+      this.writeWarning(`Warning: ${warning}`);
+    }
+
+    if (typeof renderHuman === 'function') {
+      const rendered = renderHuman();
+      if (rendered) {
+        process.stdout.write(`${rendered}\n`);
+      }
+    } else if (humanSummary) {
+      process.stdout.write(`${humanSummary}\n`);
+    } else if (Object.keys(data).length) {
+      process.stdout.write(`${inspect(data, { depth: null, colors: this.runtime.color })}\n`);
+    }
+
+    if (hints.length) {
+      const lines = hints.map((hint) => `  ${hint.command}  ${hint.reason}`);
+      process.stdout.write(`\nNext:\n${lines.join('\n')}\n`);
+    }
+
+    return EXIT_CODES.ok;
+  }
+
+  emitError({ command, error, requestId = null }) {
+    const envelope = {
+      ok: false,
+      command,
+      error: {
+        code: error.code,
+        message: error.message,
+        retryable: Boolean(error.retryable),
+        details: error.details || {},
+      },
+      hints: error.hints || [],
+      warnings: error.warnings || [],
+      request_id: requestId,
+    };
+
+    if (this.isMachineMode()) {
+      process.stdout.write(serializeMachineEnvelope(envelope, this.runtime.outputMode));
+      return error.exitCode || EXIT_CODES.unexpected;
+    }
+
+    process.stderr.write(`Error: ${error.message}\n`);
+    for (const hint of error.hints || []) {
+      process.stderr.write(`  ${hint.command}  ${hint.reason}\n`);
+    }
+    return error.exitCode || EXIT_CODES.unexpected;
+  }
+}
+
+export { formatTable };

package/src/runtime/ports.js

@@ -0,0 +1,15 @@
+import { createServer } from 'node:http';
+
+export async function getAvailablePort() {
+  const server = createServer();
+  await new Promise((resolvePromise, rejectPromise) => {
+    server.once('error', rejectPromise);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', rejectPromise);
+      resolvePromise();
+    });
+  });
+  const { port } = server.address();
+  await new Promise((resolvePromise) => server.close(resolvePromise));
+  return port;
+}

package/src/runtime/profiles.js

@@ -0,0 +1,261 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { CliError, EXIT_CODES } from './errors.js';
+import { getDesktopAuthRecovery } from './desktop-auth.js';
+
+export const CONFIG_DIR = join(homedir(), '.notis');
+export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+export const WORKSPACE_DIR = join(CONFIG_DIR, 'workspace');
+export const DEFAULT_API_BASE = 'https://api.notis.ai';
+export const DEFAULT_PROFILE = 'default';
+const LOCAL_DEFAULT_API_BASES = new Set([
+  'http://localhost:3001',
+  'http://127.0.0.1:3001',
+]);
+const LOCAL_API_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function normalizeConfig(rawConfig = {}) {
+  const raw = rawConfig && typeof rawConfig === 'object' ? clone(rawConfig) : {};
+
+  if (raw.profiles && typeof raw.profiles === 'object') {
+    const profiles = {};
+    for (const [name, profile] of Object.entries(raw.profiles)) {
+      if (!profile || typeof profile !== 'object') {
+        continue;
+      }
+      profiles[name] = {
+        jwt: typeof profile.jwt === 'string' ? profile.jwt : undefined,
+        api_base: typeof profile.api_base === 'string' ? profile.api_base : undefined,
+        auth_mode: profile.auth_mode === 'dev_portal' ? profile.auth_mode : undefined,
+        refresh_token:
+          typeof profile.refresh_token === 'string' ? profile.refresh_token : undefined,
+        access_expires_at:
+          typeof profile.access_expires_at === 'number' ? profile.access_expires_at : undefined,
+        refresh_expires_at:
+          typeof profile.refresh_expires_at === 'number' ? profile.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof profile.desktop_app_name === 'string' ? profile.desktop_app_name : undefined,
+        desktop_pid: typeof profile.desktop_pid === 'number' ? profile.desktop_pid : undefined,
+      };
+    }
+
+    if (!profiles[DEFAULT_PROFILE]) {
+      profiles[DEFAULT_PROFILE] = {};
+    }
+
+    return {
+      current_profile:
+        typeof raw.current_profile === 'string' && raw.current_profile in profiles
+          ? raw.current_profile
+          : DEFAULT_PROFILE,
+      profiles,
+    };
+  }
+
+  return {
+    current_profile: DEFAULT_PROFILE,
+    profiles: {
+      [DEFAULT_PROFILE]: {
+        jwt: typeof raw.jwt === 'string' ? raw.jwt : undefined,
+        api_base: typeof raw.api_base === 'string' ? raw.api_base : undefined,
+        auth_mode: raw.auth_mode === 'dev_portal' ? raw.auth_mode : undefined,
+        refresh_token: typeof raw.refresh_token === 'string' ? raw.refresh_token : undefined,
+        access_expires_at:
+          typeof raw.access_expires_at === 'number' ? raw.access_expires_at : undefined,
+        refresh_expires_at:
+          typeof raw.refresh_expires_at === 'number' ? raw.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof raw.desktop_app_name === 'string' ? raw.desktop_app_name : undefined,
+        desktop_pid: typeof raw.desktop_pid === 'number' ? raw.desktop_pid : undefined,
+      },
+    },
+  };
+}
+
+export function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return normalizeConfig({});
+  }
+
+  return normalizeConfig(JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')));
+}
+
+export function saveConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(normalizeConfig(config), null, 2));
+}
+
+export function getProfile(config, profileName) {
+  const normalized = normalizeConfig(config);
+  return normalized.profiles[profileName] || {};
+}
+
+export function getCurrentProfileName(config, preferredName) {
+  const normalized = normalizeConfig(config);
+  if (preferredName && normalized.profiles[preferredName]) {
+    return preferredName;
+  }
+  return normalized.current_profile || DEFAULT_PROFILE;
+}
+
+export function ensureProfile(config, profileName) {
+  const normalized = normalizeConfig(config);
+  if (!normalized.profiles[profileName]) {
+    normalized.profiles[profileName] = {};
+  }
+  return normalized;
+}
+
+function isLocalApiBase(value) {
+  if (typeof value !== 'string' || !value) {
+    return false;
+  }
+  try {
+    const parsed = new URL(value);
+    return ['http:', 'https:'].includes(parsed.protocol) && LOCAL_API_HOSTS.has(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function getApiBase(config, profileName, override) {
+  if (override) {
+    return override;
+  }
+  const env = process.env.NOTIS_API_BASE;
+  if (env) {
+    return env;
+  }
+  const profile = getProfile(config, profileName);
+  const profileApiBase = profile.api_base;
+  const conductorPort = Number.parseInt(process.env.CONDUCTOR_PORT || '', 10);
+
+  // Conductor assigns dynamic local ports. When a workspace is running under
+  // Conductor, treat saved localhost profile values as stale and transparently
+  // retarget the CLI at the active backend port.
+  if (
+    Number.isInteger(conductorPort) &&
+    conductorPort > 0 &&
+    (!profileApiBase || LOCAL_DEFAULT_API_BASES.has(profileApiBase) || isLocalApiBase(profileApiBase))
+  ) {
+    return `http://localhost:${conductorPort + 1}`;
+  }
+
+  return profileApiBase || DEFAULT_API_BASE;
+}
+
+export function getJwt(config, profileName) {
+  const env = process.env.NOTIS_JWT;
+  if (env) {
+    return env;
+  }
+  const profile = getProfile(config, profileName);
+  return profile.jwt;
+}
+
+export function isAgentMode(globalOptions = {}) {
+  return process.env.NOTIS_AGENT === '1' || Boolean(globalOptions.agentMode);
+}
+
+export function isNonInteractive(globalOptions = {}) {
+  if (process.env.NOTIS_NON_INTERACTIVE === '1') {
+    return true;
+  }
+  if (globalOptions.nonInteractive) {
+    return true;
+  }
+  return isAgentMode(globalOptions);
+}
+
+export function resolveOutputMode(globalOptions = {}) {
+  if (globalOptions.json) {
+    return 'json';
+  }
+  if (globalOptions.output) {
+    return globalOptions.output;
+  }
+  if (process.env.NOTIS_OUTPUT) {
+    return process.env.NOTIS_OUTPUT;
+  }
+  return !process.stdout.isTTY || isAgentMode(globalOptions) ? 'json' : 'table';
+}
+
+export function resolveTimeoutMs(globalOptions = {}) {
+  const raw = globalOptions.timeoutMs || process.env.NOTIS_TIMEOUT_MS;
+  if (!raw) {
+    return 30000;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 30000;
+}
+
+export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true } = {}) {
+  const config = loadConfig();
+  const profileName = getCurrentProfileName(config, globalOptions.profile);
+  const apiBase = getApiBase(config, profileName, globalOptions.apiBase);
+  const jwt = getJwt(config, profileName);
+  const profile = getProfile(config, profileName);
+  const agentMode = isAgentMode(globalOptions);
+  const nonInteractive = isNonInteractive(globalOptions);
+  const outputMode = resolveOutputMode(globalOptions);
+  const timeoutMs = resolveTimeoutMs(globalOptions);
+
+  if (requireAuth && !jwt) {
+    const recovery = getDesktopAuthRecovery({
+      apiBase,
+      desktopAppName: profile.desktop_app_name,
+      desktopPid: profile.desktop_pid,
+    });
+    throw new CliError({
+      code: 'auth_missing',
+      message: `No JWT configured for profile ${profileName}`,
+      exitCode: EXIT_CODES.auth,
+      hints: recovery.hints,
+    });
+  }
+
+  // An explicit NOTIS_JWT is a complete credential override. Use it verbatim
+  // and never replace it with a token later synced by the desktop profile.
+  const usingEnvJwt = Boolean(process.env.NOTIS_JWT);
+  return {
+    config,
+    profileName,
+    apiBase,
+    jwt,
+    credentialSource: usingEnvJwt ? 'env' : 'profile',
+    desktopAppName: usingEnvJwt ? undefined : profile.desktop_app_name,
+    desktopPid: usingEnvJwt ? undefined : profile.desktop_pid,
+    agentMode,
+    nonInteractive,
+    outputMode,
+    timeoutMs,
+  };
+}
+
+export function getJwtExpiration(jwt) {
+  if (typeof jwt !== 'string' || !jwt) {
+    return null;
+  }
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return typeof payload.exp === 'number' ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isJwtExpired(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const expiration = getJwtExpiration(jwt);
+  return expiration !== null && expiration <= nowSeconds;
+}
+
+export function workspacePath(appId) {
+  return join(WORKSPACE_DIR, appId);
+}