@papercraneai/cli 1.8.3 → 1.9.0-beta.0

package/bin/papercrane.js

@@ -13,6 +13,65 @@ import { validateApiKey } from '../lib/cloud-client.js';
 import { listFunctions, getFunction, runFunction, formatDescribe, formatDescribeRoot, formatFlat, formatResult, formatUnconnected } from '../lib/function-client.js';
 import { listWorkspaces, resolveWorkspaceId, getLocalWorkspacePath, pullWorkspace, pushWorkspace } from '../lib/environment-client.js';
 
+/**
+ * Resolve the current workspace directory from ~/.papercrane/current symlink.
+ * Returns null if no workspace is set up (does not exit).
+ */
+async function resolveWorkspaceDir() {
+  const currentLink = path.join(os.homedir(), '.papercrane', 'current');
+  try {
+    await fs.readlink(currentLink);
+    return await fs.realpath(currentLink);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load .env from workspace dir using dotenv.
+ */
+async function loadDotenv(workspaceDir) {
+  try {
+    const dotenv = await import('dotenv');
+    dotenv.config({ path: path.join(workspaceDir, '.env') });
+  } catch {
+    // dotenv not available — env vars from shell still work
+  }
+}
+
+/**
+ * Recursively collect all endpoint paths from a Node tree.
+ */
+function collectPaths(node, prefix, paths) {
+  if (!node.next || typeof node.next === 'function') {
+    // Leaf or dynamic — add the node itself
+    paths.push({ path: prefix, isDynamic: typeof node.next === 'function' });
+    return;
+  }
+  for (const [key, child] of Object.entries(node.next)) {
+    const isDynamic = key.startsWith('$');
+    const childPath = `${prefix}.${key}`;
+    if (!child.next) {
+      paths.push({ path: childPath, isDynamic });
+    } else {
+      collectPaths(child, childPath, paths);
+    }
+  }
+}
+
+/**
+ * Check if the workspace has any local handlers.
+ */
+async function hasLocalHandlers(workspaceDir) {
+  if (!workspaceDir) return false;
+  try {
+    const { loadHandlers } = await import('../lib/handler-loader.js');
+    return loadHandlers(workspaceDir).size > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check login and workspace setup. Exits with helpful message if not ready.
  */
@@ -486,8 +545,56 @@ program
   .description('Describe a module or endpoint. Use --flat to recursively list all endpoint paths')
   .option('-i, --instance <name>', 'Integration instance name', 'Default')
   .option('-f, --flat', 'List all endpoint paths under this module')
-  .action(async (path, options) => {
+  .action(async (fnPath, options) => {
     try {
+      // Local handler path
+      if (fnPath.startsWith('local.')) {
+        const workspaceDir = await resolveWorkspaceDir();
+        if (!workspaceDir) {
+          console.error(chalk.red('No workspace set up. Run: papercrane scaffold'));
+          process.exit(1);
+        }
+
+        await loadDotenv(workspaceDir);
+        const { loadHandler } = await import('../lib/handler-loader.js');
+
+        const segments = fnPath.slice('local.'.length).split('.');
+        const handlerName = segments[0];
+        const methodPath = segments.slice(1);
+
+        const node = loadHandler(workspaceDir, handlerName);
+        if (!node) {
+          console.error(chalk.red(`Local handler not found: ${handlerName}`));
+          process.exit(1);
+        }
+
+        if (options.flat) {
+          const paths = [];
+          collectPaths(node, `local.${handlerName}`, paths);
+          if (paths.length > 0) {
+            console.log();
+            for (const p of paths) {
+              const display = p.isDynamic ? chalk.yellow(p.path) : chalk.green(p.path);
+              console.log(`  ${display}`);
+            }
+            console.log();
+          } else {
+            console.log(chalk.dim('\nNo endpoints found.\n'));
+          }
+        } else {
+          const { resolve } = await import('../lib/resolver.js');
+          const ctx = { credentials: {}, pathParams: {}, cleanup: [] };
+          const result = await resolve(node, methodPath, ctx, {}, 'GET');
+
+          if (!result.ok) {
+            console.error(chalk.red('Error:'), result.error);
+            process.exit(1);
+          }
+          formatDescribe(result.info, fnPath);
+        }
+        return;
+      }
+
       const loggedIn = await isLoggedIn();
       if (!loggedIn) {
         console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
@@ -495,11 +602,11 @@ program
       }
 
       if (options.flat) {
-        const data = await listFunctions(path, options.instance, true);
+        const data = await listFunctions(fnPath, options.instance, true);
         formatFlat(data);
       } else {
-        const data = await getFunction(path, options.instance);
-        formatDescribe(data, path);
+        const data = await getFunction(fnPath, options.instance);
+        formatDescribe(data, fnPath);
       }
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
@@ -513,14 +620,8 @@ program
   .option('-i, --instance <name>', 'Integration instance name', 'Default')
   .option('-p, --params <json>', 'Parameters as JSON string (alternative to positional)')
   .option('--raw', 'Output raw JSON without formatting')
-  .action(async (path, paramsArg, options) => {
+  .action(async (fnPath, paramsArg, options) => {
     try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
-      }
-
       // Parse params - positional arg takes precedence, fall back to --params
       let params = {};
       const paramsJson = paramsArg || options.params;
@@ -534,7 +635,61 @@ program
         }
       }
 
-      const data = await runFunction(path, params, options.instance);
+      // Local handler path — execute directly via jiti, no server needed
+      if (fnPath.startsWith('local.')) {
+        const workspaceDir = await resolveWorkspaceDir();
+        if (!workspaceDir) {
+          console.error(chalk.red('No workspace set up. Run: papercrane scaffold'));
+          process.exit(1);
+        }
+
+        await loadDotenv(workspaceDir);
+        const { resolve } = await import('../lib/resolver.js');
+        const { loadHandler } = await import('../lib/handler-loader.js');
+
+        const segments = fnPath.slice('local.'.length).split('.');
+        const handlerName = segments[0];
+        const methodPath = segments.slice(1);
+
+        const node = loadHandler(workspaceDir, handlerName);
+        if (!node) {
+          console.error(chalk.red(`Local handler not found: ${handlerName}`));
+          console.error(chalk.dim(`  Expected file: app/_handlers/${handlerName}.ts`));
+          process.exit(1);
+        }
+
+        const ctx = { credentials: {}, pathParams: {}, cleanup: [] };
+        const result = await resolve(node, methodPath, ctx, params, 'POST');
+
+        for (const fn of ctx.cleanup || []) {
+          try { await fn(); } catch {}
+        }
+
+        if (!result.ok) {
+          if (result.schema) {
+            console.error(chalk.yellow('\nExpected parameters:'));
+            for (const [name, info] of Object.entries(result.schema)) {
+              const req = info.required ? chalk.red('required') : chalk.dim('optional');
+              console.error(`  ${chalk.cyan(name)} (${info.type}) ${req}`);
+              if (info.description) console.error(`    ${chalk.dim(info.description)}`);
+            }
+            console.error('');
+          }
+          console.error(chalk.red('Error:'), result.error);
+          process.exit(1);
+        }
+
+        formatResult({ result: result.result });
+        return;
+      }
+
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const data = await runFunction(fnPath, params, options.instance);
       formatResult(data);
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
@@ -784,6 +939,140 @@ Use these Tailwind classes for theme-aware colors:
     console.log();
   });
 
+// ============================================================================
+// LOCAL INTEGRATION GUIDE
+// ============================================================================
+
+program
+  .command('local-integration-guide')
+  .description('Show how to build local API integrations that dashboards can call')
+  .action(async () => {
+    console.log(`
+LOCAL INTEGRATION GUIDE
+
+Connect any API to Papercrane dashboards via handler files.
+
+WORKFLOW
+  1. Research the target API: auth mechanism, base URL, endpoints, exact field names
+  2. Create app/_handlers/<name>.ts exporting a Node tree (see format below)
+  3. Add credentials to .env at workspace root
+  4. Test: papercrane call local.<name>.<endpoint> '{...}'
+  5. Iterate: fix field names, URLs, auth until calls return real data
+  6. Call from dashboards: authFetch('local.<name>.<endpoint>', params)
+
+FILES
+  ~/.papercrane/current/
+  ├── .env                   # Credentials (not synced by push/pull)
+  └── app/_handlers/
+      └── <name>.ts          # → local.<name>.* endpoints
+
+AVAILABLE WITHOUT npm install
+  - zod (from @papercraneai/cli)
+  - fetch (Node built-in)
+  - crypto (Node built-in)
+  If you need a vendor SDK, the user must npm install it in the workspace.
+
+HANDLER FORMAT
+  File must export a Node object (named or default export).
+  Filename becomes the handler name: my-api.ts → local.my-api.*
+
+  import { z } from 'zod'
+
+  export const myApi = {
+    description: 'Short description of this integration',
+
+    // Optional root handler — runs first on every call
+    handler: async (ctx, params) => {
+      const token = process.env.MY_API_TOKEN
+      if (!token) throw new Error('Set MY_API_TOKEN in .env')
+      ctx.baseUrl = 'https://api.example.com'
+      ctx.headers = { Authorization: 'Bearer ' + token }
+    },
+
+    next: {
+      // Leaf node (callable endpoint): local.my-api.list
+      list: {
+        description: 'List items',
+        params: z.object({
+          limit: z.number().optional().describe('Max results'),
+        }),
+        handler: async (ctx, params) => {
+          const res = await fetch(ctx.baseUrl + '/items?' + new URLSearchParams(params), {
+            headers: ctx.headers,
+          })
+          if (!res.ok) throw new Error('API error: ' + res.status)
+          return res.json()
+        },
+      },
+
+      // Branch node (grouping): local.my-api.accounts.*
+      accounts: {
+        description: 'Account operations',
+        next: {
+          list: {
+            description: 'List accounts',
+            handler: async (ctx) => {
+              const res = await fetch(ctx.baseUrl + '/accounts', { headers: ctx.headers })
+              return res.json()
+            },
+          },
+        },
+      },
+    },
+  }
+
+NODE TYPES
+  Leaf   — { description, params?, handler } — callable endpoint, no next
+  Branch — { description, handler?, next }   — groups children, handler sets up ctx
+  Dynamic — key starts with $                — captures path segment
+             $id → ctx.pathParams.id
+             local.my-api.accounts.123.get → ctx.pathParams.id = '123'
+
+CONTEXT (ctx)
+  ctx.pathParams   Values captured by $ segments
+  ctx.cleanup      Array of async teardown functions (push to close connections)
+  ctx[anything]    Add any property — common: ctx.client, ctx.headers, ctx.baseUrl
+
+PARAMS
+  Use z.object({...}) with .describe() on each field.
+  Validated before handler runs. Shows in "papercrane describe" output.
+
+CREDENTIALS
+  Store in .env at workspace root. Read via process.env.KEY_NAME.
+  .env is loaded automatically by both dev server and CLI.
+  .env is NOT synced by push/pull — credentials stay local.
+
+AUTH PATTERNS
+  Bearer token:
+    headers: { Authorization: 'Bearer ' + process.env.TOKEN }
+
+  HMAC signing:
+    import crypto from 'crypto'
+    const sig = crypto.createHmac('sha1', key).update(body).digest('base64')
+    headers: { 'X-Signature': sig }
+
+  API key in query:
+    url + '?api_key=' + process.env.API_KEY
+
+ERRORS
+  Just throw. Message is returned to caller, no stack trace exposed.
+
+TESTING
+  papercrane describe local.<name>             # see endpoints
+  papercrane describe local.<name> --flat      # all paths
+  papercrane describe local.<name>.<endpoint>  # params + example
+  papercrane call local.<name>.<endpoint> '{...}'
+
+IMPORTANT
+  - Read the vendor's actual API docs for exact field names, URL paths, and
+    auth details before writing code. Getting field names wrong (e.g. "message"
+    vs "messagetext", "url" vs "profile") is the #1 source of errors.
+  - Test with papercrane call after writing each endpoint. Don't write the
+    whole handler tree before testing — iterate one endpoint at a time.
+  - Ask the user for credentials. They go in .env, not in the handler file.
+`);
+  });
+
 // ============================================================================
 // WORKSPACE COMMANDS
 // ============================================================================
@@ -1074,6 +1363,7 @@ program.action(async (_, cmd) => {
     console.error('  papercrane call <path> [json]   Call an endpoint');
     console.error('  papercrane add                  Add a new integration');
     console.error('  papercrane dashboard-guide      Show how to build dashboards');
+    console.error('  papercrane local-integration-guide  Show how to build local API integrations');
     console.error('  papercrane scaffold             Pre-scaffold workspace (no login required)');
     console.error('  papercrane workspaces list      List workspaces');
     console.error('  papercrane workspaces use <id>  Set default workspace');
@@ -1086,14 +1376,45 @@ program.action(async (_, cmd) => {
   }
 
   try {
+    // Show cloud modules if logged in
     const loggedIn = await isLoggedIn();
-    if (!loggedIn) {
+    if (loggedIn) {
+      try {
+        const data = await listFunctions('', 'Default');
+        formatDescribeRoot(data);
+      } catch (error) {
+        console.error(chalk.red('Error loading cloud modules:'), error.message);
+      }
+    }
+
+    // Show local handlers if workspace has any
+    const workspaceDir = await resolveWorkspaceDir();
+    if (workspaceDir) {
+      try {
+        const { loadHandlers } = await import('../lib/handler-loader.js');
+        const handlers = loadHandlers(workspaceDir);
+        if (handlers.size > 0) {
+          console.log(chalk.bold('Local modules:\n'));
+          for (const [name, node] of handlers) {
+            const displayPath = node.next ? `local.${name}.*` : `local.${name}`;
+            console.log(`  ${chalk.magenta(displayPath)}`);
+            if (node.description) {
+              console.log(`    ${chalk.dim(node.description)}`);
+            }
+          }
+          console.log();
+          console.log(chalk.dim('Run "papercrane describe local.<name>" to see endpoints.'));
+          console.log();
+        }
+      } catch {
+        // Non-fatal — local handlers are optional
+      }
+    }
+
+    if (!loggedIn && (!workspaceDir || !(await hasLocalHandlers(workspaceDir)))) {
       console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
       process.exit(1);
     }
-
-    const data = await listFunctions('', 'Default');
-    formatDescribeRoot(data);
   } catch (error) {
     console.error(chalk.red('Error:'), error.message);
     process.exit(1);

package/lib/dev-server.js

@@ -391,6 +391,103 @@ export async function startDevServer(workspaceDir, port) {
   // Serve theme CSS from CLI package
   server.use('/themes', express.static(path.join(cliRoot, 'public', 'themes')));
 
+  // ---- Local handler routes ----
+  server.use(express.json());
+
+  // POST /function/local.* — execute a local handler
+  server.post('/function/local.:rest(*)', async (req, res) => {
+    try {
+      const { resolve } = await import('./resolver.js');
+      const { loadHandler, clearHandlerCache } = await import('./handler-loader.js');
+
+      const segments = req.params.rest.split('.');
+      const handlerName = segments[0];
+      const methodPath = segments.slice(1);
+
+      // Clear cache on each request during dev for hot-reload
+      clearHandlerCache(projectDir);
+
+      const node = loadHandler(projectDir, handlerName);
+      if (!node) {
+        return res.status(404).json({ error: `Local handler not found: ${handlerName}` });
+      }
+
+      const ctx = { credentials: {}, pathParams: {}, cleanup: [] };
+      const params = req.body?.params || req.body || {};
+
+      const result = await resolve(node, methodPath, ctx, params, 'POST');
+
+      // Run cleanup functions
+      for (const fn of ctx.cleanup || []) {
+        try { await fn(); } catch {}
+      }
+
+      if (!result.ok) {
+        const response = { error: result.error };
+        if (result.schema) response.schema = result.schema;
+        return res.status(result.status || 500).json(response);
+      }
+
+      return res.json({ result: result.result });
+    } catch (err) {
+      return res.status(500).json({ error: err.message });
+    }
+  });
+
+  // GET /function/local.* — describe a local handler
+  server.get('/function/local.:rest(*)', async (req, res) => {
+    try {
+      const { resolve } = await import('./resolver.js');
+      const { loadHandler, clearHandlerCache } = await import('./handler-loader.js');
+
+      const segments = req.params.rest.split('.');
+      const handlerName = segments[0];
+      const methodPath = segments.slice(1);
+
+      clearHandlerCache(projectDir);
+
+      const node = loadHandler(projectDir, handlerName);
+      if (!node) {
+        return res.status(404).json({ error: `Local handler not found: ${handlerName}` });
+      }
+
+      const ctx = { credentials: {}, pathParams: {}, cleanup: [] };
+      const result = await resolve(node, methodPath, ctx, {}, 'GET');
+
+      for (const fn of ctx.cleanup || []) {
+        try { await fn(); } catch {}
+      }
+
+      if (!result.ok) {
+        return res.status(result.status || 500).json({ error: result.error });
+      }
+
+      return res.json(result.info);
+    } catch (err) {
+      return res.status(500).json({ error: err.message });
+    }
+  });
+
+  // GET /function/local — list all local handlers
+  server.get('/function/local', async (req, res) => {
+    try {
+      const { loadHandlers, clearHandlerCache } = await import('./handler-loader.js');
+      clearHandlerCache(projectDir);
+      const handlers = loadHandlers(projectDir);
+      const items = [];
+      for (const [name, node] of handlers) {
+        items.push({
+          path: `local.${name}`,
+          description: node.description,
+          isGroup: !!node.next,
+        });
+      }
+      return res.json({ items });
+    } catch (err) {
+      return res.status(500).json({ error: err.message });
+    }
+  });
+
   // Everything else -> Next.js
   server.all('/{*path}', (req, res) => handle(req, res));
 

package/lib/handler-loader.js

@@ -0,0 +1,123 @@
+/**
+ * Handler loader — scans app/_handlers/*.ts in a workspace dir,
+ * loads each via jiti, and returns handler Node trees.
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+// Cache: workspaceDir → Map<name, Node>
+const cache = new Map();
+
+/**
+ * Create a jiti instance rooted at the workspace dir so handler imports
+ * resolve from the workspace's node_modules.
+ */
+function createJiti(workspaceDir) {
+  const { createJiti: createJitiFn } = require('jiti');
+  return createJitiFn(path.join(workspaceDir, '_virtual_entry.ts'), {
+    interopDefault: true,
+    moduleCache: false,
+  });
+}
+
+/**
+ * Load all handlers from app/_handlers/*.ts in the given workspace dir.
+ * @param {string} workspaceDir - Absolute path to the workspace root
+ * @param {Object} [options]
+ * @param {boolean} [options.noCache] - Skip cache
+ * @returns {Map<string, Object>} Map of handler name → Node tree
+ */
+export function loadHandlers(workspaceDir, { noCache = false } = {}) {
+  if (!noCache && cache.has(workspaceDir)) {
+    return cache.get(workspaceDir);
+  }
+
+  const handlersDir = path.join(workspaceDir, 'app', '_handlers');
+  const handlers = new Map();
+
+  if (!fs.existsSync(handlersDir)) {
+    cache.set(workspaceDir, handlers);
+    return handlers;
+  }
+
+  const files = fs.readdirSync(handlersDir).filter(f => f.endsWith('.ts') || f.endsWith('.js'));
+  const jiti = createJiti(workspaceDir);
+
+  for (const file of files) {
+    const name = path.basename(file, path.extname(file));
+    try {
+      const mod = jiti(path.join(handlersDir, file));
+      const node = extractNode(mod);
+      if (node) {
+        handlers.set(name, node);
+      }
+    } catch (err) {
+      // Log but don't fail — other handlers may still work
+      console.error(`Warning: Failed to load handler "${name}": ${err.message}`);
+    }
+  }
+
+  cache.set(workspaceDir, handlers);
+  return handlers;
+}
+
+/**
+ * Load a single handler by name.
+ * @param {string} workspaceDir - Absolute path to the workspace root
+ * @param {string} name - Handler name (filename without extension)
+ * @returns {Object|null} Node tree or null if not found
+ */
+export function loadHandler(workspaceDir, name) {
+  const handlersDir = path.join(workspaceDir, 'app', '_handlers');
+
+  // Try .ts first, then .js
+  for (const ext of ['.ts', '.js']) {
+    const filePath = path.join(handlersDir, name + ext);
+    if (fs.existsSync(filePath)) {
+      const jiti = createJiti(workspaceDir);
+      const mod = jiti(filePath);
+      return extractNode(mod);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Clear the handler cache (useful when files change).
+ * @param {string} [workspaceDir] - Clear for specific dir, or all if omitted
+ */
+export function clearHandlerCache(workspaceDir) {
+  if (workspaceDir) {
+    cache.delete(workspaceDir);
+  } else {
+    cache.clear();
+  }
+}
+
+/**
+ * Extract the first Node-shaped export from a module.
+ * A Node has at minimum a `description` string.
+ */
+function extractNode(mod) {
+  if (!mod || typeof mod !== 'object') return null;
+
+  // Check if the module itself is a Node (default export)
+  if (typeof mod.description === 'string' && (mod.handler || mod.next)) {
+    return mod;
+  }
+
+  // Check named exports
+  for (const key of Object.keys(mod)) {
+    const val = mod[key];
+    if (val && typeof val === 'object' && typeof val.description === 'string' && (val.handler || val.next)) {
+      return val;
+    }
+  }
+
+  return null;
+}

package/lib/resolver.js

@@ -0,0 +1,316 @@
+/**
+ * Local resolver — adapted from apps/papercrane/src/server/lib/sdk-handlers/resolver.ts
+ * for CLI/dev-server use. No Express dependencies, no streaming.
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+/**
+ * Convert Zod schema to JSON Schema.
+ * Supports both zod v4 (native toJSONSchema) and v3 (zod-to-json-schema).
+ */
+function zodToJsonSchema(schema) {
+  try {
+    // Zod v4 has native toJSONSchema
+    if (typeof schema.toJSONSchema === 'function') {
+      return schema.toJSONSchema();
+    }
+    // Fallback to zod-to-json-schema for v3
+    const { zodToJsonSchema: convert } = require('zod-to-json-schema');
+    return convert(schema);
+  } catch {
+    return { type: 'object' };
+  }
+}
+
+/**
+ * Check if next is a dynamic function
+ */
+function isDynamicNext(next) {
+  return typeof next === 'function';
+}
+
+/**
+ * Resolve dynamic next to static Record<string, Node>.
+ */
+async function resolveNext(node, ctx) {
+  if (!node.next) return undefined;
+
+  if (isDynamicNext(node.next)) {
+    if (node.handler) {
+      await node.handler(ctx, {});
+    }
+    return await node.next(ctx);
+  }
+
+  return node.next;
+}
+
+/**
+ * Find the next node given a path segment.
+ */
+function findNext(next, segment) {
+  if (!next) return null;
+
+  if (segment in next) {
+    return { node: next[segment] };
+  }
+
+  const wildcardKey = Object.keys(next).find((k) => k.startsWith('$'));
+  if (wildcardKey) {
+    const paramName = wildcardKey.slice(1);
+    return { node: next[wildcardKey], paramName };
+  }
+
+  return null;
+}
+
+/**
+ * Get a human-readable type name from a Zod schema field.
+ * Supports both zod v3 (_def.typeName) and v4 (.type property).
+ */
+function getZodTypeName(field) {
+  // Zod v4: field.type is a string like 'string', 'number', etc.
+  if (typeof field.type === 'string') {
+    const t = field.type;
+    // For optional wrapper in v4, unwrap
+    if (t === 'optional' && field.unwrap) {
+      return getZodTypeName(field.unwrap());
+    }
+    if (t === 'nullable' && field.unwrap) {
+      return `${getZodTypeName(field.unwrap())} | null`;
+    }
+    if (t === 'array' && field.def?.element) {
+      return `${getZodTypeName(field.def.element)}[]`;
+    }
+    if (t === 'enum' && field.def?.entries) {
+      return Object.keys(field.def.entries).map((v) => `"${v}"`).join(' | ');
+    }
+    if (t === 'union' && field.def?.options) {
+      return field.def.options.map((o) => getZodTypeName(o)).join(' | ');
+    }
+    return t;
+  }
+
+  // Zod v3 fallback
+  const typeName = field._def?.typeName;
+  if (!typeName) return 'unknown';
+  if (typeName === 'ZodOptional' || typeName === 'ZodDefault') {
+    return getZodTypeName(field._def.innerType);
+  }
+  if (typeName === 'ZodNullable') {
+    return `${getZodTypeName(field._def.innerType)} | null`;
+  }
+  if (typeName === 'ZodArray') {
+    return `${getZodTypeName(field._def.type)}[]`;
+  }
+  if (typeName === 'ZodEnum') {
+    return field._def.values.map((v) => `"${v}"`).join(' | ');
+  }
+  if (typeName === 'ZodUnion') {
+    return field._def.options.map((o) => getZodTypeName(o)).join(' | ');
+  }
+  const map = {
+    ZodString: 'string',
+    ZodNumber: 'number',
+    ZodBoolean: 'boolean',
+    ZodObject: 'object',
+    ZodRecord: 'Record<string, any>',
+  };
+  return map[typeName] || typeName.replace('Zod', '').toLowerCase();
+}
+
+/**
+ * Convert a Zod schema to a simple field-level schema description.
+ * Supports both zod v3 (_def.typeName) and v4 (.shape property).
+ */
+function zodToSimpleSchema(schema) {
+  try {
+    // Zod v4: schema.shape is a plain object
+    const shape = typeof schema.shape === 'object' && schema.shape
+      ? schema.shape
+      // Zod v3: schema._def.shape() is a function
+      : (schema._def?.typeName === 'ZodObject' ? schema._def.shape() : null);
+
+    if (!shape) return undefined;
+
+    const result = {};
+    for (const [key, value] of Object.entries(shape)) {
+      const field = value;
+      const entry = {
+        type: getZodTypeName(field),
+        required: typeof field.isOptional === 'function' ? !field.isOptional() : true,
+      };
+      // Zod v4: description is in field.description or field._zod?.def?.description
+      const desc = field.description || field._zod?.def?.description;
+      if (desc) {
+        entry.description = desc;
+      }
+      result[key] = entry;
+    }
+    return result;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Format Zod validation errors into a readable string.
+ * Supports both zod v3 (.errors) and v4 (.issues).
+ */
+function formatZodError(error) {
+  const items = error.errors || error.issues;
+  if (items && Array.isArray(items)) {
+    return items
+      .map((e) => {
+        const path = e.path && e.path.length > 0 ? `${e.path.join('.')}: ` : '';
+        return `${path}${e.message}`;
+      })
+      .join('; ');
+  }
+  return error.message || 'Validation failed';
+}
+
+/**
+ * Build node info for GET requests
+ */
+function buildNodeInfo(node, inheritedScopes, resolvedNext) {
+  const resolvedScopes = node.scopes || inheritedScopes;
+
+  const info = {
+    description: node.description,
+  };
+
+  if (node.guide) {
+    info.guide = node.guide;
+  }
+
+  if (resolvedScopes && resolvedScopes.length > 0) {
+    info.scopes = resolvedScopes;
+  }
+
+  if (node.params) {
+    try {
+      info.params = zodToJsonSchema(node.params);
+    } catch (e) {
+      // skip
+    }
+  }
+
+  if (resolvedNext) {
+    info.next = Object.entries(resolvedNext).map(([name, child]) => ({
+      name,
+      description: child.description,
+      isDynamic: name.startsWith('$'),
+      isEndpoint: !child.next,
+    }));
+  }
+
+  return info;
+}
+
+/**
+ * Resolve a path through the node tree and execute/describe the target node.
+ *
+ * @param {Object} node - The root node to start from
+ * @param {string[]} path - Array of path segments (already split by '.')
+ * @param {Object} ctx - The context object (will be mutated by handlers)
+ * @param {Object} params - Request body params (used at leaf nodes)
+ * @param {'GET'|'POST'} method - HTTP method
+ * @param {string[]} [inheritedScopes] - Scopes inherited from ancestors
+ * @returns {Promise<Object>} ResolveResult
+ */
+export async function resolve(node, path, ctx, params, method, inheritedScopes) {
+  try {
+    const atEndOfPath = path.length === 0;
+    const resolvedScopes = node.scopes || inheritedScopes;
+
+    if (!atEndOfPath) {
+      const needsHandler = method === 'POST' || isDynamicNext(node.next);
+      if (needsHandler && node.handler) {
+        await node.handler(ctx, params);
+      }
+
+      const nextNodes = isDynamicNext(node.next)
+        ? await node.next(ctx)
+        : node.next;
+
+      const [segment, ...rest] = path;
+      const found = findNext(nextNodes, segment);
+
+      if (!found) {
+        return { ok: false, error: `Unknown path segment: ${segment}`, status: 404 };
+      }
+
+      if (found.paramName) {
+        ctx.pathParams[found.paramName] = segment;
+      }
+
+      // $resolveFullPath captures all remaining segments
+      if (found.paramName === 'resolveFullPath') {
+        ctx.pathParams.resolveFullPath = [segment, ...rest];
+        ctx.resolvedScopes = found.node.scopes || resolvedScopes;
+
+        if (method === 'GET') {
+          return { ok: true, info: buildNodeInfo(found.node, resolvedScopes) };
+        }
+
+        if (!found.node.handler) {
+          return { ok: false, error: 'No handler defined for this function', status: 500 };
+        }
+
+        const result = await found.node.handler(ctx, params);
+        return { ok: true, result };
+      }
+
+      return resolve(found.node, rest, ctx, params, method, resolvedScopes);
+    }
+
+    ctx.resolvedScopes = resolvedScopes;
+
+    if (method === 'GET') {
+      const nextNodes = await resolveNext(node, ctx);
+      return { ok: true, info: buildNodeInfo(node, inheritedScopes, nextNodes) };
+    }
+
+    const isLeaf = !node.next;
+    if (!isLeaf) {
+      return {
+        ok: false,
+        error: 'Cannot execute branch node - must specify a complete path to a leaf function',
+        status: 400,
+      };
+    }
+
+    let validatedParams = params;
+    if (node.params) {
+      const schema = node.params;
+      const strictSchema = typeof schema.strict === 'function' ? schema.strict() : schema;
+      const parsed = strictSchema.safeParse(params);
+      if (!parsed.success) {
+        return {
+          ok: false,
+          error: formatZodError(parsed.error),
+          schema: zodToSimpleSchema(node.params),
+          status: 400,
+        };
+      }
+      validatedParams = parsed.data;
+    }
+
+    if (!node.handler) {
+      return { ok: false, error: 'No handler defined for this function', status: 500 };
+    }
+
+    const result = await node.handler(ctx, validatedParams);
+    return { ok: true, result };
+  } catch (err) {
+    const upstreamError = err.response?.data || err.response?.body;
+    return {
+      ok: false,
+      error: upstreamError || (err instanceof Error ? err.message : 'Unknown error occurred'),
+      status: err.response?.status || 500,
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papercraneai/cli",
-  "version": "1.8.3",
+  "version": "1.9.0-beta.0",
   "description": "CLI tool for managing OAuth credentials for LLM integrations",
   "main": "index.js",
   "type": "module",
@@ -69,10 +69,12 @@
     "cmdk": "^1.1.1",
     "commander": "^12.0.0",
     "date-fns": "^4.1.0",
+    "dotenv": "^16.4.5",
     "embla-carousel-react": "^8.6.0",
     "express": "^5.1.0",
     "https-proxy-agent": "^7.0.4",
     "input-otp": "^1.4.2",
+    "jiti": "^2.4.2",
     "inquirer": "^8.2.6",
     "lucide-react": "^0.559.0",
     "next": "16.1.7",
@@ -92,7 +94,8 @@
     "tw-animate-css": "^1.4.0",
     "typescript": "^5",
     "vaul": "^1.1.2",
-    "zod": "^4.1.13"
+    "zod": "^4.1.13",
+    "zod-to-json-schema": "^3.24.5"
   },
   "overrides": {}
 }

package/runtime-lib/papercrane.ts

@@ -28,6 +28,24 @@ export async function getAuthConfig(): Promise<AuthConfig> {
 }
 
 export async function authFetch(functionPath: string, params: Record<string, unknown> = {}) {
+  // Route local.* handlers to the dev server on localhost
+  if (functionPath.startsWith('local.')) {
+    const port = process.env.PAPERCRANE_LOCAL_PORT || '3100'
+    const res = await fetch(`http://localhost:${port}/function/${functionPath}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ params })
+    })
+
+    if (!res.ok) {
+      const error = await res.json().catch(() => ({ error: res.statusText }))
+      throw new Error(error.error || `Local handler error: ${res.status}`)
+    }
+
+    const { result } = await res.json()
+    return result
+  }
+
   const { apiKey, apiBaseUrl } = await getAuthConfig()
 
   const res = await fetch(`${apiBaseUrl}/function/${functionPath}`, {