deepline 0.1.32 → 0.1.35

package/dist/repo/sdk/src/config.ts

@@ -1,47 +1,43 @@
 /**
- * Configuration resolution for the Deepline SDK.
+ * Configuration resolution for the Deepline SDK and SDK CLI.
  *
- * The SDK resolves configuration from multiple sources in a strict priority order,
- * making it zero-config for common setups while allowing full override control.
+ * The public SDK CLI env contract is deliberately small:
  *
- * ## Resolution order
+ * - `DEEPLINE_HOST_URL`: Deepline API/app host, for example `https://code.deepline.com`
+ * - `DEEPLINE_API_KEY`: API key for that host and workspace
  *
- * ### Base URL
- * 1. `options.baseUrl` (explicit constructor argument)
- * 2. `DEEPLINE_ORIGIN_URL` environment variable
- * 3. `DEEPLINE_API_BASE_URL` environment variable
- * 4. Nearest checkout-local `.env.deepline`
- * 5. Nearest checkout-local profile file (`.env.deepline.prod`, etc.)
- * 6. Nearest checkout-local app env file (`.env.prod`, `.env.staging`, `.env.local`, `.env`)
- * 7. Nearest checkout-local `.env.worktree`
- * 8. `DEEPLINE_ORIGIN_URL` from the production host auth file
- * 9. Production fallback: `https://code.deepline.com`
+ * The CLI also stores the same two keys in per-host files under
+ * `~/.local/deepline/<host-slug>/.env`, created by `deepline auth register`.
  *
- * ### API Key
- * 1. `options.apiKey` (explicit constructor argument)
- * 2. `DEEPLINE_API_KEY` environment variable
- * 3. `DEEPLINE_API_KEY` from `~/.local/deepline/<host-slug>/.env` (SDK CLI config)
+ * Resolution order:
  *
- * If no API key is found from any source, a {@link ConfigError} is thrown.
+ * Base URL:
+ * 1. `options.baseUrl`
+ * 2. `DEEPLINE_HOST_URL`
+ * 3. nearest project `.env.deepline`
+ * 4. production host auth file
+ * 5. production fallback: `https://code.deepline.com`
  *
- * ## CLI env file format
+ * API key:
+ * 1. `options.apiKey`
+ * 2. `DEEPLINE_API_KEY`
+ * 3. nearest project `.env.deepline`
+ * 4. host auth file for the resolved base URL
  *
- * The CLI stores credentials in simple `KEY=VALUE` files (one per line).
- * These are created by `deepline auth register`:
- *
- * ```
- * ~/.local/deepline/code-deepline-com/.env       # production
- * ~/.local/deepline/localhost-3000/.env          # local dev
- * ```
+ * App/runtime env files such as `.env`, `.env.local`, and `.env.worktree` do
+ * not route the SDK CLI. Put CLI routing in `.env.deepline`.
  *
  * @module
  */
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import type { DeeplineClientOptions, ResolvedConfig } from './types.js';
 import { ConfigError } from './errors.js';
 
+export const HOST_URL_ENV = 'DEEPLINE_HOST_URL';
+export const API_KEY_ENV = 'DEEPLINE_API_KEY';
+
 /** Production API base URL. */
 const PROD_URL = 'https://code.deepline.com';
 
@@ -51,26 +47,13 @@ const DEFAULT_TIMEOUT = 60_000;
 /** Default retry count for transient failures. */
 const DEFAULT_MAX_RETRIES = 3;
 
-const ACTIVE_DEEPLINE_ENV_FILE = '.env.deepline';
-
-function isProdBaseUrl(baseUrl: string): boolean {
-  return baseUrl.trim().replace(/\/$/, '') === PROD_URL;
-}
+const PROJECT_DEEPLINE_ENV_FILE = '.env.deepline';
 
-function profileNameForBaseUrl(baseUrl: string): 'prod' | 'dev' {
-  return isProdBaseUrl(baseUrl) ? 'prod' : 'dev';
-}
-
-function projectEnvStartDir(): string {
-  return process.env.DEEPLINE_PROJECT_ENV_DIR?.trim() || process.cwd();
-}
+type EnvValues = Record<string, string>;
 
 /**
  * Convert a base URL to a filesystem-safe slug for per-host config storage.
  *
- * @param baseUrl - Full URL (e.g. `"http://localhost:3000"`)
- * @returns Slug like `"localhost-3000"` or `"code-deepline-com"`
- *
  * @example
  * ```typescript
  * baseUrlSlug('http://localhost:3000')      // "localhost-3000"
@@ -86,7 +69,7 @@ function baseUrlSlug(baseUrl: string): string {
     return 'unknown';
   }
   const host = url.hostname || 'unknown';
-  const port = url.port ? parseInt(url.port, 10) : null;
+  const port = url.port ? Number.parseInt(url.port, 10) : null;
   let slug = host.replace(/[^a-zA-Z0-9]/g, '-');
   if (port && port !== 80 && port !== 443) {
     slug = `${slug}-${port}`;
@@ -96,20 +79,10 @@ function baseUrlSlug(baseUrl: string): string {
 
 /**
  * Parse a simple `KEY=VALUE` env file. Handles `#` comments and quoted values.
- *
- * @param filePath - Absolute path to the env file
- * @returns Key-value pairs; empty object if file doesn't exist
- *
- * @example
- * ```typescript
- * // File: DEEPLINE_API_KEY="dl_test_abc123"
- * const env = parseEnvFile('/path/to/.env');
- * console.log(env.DEEPLINE_API_KEY); // "dl_test_abc123"
- * ```
  */
-function parseEnvFile(filePath: string): Record<string, string> {
+function parseEnvFile(filePath: string): EnvValues {
   if (!existsSync(filePath)) return {};
-  const env: Record<string, string> = {};
+  const env: EnvValues = {};
   const content = readFileSync(filePath, 'utf-8');
   for (const line of content.split(/\r?\n/)) {
     const trimmed = line.trim();
@@ -118,7 +91,6 @@ function parseEnvFile(filePath: string): Record<string, string> {
     if (eqIndex < 0) continue;
     const key = trimmed.slice(0, eqIndex).trim();
     let value = trimmed.slice(eqIndex + 1).trim();
-    // Strip surrounding quotes
     if (
       value.length >= 2 &&
       ((value.startsWith('"') && value.endsWith('"')) ||
@@ -134,223 +106,136 @@ function parseEnvFile(filePath: string): Record<string, string> {
 }
 
 function findNearestEnvFile(
-  names: string[],
+  name: string,
   startDir: string = process.cwd(),
 ): string | null {
   let current = resolve(startDir);
   while (true) {
-    for (const name of names) {
-      const filePath = join(current, name);
-      if (existsSync(filePath)) return filePath;
-    }
+    const filePath = join(current, name);
+    if (existsSync(filePath)) return filePath;
     const parent = dirname(current);
     if (parent === current) return null;
     current = parent;
   }
 }
 
-function findNearestEnv(names: string[], startDir: string = process.cwd()): Record<string, string> {
-  const filePath = findNearestEnvFile(names, startDir);
+function loadProjectDeeplineEnv(startDir = process.cwd()): EnvValues {
+  const filePath = findNearestEnvFile(PROJECT_DEEPLINE_ENV_FILE, startDir);
   return filePath ? parseEnvFile(filePath) : {};
 }
 
-function findNearestWorktreeEnv(startDir: string = process.cwd()): Record<string, string> {
-  return findNearestEnv(['.env.worktree'], startDir);
-}
-
-function resolveProfileEnvFileNames(): string[] {
-  const explicitProfile =
-    process.env.DEEPLINE_ENV_PROFILE?.trim() ||
-    process.env.DEEPLINE_PROFILE?.trim() ||
-    '';
-  const names: string[] = [];
-  if (explicitProfile) names.push(`.env.deepline.${explicitProfile}`);
-  const nodeEnv = process.env.NODE_ENV?.trim();
-  if (nodeEnv === 'production') names.push('.env.deepline.prod');
-  else if (nodeEnv === 'staging') names.push('.env.deepline.staging');
-  names.push(ACTIVE_DEEPLINE_ENV_FILE);
-  return names;
-}
-
-function resolveProjectAppEnvFileNames(): string[] {
-  const nodeEnv = process.env.NODE_ENV?.trim();
-  const names: string[] = [];
-  if (nodeEnv === 'production') names.push('.env.prod');
-  if (nodeEnv === 'staging') names.push('.env.staging');
-  names.push('.env.local', '.env');
-  return names;
-}
-
-function resolveBaseUrlFromEnvValues(env: Record<string, string>): string {
-  return (
-    env.DEEPLINE_ORIGIN_URL?.trim() ||
-    env.DEEPLINE_API_BASE_URL?.trim() ||
-    ''
-  );
-}
-
-function loadProjectDeeplineEnv(): Record<string, string> {
-  return findNearestEnv(resolveProfileEnvFileNames(), projectEnvStartDir());
-}
-
-function loadProjectAppEnv(): Record<string, string> {
-  return findNearestEnv(resolveProjectAppEnvFileNames(), projectEnvStartDir());
-}
-
-function normalizeWorktreeBaseUrl(baseUrl: string, worktreeEnv = findNearestWorktreeEnv()): string {
-  const trimmed = baseUrl.trim().replace(/\/$/, '');
-  if (!trimmed) return trimmed;
+function normalizeBaseUrl(baseUrl: string): string {
+  const trimmed = baseUrl.trim().replace(/\/+$/, '');
+  if (!trimmed) return '';
   try {
     const parsed = new URL(trimmed);
-    if (parsed.hostname.endsWith('.localhost') && parsed.port === '1355') {
-      const port = worktreeEnv.WORKTREE_APP_PORT || worktreeEnv.PORT;
-      if (port) return `${parsed.protocol}//localhost:${port}`;
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return '';
     }
-  } catch {}
-  return trimmed;
+    return parsed.toString().replace(/\/+$/, '');
+  } catch {
+    return '';
+  }
 }
 
-function resolveWorktreeBaseUrl(): string {
-  const worktreeEnv = findNearestWorktreeEnv();
-  const declared =
-    worktreeEnv.DEEPLINE_API_BASE_URL ||
-    worktreeEnv.WORKTREE_PUBLIC_APP_URL ||
-    worktreeEnv.APP_URL ||
-    '';
-  if (declared) return normalizeWorktreeBaseUrl(declared, worktreeEnv);
-  const port = worktreeEnv.WORKTREE_APP_PORT || worktreeEnv.PORT || '';
-  return port ? `http://localhost:${port}` : '';
+function firstNonEmpty(...values: Array<string | undefined | null>): string {
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (trimmed) return trimmed;
+  }
+  return '';
 }
 
-/**
- * Load the SDK CLI env file for a specific Deepline host.
- *
- * @returns Key-value pairs from `~/.local/deepline/<host-slug>/.env`
- */
-function sdkCliEnvFilePath(baseUrl: string): string {
+function sdkCliConfigDir(baseUrl: string): string {
   const home = process.env.HOME?.trim() || homedir();
-  return join(home, '.local', 'deepline', baseUrlSlug(baseUrl || PROD_URL), '.env');
+  return join(home, '.local', 'deepline', baseUrlSlug(baseUrl || PROD_URL));
+}
+
+function sdkCliEnvFilePath(baseUrl: string): string {
+  return join(sdkCliConfigDir(baseUrl), '.env');
 }
 
-function loadCliEnv(baseUrl = PROD_URL): Record<string, string> {
-  const envPath = sdkCliEnvFilePath(baseUrl);
-  return parseEnvFile(envPath);
+function loadCliEnv(baseUrl = PROD_URL): EnvValues {
+  return parseEnvFile(sdkCliEnvFilePath(baseUrl));
+}
+
+export function hostConfigDirPath(baseUrl: string): string {
+  return sdkCliConfigDir(baseUrl);
 }
 
 export function hostEnvFilePath(baseUrl: string): string {
   return sdkCliEnvFilePath(baseUrl);
 }
 
-export function saveHostEnvValues(baseUrl: string, values: Record<string, string>): void {
+export function saveHostEnvValues(baseUrl: string, values: EnvValues): void {
   const filePath = sdkCliEnvFilePath(baseUrl);
   const dir = dirname(filePath);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
 
-  const existing = existsSync(filePath) ? parseEnvFile(filePath) : {};
+  const existing = parseEnvFile(filePath);
   const merged = { ...existing, ...values };
+  const allowedKeys = new Set([HOST_URL_ENV, API_KEY_ENV]);
   const lines = Object.entries(merged)
-    .filter(([, value]) => value !== '')
+    .filter(([key, value]) => allowedKeys.has(key) && value !== '')
     .map(([key, value]) => `${key}=${value}`);
   writeFileSync(filePath, `${lines.join('\n')}\n`, 'utf-8');
 }
 
-/**
- * Load the production SDK CLI env file.
- *
- * This gives `deepline` a stable production default without sharing credentials
- * with local/worktree hosts.
- */
-function loadGlobalCliEnv(): Record<string, string> {
+function loadGlobalCliEnv(): EnvValues {
   return loadCliEnv(PROD_URL);
 }
 
-/**
- * Check if a URL points to a local development server.
- *
- * @example
- * ```typescript
- * isLocalhost('http://localhost:3000')  // true
- * isLocalhost('http://127.0.0.1:3000') // true
- * isLocalhost('https://code.deepline.com') // false
- * ```
- */
 /**
  * Auto-detect the best base URL when none is explicitly provided.
- *
- * Checks environment variables first, then checkout-local worktree config,
- * then SDK CLI config, before falling back to production.
  */
 function autoDetectBaseUrl(): string {
-  const envOrigin = process.env.DEEPLINE_ORIGIN_URL?.trim();
-  if (envOrigin) return normalizeWorktreeBaseUrl(envOrigin);
-
-  const envBase = process.env.DEEPLINE_API_BASE_URL?.trim();
-  if (envBase) return normalizeWorktreeBaseUrl(envBase);
-
-  const projectDeeplineBaseUrl = resolveBaseUrlFromEnvValues(loadProjectDeeplineEnv());
-  if (projectDeeplineBaseUrl) return normalizeWorktreeBaseUrl(projectDeeplineBaseUrl);
-
-  const projectAppBaseUrl = resolveBaseUrlFromEnvValues(loadProjectAppEnv());
-  if (projectAppBaseUrl) return normalizeWorktreeBaseUrl(projectAppBaseUrl);
-
-  const worktreeBaseUrl = resolveWorktreeBaseUrl();
-  if (worktreeBaseUrl) return worktreeBaseUrl;
-
+  const projectEnv = loadProjectDeeplineEnv();
   const globalEnv = loadGlobalCliEnv();
-  const globalOrigin = globalEnv.DEEPLINE_ORIGIN_URL?.trim();
-  if (globalOrigin) return normalizeWorktreeBaseUrl(globalOrigin);
+  return (
+    normalizeBaseUrl(process.env[HOST_URL_ENV] ?? '') ||
+    normalizeBaseUrl(projectEnv[HOST_URL_ENV] ?? '') ||
+    normalizeBaseUrl(globalEnv[HOST_URL_ENV] ?? '') ||
+    PROD_URL
+  );
+}
 
-  return PROD_URL;
+export function resolveApiKeyForBaseUrl(
+  baseUrl: string,
+  explicitApiKey?: string | null,
+): string {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  const projectEnv = loadProjectDeeplineEnv();
+  const cliEnv = loadCliEnv(normalizedBaseUrl || baseUrl);
+  const projectBaseUrl = normalizeBaseUrl(projectEnv[HOST_URL_ENV] ?? '');
+  const projectKeyApplies = projectBaseUrl === normalizedBaseUrl;
+  return firstNonEmpty(
+    explicitApiKey,
+    process.env[API_KEY_ENV],
+    projectKeyApplies ? projectEnv[API_KEY_ENV] : '',
+    cliEnv[API_KEY_ENV],
+  );
 }
 
 /**
- * Resolve SDK configuration from all available sources.
- *
- * Merges explicit options, environment variables, and CLI-managed config files
- * into a fully validated {@link ResolvedConfig}. See the module-level docs for
- * the complete resolution order.
- *
- * @param options - Optional overrides (highest priority)
- * @returns Fully resolved configuration with all fields populated
- * @throws {@link ConfigError} if no API key can be found from any source
- *
- * @example
- * ```typescript
- * import { resolveConfig } from 'deepline';
- *
- * // Auto-resolve everything:
- * const config = resolveConfig();
- * console.log(config.baseUrl); // "http://localhost:3000" or "https://code.deepline.com"
- *
- * // Override specific values:
- * const config2 = resolveConfig({ baseUrl: 'http://localhost:4000', timeout: 10_000 });
- * ```
+ * Resolve SDK configuration from the public SDK CLI env contract.
  */
 export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
-  // Resolve base URL
-  const requestedBaseUrl =
-    options?.baseUrl?.trim() ||
-    autoDetectBaseUrl();
-  const baseUrl = normalizeWorktreeBaseUrl(requestedBaseUrl);
-
-  const cliEnv = loadCliEnv(baseUrl);
-  const projectDeeplineEnv = loadProjectDeeplineEnv();
-  const projectAppEnv = loadProjectAppEnv();
+  const baseUrl = normalizeBaseUrl(
+    options?.baseUrl?.trim() || autoDetectBaseUrl(),
+  );
+  if (!baseUrl) {
+    throw new ConfigError(
+      `Invalid ${HOST_URL_ENV}. Expected an http(s) URL such as https://code.deepline.com.`,
+    );
+  }
 
-  // Resolve API key: option > env var > SDK CLI env
-  const apiKey =
-    options?.apiKey?.trim() ||
-    process.env.DEEPLINE_API_KEY?.trim() ||
-    projectDeeplineEnv.DEEPLINE_API_KEY ||
-    projectAppEnv.DEEPLINE_API_KEY ||
-    cliEnv.DEEPLINE_API_KEY ||
-    '';
+  const apiKey = resolveApiKeyForBaseUrl(baseUrl, options?.apiKey);
 
   if (!apiKey) {
     throw new ConfigError(
-      `No API key found. Set DEEPLINE_API_KEY env var, pass apiKey option, or run: deepline auth register`,
+      `No API key found. Set ${API_KEY_ENV}, add it to .env.deepline, or run: deepline auth register`,
     );
   }
 
@@ -362,34 +247,25 @@ export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
   };
 }
 
-function mergeEnvFile(filePath: string, values: Record<string, string>): void {
-  const existing = existsSync(filePath) ? parseEnvFile(filePath) : {};
+function mergeProjectEnvFile(filePath: string, values: EnvValues): void {
+  const existing = parseEnvFile(filePath);
   const merged = { ...existing, ...values };
   const dir = dirname(filePath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const allowedKeys = new Set([HOST_URL_ENV, API_KEY_ENV]);
   const lines = Object.entries(merged)
-    .filter(([, value]) => value !== '')
+    .filter(([key, value]) => allowedKeys.has(key) && value !== '')
     .map(([key, value]) => `${key}=${value}`);
   writeFileSync(filePath, `${lines.join('\n')}\n`, 'utf-8');
 }
 
 export function saveProjectDeeplineEnvValues(
-  baseUrl: string,
-  values: Record<string, string>,
-  startDir: string = projectEnvStartDir(),
+  values: EnvValues,
+  startDir: string = process.cwd(),
 ): string[] {
-  const root = resolve(startDir);
-  const profile = profileNameForBaseUrl(baseUrl);
-  const files = [
-    join(root, ACTIVE_DEEPLINE_ENV_FILE),
-    join(root, `.env.deepline.${profile}`),
-  ];
-  if (profile === 'dev') files.push(join(root, '.env'));
-
-  for (const filePath of files) {
-    mergeEnvFile(filePath, values);
-  }
-  return files;
+  const filePath = join(resolve(startDir), PROJECT_DEEPLINE_ENV_FILE);
+  mergeProjectEnvFile(filePath, values);
+  return [filePath];
 }
 
 export {

package/dist/repo/sdk/src/http.ts

@@ -31,7 +31,7 @@ import {
 interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
   body?: unknown;
-  formData?: FormData;
+  formData?: FormData | (() => FormData);
   headers?: Record<string, string>;
   /** Per-request timeout override in milliseconds. */
   timeout?: number;
@@ -153,7 +153,9 @@ export class HttpClient {
             headers,
             body:
               options?.formData !== undefined
-                ? options.formData
+                ? typeof options.formData === 'function'
+                  ? options.formData()
+                  : options.formData
                 : options?.body !== undefined
                   ? JSON.stringify(options.body)
                   : undefined,
@@ -277,10 +279,13 @@ export class HttpClient {
           throw new AuthError();
         }
         if (!response.ok) {
+          const body = await response.text();
+          const parsed = parseResponseBody(body);
           throw new DeeplineError(
-            `HTTP ${response.status}`,
+            apiErrorMessage(parsed, response.status),
             response.status,
             'API_ERROR',
+            { response: parsed },
           );
         }
         if (!response.body) {
@@ -325,7 +330,7 @@ export class HttpClient {
 
   async postFormData<T = unknown>(
     path: string,
-    formData: FormData,
+    formData: FormData | (() => FormData),
     headers?: Record<string, string>,
   ): Promise<T> {
     return this.request<T>(path, {
@@ -346,6 +351,41 @@ export class HttpClient {
   }
 }
 
+function parseResponseBody(body: string): unknown {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+
+function apiErrorMessage(parsed: unknown, status: number): string {
+  const errorValue =
+    typeof parsed === 'object' && parsed && 'error' in parsed
+      ? (parsed as Record<string, unknown>).error
+      : undefined;
+  if (typeof errorValue === 'string') {
+    return errorValue;
+  }
+  if (
+    errorValue &&
+    typeof errorValue === 'object' &&
+    'message' in errorValue &&
+    typeof (errorValue as Record<string, unknown>).message === 'string'
+  ) {
+    return (errorValue as Record<string, string>).message;
+  }
+  if (
+    typeof parsed === 'object' &&
+    parsed &&
+    'message' in parsed &&
+    typeof (parsed as Record<string, unknown>).message === 'string'
+  ) {
+    return (parsed as Record<string, string>).message;
+  }
+  return `HTTP ${status}`;
+}
+
 /** Parse the `Retry-After` header as milliseconds. Falls back to 5000ms. */
 function parseRetryAfter(response: Response): number {
   const header = response.headers.get('retry-after');

package/dist/repo/sdk/src/index.ts

@@ -7,14 +7,14 @@
  * import { Deepline, definePlay } from 'deepline';
  *
  * // Connect (auto-resolves API key from env / CLI config)
- * const ctx = await Deepline.connect();
+ * const deepline = await Deepline.connect();
  *
  * // Execute a tool
- * const result = await ctx.tools.execute('test_company_search', { domain: 'stripe.com' });
- * const company = result.result.data;
+ * const result = await deepline.tools.execute('test_company_search', { domain: 'stripe.com' });
+ * const company = result.toolOutput.raw;
  *
  * // Run a named play
- * const job = await ctx.play('email-waterfall').run({ domain: 'stripe.com' });
+ * const job = await deepline.play('email-waterfall').run({ domain: 'stripe.com' });
  * const result = await job.get();
  * ```
  *
@@ -25,7 +25,10 @@
  *
  * export default definePlay('my-play', async (ctx, input: { domain: string }) => {
  *   ctx.log(`Looking up ${input.domain}`);
- *   const company = await ctx.tools.execute('company_search', 'test_company_search', { domain: input.domain }, {
+ *   const company = await ctx.tools.execute({
+ *     id: 'company_search',
+ *     tool: 'test_company_search',
+ *     input: { domain: input.domain },
  *     description: 'Look up company details by domain.',
  *   });
  *   return company;