@notis_ai/cli 0.2.6 → 0.2.8

package/src/runtime/profiles.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, parse, resolve } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
 import { getDesktopAuthRecovery } from './desktop-auth.js';
 
@@ -9,6 +9,8 @@ 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 WORKTREE_RUNTIME_FILENAME = join('.context', 'notis-runtime.json');
+const WORKTREE_ROUTING_FILENAME = join('.context', 'notis-routing.json');
 const LOCAL_DEFAULT_API_BASES = new Set([
   'http://localhost:3001',
   'http://127.0.0.1:3001',
@@ -77,17 +79,129 @@ export function normalizeConfig(rawConfig = {}) {
   };
 }
 
-export function loadConfig() {
-  if (!existsSync(CONFIG_FILE)) {
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function findUp(filename, startDir = process.cwd()) {
+  let current = resolve(startDir);
+  const root = parse(current).root;
+  while (true) {
+    const candidate = join(current, filename);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    if (current === root) {
+      return null;
+    }
+    current = dirname(current);
+  }
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveWorktreeRuntime(startDir = process.cwd()) {
+  if (
+    process.env.NODE_ENV === 'test' &&
+    process.env.NOTIS_TEST_DISABLE_WORKTREE_ROUTING === '1'
+  ) {
+    return null;
+  }
+  const runtimePath = findUp(WORKTREE_RUNTIME_FILENAME, startDir);
+  const routingPath = findUp(WORKTREE_ROUTING_FILENAME, startDir);
+  const routing = routingPath ? readJsonFile(routingPath) : null;
+
+  if (!runtimePath) {
+    if (routing?.mode === 'local-only') {
+      throw new CliError({
+        code: 'dev_runtime_unavailable',
+        message: `This worktree is local-only, but its dev.sh runtime is not active`,
+        exitCode: EXIT_CODES.network,
+        hints: [
+          { message: 'Start ./dev.sh in this worktree, then retry the command.' },
+          { message: `Routing policy: ${routingPath}` },
+        ],
+      });
+    }
+    return null;
+  }
+
+  const runtime = readJsonFile(runtimePath);
+  const apiBase = typeof runtime?.api_base === 'string' ? runtime.api_base.replace(/\/+$/, '') : '';
+  const configFile = typeof runtime?.config_file === 'string' ? runtime.config_file : '';
+  const pid = Number(runtime?.dev_pid);
+  if (
+    runtime?.mode !== 'local-only' ||
+    !isLocalApiBase(apiBase) ||
+    !configFile ||
+    !processIsAlive(pid)
+  ) {
+    throw new CliError({
+      code: 'dev_runtime_unavailable',
+      message: 'The local-only worktree runtime is stale or invalid',
+      exitCode: EXIT_CODES.network,
+      hints: [
+        { message: 'Restart ./dev.sh in this worktree, then retry the command.' },
+        { message: `Runtime lease: ${runtimePath}` },
+      ],
+    });
+  }
+
+  return {
+    ...runtime,
+    api_base: apiBase,
+    config_file: resolve(dirname(runtimePath), configFile),
+    runtime_path: runtimePath,
+    routing_path: routingPath,
+  };
+}
+
+export function resolveConfigFile(runtime = null) {
+  if (runtime?.config_file) {
+    return runtime.config_file;
+  }
+  const envConfigFile = process.env.NOTIS_CLI_CONFIG_FILE;
+  if (envConfigFile) {
+    return resolve(envConfigFile);
+  }
+  return CONFIG_FILE;
+}
+
+export function loadConfig(runtime = null) {
+  const configFile = resolveConfigFile(runtime);
+  if (!existsSync(configFile)) {
     return normalizeConfig({});
   }
 
-  return normalizeConfig(JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')));
+  // The desktop app rewrites this file while the CLI may be reading it, so a
+  // torn or corrupt read is expected rather than exceptional. Degrade to
+  // "unauthenticated", which surfaces the actionable auth_missing error instead
+  // of a raw SyntaxError from deep inside the runtime.
+  try {
+    return normalizeConfig(JSON.parse(readFileSync(configFile, 'utf-8')));
+  } catch {
+    return normalizeConfig({});
+  }
 }
 
-export function saveConfig(config) {
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_FILE, JSON.stringify(normalizeConfig(config), null, 2));
+export function saveConfig(config, runtime = null) {
+  const configFile = resolveConfigFile(runtime);
+  mkdirSync(dirname(configFile), { recursive: true });
+  writeFileSync(configFile, JSON.stringify(normalizeConfig(config), null, 2), { mode: 0o600 });
 }
 
 export function getProfile(config, profileName) {
@@ -194,23 +308,75 @@ export function resolveTimeoutMs(globalOptions = {}) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 30000;
 }
 
-export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true } = {}) {
-  const config = loadConfig();
+export function parseDebugEntitlementOverride(value = process.env.NOTIS_DEBUG_ENTITLEMENT_OVERRIDE) {
+  if (!value) {
+    return null;
+  }
+  const candidates = [value];
+  try {
+    candidates.push(Buffer.from(value, 'base64url').toString('utf-8'));
+  } catch {
+    // The plain JSON candidate below will provide the actionable error.
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Try the next supported encoding.
+    }
+  }
+  throw new CliError({
+    code: 'debug_entitlement_override_invalid',
+    message: 'NOTIS_DEBUG_ENTITLEMENT_OVERRIDE must be a JSON object or base64url-encoded JSON object.',
+    exitCode: EXIT_CODES.usage,
+  });
+}
+
+export function resolveRuntimeProfile(
+  globalOptions = {},
+  { requireAuth = true, includeDebugEntitlementOverride = true } = {},
+) {
+  const worktreeRuntime = resolveWorktreeRuntime();
+  const config = loadConfig(worktreeRuntime);
   const profileName = getCurrentProfileName(config, globalOptions.profile);
-  const apiBase = getApiBase(config, profileName, globalOptions.apiBase);
-  const jwt = getJwt(config, profileName);
+  const requestedApiBase = globalOptions.apiBase;
+  if (
+    worktreeRuntime &&
+    requestedApiBase &&
+    requestedApiBase.replace(/\/+$/, '') !== worktreeRuntime.api_base
+  ) {
+    throw new CliError({
+      code: 'dev_runtime_route_mismatch',
+      message: `This local-only worktree cannot route to ${requestedApiBase}`,
+      exitCode: EXIT_CODES.usage,
+      hints: [{ message: `Expected local API: ${worktreeRuntime.api_base}` }],
+    });
+  }
+  const apiBase = worktreeRuntime
+    ? worktreeRuntime.api_base
+    : getApiBase(config, profileName, globalOptions.apiBase);
+  const jwt = worktreeRuntime ? getProfile(config, profileName).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);
+  const debugEntitlementOverride = includeDebugEntitlementOverride
+    ? parseDebugEntitlementOverride()
+    : null;
 
   if (requireAuth && !jwt) {
-    const recovery = getDesktopAuthRecovery({
-      apiBase,
-      desktopAppName: profile.desktop_app_name,
-      desktopPid: profile.desktop_pid,
-    });
+    const recovery = getDesktopAuthRecovery(
+      {
+        apiBase,
+        desktopAppName: profile.desktop_app_name,
+        desktopPid: profile.desktop_pid,
+      },
+      { mode: 'missing' },
+    );
     throw new CliError({
       code: 'auth_missing',
       message: `No JWT configured for profile ${profileName}`,
@@ -218,22 +384,38 @@ export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true }
       hints: recovery.hints,
     });
   }
+  if (
+    worktreeRuntime?.expected_user_id &&
+    getJwtSubject(jwt) !== worktreeRuntime.expected_user_id
+  ) {
+    throw new CliError({
+      code: 'dev_runtime_identity_mismatch',
+      message: 'The scoped dev credential does not belong to this worktree test user',
+      exitCode: EXIT_CODES.auth,
+      hints: [
+        { message: 'Restart ./dev.sh to restore the approved worktree identity.' },
+        { message: `Expected user: ${worktreeRuntime.expected_user_id}` },
+      ],
+    });
+  }
 
   // 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);
+  const usingEnvJwt = !worktreeRuntime && Boolean(process.env.NOTIS_JWT);
   return {
     config,
     profileName,
     apiBase,
     jwt,
-    credentialSource: usingEnvJwt ? 'env' : 'profile',
+    credentialSource: worktreeRuntime ? 'worktree' : usingEnvJwt ? 'env' : 'profile',
     desktopAppName: usingEnvJwt ? undefined : profile.desktop_app_name,
     desktopPid: usingEnvJwt ? undefined : profile.desktop_pid,
     agentMode,
     nonInteractive,
     outputMode,
     timeoutMs,
+    debugEntitlementOverride,
+    worktreeRuntime,
   };
 }
 
@@ -251,6 +433,20 @@ export function getJwtExpiration(jwt) {
   }
 }
 
+export function getJwtSubject(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.sub === 'string' && payload.sub ? payload.sub : null;
+  } catch {
+    return null;
+  }
+}
+
 export function isJwtExpired(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
   const expiration = getJwtExpiration(jwt);
   return expiration !== null && expiration <= nowSeconds;

package/src/runtime/telemetry.js

@@ -0,0 +1,92 @@
+const ERROR_CATEGORIES = new Map([
+  [2, 'usage'],
+  [3, 'auth'],
+  [4, 'network'],
+  [5, 'conflict'],
+  [6, 'backend'],
+  [7, 'unexpected'],
+  [8, 'payment'],
+]);
+
+export function cliDurationBucket(durationMs) {
+  if (durationMs < 1_000) return 'under_1s';
+  if (durationMs < 5_000) return '1s_to_5s';
+  if (durationMs < 30_000) return '5s_to_30s';
+  return 'over_30s';
+}
+
+export function cliBackendKind(spec) {
+  const value = String(spec?.backend_call?.type || '').toLowerCase();
+  if (value === 'tool') return 'tool';
+  if (value === 'http') return 'http';
+  if (value === 'local') return 'local';
+  if (value.includes('health')) return 'health';
+  if (value.includes('local')) return 'local';
+  return 'other';
+}
+
+export function buildCliTelemetryPayload({
+  spec,
+  runtime,
+  result,
+  durationMs,
+  error,
+}) {
+  return {
+    command_id: spec.command_path.join('.'),
+    backend_kind: cliBackendKind(spec),
+    result,
+    error_category: result === 'failed'
+      ? (ERROR_CATEGORIES.get(Number(error?.exitCode)) || 'unexpected')
+      : 'none',
+    duration_bucket: cliDurationBucket(durationMs),
+    cli_version: runtime.cliVersion,
+    agent_mode: Boolean(runtime.agentMode),
+  };
+}
+
+export async function reportCliCommand({
+  spec,
+  runtime,
+  result,
+  durationMs,
+  error = null,
+  fetchImpl = globalThis.fetch,
+}) {
+  // Backend tool calls emit authoritative surface/tool telemetry server-side.
+  // This client event exists only for local commands that otherwise leave no
+  // observable runtime boundary.
+  if (
+    cliBackendKind(spec) !== 'local'
+    || !runtime?.jwt
+    || !runtime?.apiBase
+    || typeof fetchImpl !== 'function'
+  ) {
+    return false;
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1_500);
+  try {
+    const response = await fetchImpl(`${runtime.apiBase}/cli_telemetry`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${runtime.jwt}`,
+        'Content-Type': 'application/json',
+        'X-Notis-CLI-Version': runtime.cliVersion,
+      },
+      body: JSON.stringify(buildCliTelemetryPayload({
+        spec,
+        runtime,
+        result,
+        durationMs,
+        error,
+      })),
+      signal: controller.signal,
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/runtime/transport.js

@@ -4,6 +4,7 @@ import { CliError, EXIT_CODES } from './errors.js';
 import {
   DEFAULT_PROFILE,
   getProfile,
+  getJwtSubject,
   isJwtExpired,
   loadConfig,
 } from './profiles.js';
@@ -122,6 +123,18 @@ function normalizeBackendError(status, payload, runtime) {
     });
   }
 
+  if (status === 402) {
+    // Distinct from auth on purpose: an agent that sees an auth exit code will
+    // loop trying to re-authenticate, when the actual fix is to add credit.
+    return new CliError({
+      code: 'payment_required',
+      message,
+      exitCode: EXIT_CODES.payment,
+      details: payload || {},
+      hints: payload?.hints || [],
+    });
+  }
+
   if (status >= 400 && status < 500) {
     return new CliError({
       code: 'usage_error',
@@ -149,7 +162,7 @@ function reloadJwtFromConfig(runtime) {
   const profileName = runtime.profileName || DEFAULT_PROFILE;
   let profile;
   try {
-    profile = getProfile(loadConfig(), profileName);
+    profile = getProfile(loadConfig(runtime.worktreeRuntime), profileName);
   } catch {
     return false;
   }
@@ -157,6 +170,18 @@ function reloadJwtFromConfig(runtime) {
   if (!nextJwt || nextJwt === runtime.jwt) {
     return false;
   }
+  const expectedUserId = runtime.worktreeRuntime?.expected_user_id;
+  if (expectedUserId && getJwtSubject(nextJwt) !== expectedUserId) {
+    throw new CliError({
+      code: 'dev_runtime_identity_mismatch',
+      message: 'The refreshed scoped dev credential does not belong to this worktree test user',
+      exitCode: EXIT_CODES.auth,
+      hints: [
+        { message: 'Restart ./dev.sh to restore the approved worktree identity.' },
+        { message: `Expected user: ${expectedUserId}` },
+      ],
+    });
+  }
   runtime.jwt = nextJwt;
   runtime.desktopAppName = profile.desktop_app_name;
   runtime.desktopPid = profile.desktop_pid;
@@ -318,6 +343,9 @@ export async function callTool({
       cwd: process.cwd(),
       agent_mode: runtime.agentMode,
       cli_version: runtime.cliVersion,
+      ...(runtime.debugEntitlementOverride
+        ? { debug_entitlement_override: runtime.debugEntitlementOverride }
+        : {}),
     },
   };
 

package/template/.harness/index.html.tmpl

@@ -107,6 +107,33 @@
     const apiBase = {{API_BASE}};
     const jwt = {{JWT}};
     const fixtures = {{FIXTURES}};
+
+    /**
+     * Resolves the canned response for one tool call.
+     *
+     * A plain `"TOOL_NAME"` key answers every call to that tool. An app that
+     * reaches several databases through a single tool needs to vary the
+     * payload per call, so a key may also be scoped to one argument with
+     * `"TOOL_NAME#arg=value"` — for example
+     * `"LOCAL_NOTIS_DATABASE_QUERY#database_slug=notes"`. Scoped keys are
+     * checked first; the unscoped key stays the fallback.
+     */
+    function lookupToolFixture(name, args) {
+      const tools = fixtures && fixtures.tools;
+      if (!tools) return undefined;
+      for (const key of Object.keys(tools)) {
+        const sep = key.indexOf('#');
+        if (sep === -1 || key.slice(0, sep) !== name) continue;
+        const scope = key.slice(sep + 1);
+        const eq = scope.indexOf('=');
+        if (eq === -1) continue;
+        if (String(args[scope.slice(0, eq)]) === scope.slice(eq + 1)) {
+          return tools[key];
+        }
+      }
+      return Object.prototype.hasOwnProperty.call(tools, name) ? tools[name] : undefined;
+    }
+
     const status = document.getElementById('harness-status');
     const setStatus = (msg, color = '#0f0') => {
       status.textContent = `harness: ${msg}`;
@@ -197,8 +224,9 @@
         },
         callTool: async (name, args) => {
           record('callTool', { name, arguments: args || {} });
-          if (fixtures && fixtures.tools && Object.prototype.hasOwnProperty.call(fixtures.tools, name)) {
-            return structuredClone(fixtures.tools[name]);
+          const fixture = lookupToolFixture(name, args || {});
+          if (fixture !== undefined) {
+            return structuredClone(fixture);
           }
           return { ok: true, result: null };
         },

package/template/packages/sdk/src/config.ts

@@ -62,6 +62,20 @@ export const NOTIS_APP_CATEGORIES = [
 
 export type NotisAppCategory = typeof NOTIS_APP_CATEGORIES[number];
 
+export interface NotisAppDatabaseConfig {
+  /** Database slug, as declared by the app. */
+  slug: string;
+  /**
+   * Ship this database's rows to everyone who installs the app.
+   *
+   * Off by default: declaring a database publishes its STRUCTURE, never its
+   * content. Turn it on only for starter content that every installer should
+   * receive - a default folder tree, a set of templates - and never for a
+   * database that accumulates the author's own data.
+   */
+  seedDocuments?: boolean;
+}
+
 export interface NotisAppAuthor {
   name: string;
   handle?: string;
@@ -106,6 +120,19 @@ export const NOTIS_APP_ACCENTS = [
 
 export type NotisAppAccent = typeof NOTIS_APP_ACCENTS[number];
 
+export interface NotisAppCapabilities {
+  /**
+   * Read every database in the workspace, not only the ones this app declares
+   * in `databases` or created itself.
+   *
+   * An app runtime is otherwise sandboxed to its own databases, so a catalog or
+   * explorer app sees an empty list without this. `'read'` is the only accepted
+   * value and it never grants writes: `LOCAL_NOTIS_DATABASE_UPSERT_*` stays
+   * bound to the app's own databases.
+   */
+  workspaceDatabases?: 'read';
+}
+
 export interface NotisAppConfig {
   /** URL-safe app slug. Existing apps may still use a display name here. */
   name: string;
@@ -128,7 +155,17 @@ export interface NotisAppConfig {
   /** @deprecated Add release entries to the root CHANGELOG.md instead. */
   versionNotes?: string;
   screenshots?: NotisAppScreenshotConfig[];
-  databases?: string[];
+  /**
+   * Databases this app owns. A bare string publishes structure only; use the
+   * object form to opt a database into shipping its rows to installers.
+   */
+  databases?: (string | NotisAppDatabaseConfig)[];
+  /**
+   * Extra permissions the app asks for at install time. Everything here widens
+   * what the app can reach beyond its own data, so each one is surfaced to the
+   * user before they install.
+   */
+  capabilities?: NotisAppCapabilities;
   routes?: NotisRouteConfig[];
   tools?: string[];
   skills?: NotisAppSkillConfig[];