deepline 0.0.1 → 0.1.1

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

@@ -0,0 +1,77 @@
+import { SDK_API_CONTRACT, SDK_VERSION } from "./version.js";
+
+export type SdkCompatibilityStatus =
+  | "current"
+  | "update_available"
+  | "deprecated"
+  | "unsupported";
+
+export type SdkCompatibilityResponse = {
+  ok: boolean;
+  status: SdkCompatibilityStatus;
+  current: string | null;
+  latest: string;
+  minimum_supported: string;
+  deprecated_below: string;
+  api_contract: string;
+  update_available: boolean;
+  update_required: boolean;
+  message: string;
+  update_command: string;
+};
+
+const CHECK_TIMEOUT_MS = 2_000;
+
+function shouldSkipCompatibilityCheck(): boolean {
+  const value = process.env.DEEPLINE_SKIP_SDK_COMPAT_CHECK?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
+export async function checkSdkCompatibility(baseUrl: string): Promise<{
+  response: SdkCompatibilityResponse | null;
+  error: Error | null;
+}> {
+  if (shouldSkipCompatibilityCheck()) {
+    return { response: null, error: null };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+  try {
+    const url = new URL("/api/v2/sdk/compat", baseUrl);
+    url.searchParams.set("version", SDK_VERSION);
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        "User-Agent": `deepline-ts-sdk/${SDK_VERSION}`,
+        "X-Deepline-SDK-Version": SDK_VERSION,
+        "X-Deepline-API-Contract": SDK_API_CONTRACT,
+      },
+      signal: controller.signal,
+    });
+    const data = (await response.json().catch(() => null)) as
+      | SdkCompatibilityResponse
+      | null;
+    return { response: data, error: null };
+  } catch (error) {
+    return {
+      response: null,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function enforceSdkCompatibility(baseUrl: string): Promise<void> {
+  const { response, error } = await checkSdkCompatibility(baseUrl);
+  if (error || !response) {
+    return;
+  }
+  if (response.update_required) {
+    throw new Error(response.message);
+  }
+  if (response.status === "deprecated" || response.status === "update_available") {
+    process.stderr.write(`${response.message}\n`);
+  }
+}

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

@@ -0,0 +1,285 @@
+/**
+ * Configuration resolution for the Deepline SDK.
+ *
+ * The SDK resolves configuration from multiple sources in a strict priority order,
+ * making it zero-config for common setups while allowing full override control.
+ *
+ * ## Resolution order
+ *
+ * ### 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.worktree`
+ * 5. `DEEPLINE_ORIGIN_URL` from the production host auth file
+ * 6. Production fallback: `https://code.deepline.com`
+ *
+ * ### 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)
+ *
+ * If no API key is found from any source, a {@link ConfigError} is thrown.
+ *
+ * ## CLI env file format
+ *
+ * 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
+ * ```
+ *
+ * @module
+ */
+import { readFileSync, existsSync, mkdirSync, 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';
+
+/** Production API base URL. */
+const PROD_URL = 'https://code.deepline.com';
+
+/** Default request timeout: 60 seconds. */
+const DEFAULT_TIMEOUT = 60_000;
+
+/** Default retry count for transient failures. */
+const DEFAULT_MAX_RETRIES = 3;
+
+/**
+ * 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"
+ * baseUrlSlug('https://code.deepline.com')  // "code-deepline-com"
+ * baseUrlSlug('https://example.com:8080')   // "example-com-8080"
+ * ```
+ */
+function baseUrlSlug(baseUrl: string): string {
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return 'unknown';
+  }
+  const host = url.hostname || 'unknown';
+  const port = url.port ? parseInt(url.port, 10) : null;
+  let slug = host.replace(/[^a-zA-Z0-9]/g, '-');
+  if (port && port !== 80 && port !== 443) {
+    slug = `${slug}-${port}`;
+  }
+  return slug.toLowerCase().replace(/^-+|-+$/g, '');
+}
+
+/**
+ * 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> {
+  if (!existsSync(filePath)) return {};
+  const env: Record<string, string> = {};
+  const content = readFileSync(filePath, 'utf-8');
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIndex = trimmed.indexOf('=');
+    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('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key && value) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+function findNearestWorktreeEnv(startDir: string = process.cwd()): Record<string, string> {
+  let current = resolve(startDir);
+  while (true) {
+    const values = parseEnvFile(join(current, '.env.worktree'));
+    if (Object.keys(values).length > 0) return values;
+    const parent = dirname(current);
+    if (parent === current) return {};
+    current = parent;
+  }
+}
+
+function normalizeWorktreeBaseUrl(baseUrl: string, worktreeEnv = findNearestWorktreeEnv()): string {
+  const trimmed = baseUrl.trim().replace(/\/$/, '');
+  if (!trimmed) return trimmed;
+  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}`;
+    }
+  } catch {}
+  return trimmed;
+}
+
+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}` : '';
+}
+
+/**
+ * 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 {
+  const home = process.env.HOME?.trim() || homedir();
+  return join(home, '.local', 'deepline', baseUrlSlug(baseUrl || PROD_URL), '.env');
+}
+
+function loadCliEnv(baseUrl = PROD_URL): Record<string, string> {
+  const envPath = sdkCliEnvFilePath(baseUrl);
+  return parseEnvFile(envPath);
+}
+
+export function hostEnvFilePath(baseUrl: string): string {
+  return sdkCliEnvFilePath(baseUrl);
+}
+
+export function saveHostEnvValues(baseUrl: string, values: Record<string, string>): void {
+  const filePath = sdkCliEnvFilePath(baseUrl);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const existing = existsSync(filePath) ? parseEnvFile(filePath) : {};
+  const merged = { ...existing, ...values };
+  const lines = Object.entries(merged)
+    .filter(([, value]) => 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> {
+  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 worktreeBaseUrl = resolveWorktreeBaseUrl();
+  if (worktreeBaseUrl) return worktreeBaseUrl;
+
+  const globalEnv = loadGlobalCliEnv();
+  const globalOrigin = globalEnv.DEEPLINE_ORIGIN_URL?.trim();
+  if (globalOrigin) return normalizeWorktreeBaseUrl(globalOrigin);
+
+  return PROD_URL;
+}
+
+/**
+ * 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 });
+ * ```
+ */
+export function resolveConfig(options?: DeeplineClientOptions): ResolvedConfig {
+  // Resolve base URL
+  const requestedBaseUrl =
+    options?.baseUrl?.trim() ||
+    autoDetectBaseUrl();
+  const baseUrl = normalizeWorktreeBaseUrl(requestedBaseUrl);
+
+  const cliEnv = loadCliEnv(baseUrl);
+
+  // Resolve API key: option > env var > SDK CLI env
+  const apiKey =
+    options?.apiKey?.trim() ||
+    process.env.DEEPLINE_API_KEY?.trim() ||
+    cliEnv.DEEPLINE_API_KEY ||
+    '';
+
+  if (!apiKey) {
+    throw new ConfigError(
+      `No API key found. Set DEEPLINE_API_KEY env var, pass apiKey option, or run: deepline auth register`,
+    );
+  }
+
+  return {
+    apiKey,
+    baseUrl,
+    timeout: options?.timeout ?? DEFAULT_TIMEOUT,
+    maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+  };
+}
+
+export { baseUrlSlug, loadCliEnv, loadGlobalCliEnv, parseEnvFile, autoDetectBaseUrl, PROD_URL };

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

@@ -0,0 +1,125 @@
+/**
+ * Base error class for all Deepline SDK errors.
+ *
+ * Every error thrown by the SDK extends this class, so you can catch all
+ * Deepline-specific errors with a single `catch (e) { if (e instanceof DeeplineError) }`.
+ *
+ * @example
+ * ```typescript
+ * import { DeeplineClient, DeeplineError, AuthError } from 'deepline';
+ *
+ * const client = new DeeplineClient();
+ * try {
+ *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ * } catch (err) {
+ *   if (err instanceof AuthError) {
+ *     console.error('Bad API key — run: deepline auth register');
+ *   } else if (err instanceof DeeplineError) {
+ *     console.error(`API error ${err.statusCode}: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export class DeeplineError extends Error {
+  constructor(
+    message: string,
+    /** HTTP status code from the API response, if applicable. */
+    public statusCode?: number,
+    /** Machine-readable error code (e.g. `'AUTH_ERROR'`, `'RATE_LIMIT'`, `'CONFIG_ERROR'`). */
+    public code?: string,
+    /** Additional context from the API response body. */
+    public details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'DeeplineError';
+  }
+}
+
+/**
+ * Thrown when the API rejects the request due to an invalid or missing API key.
+ *
+ * This maps to HTTP 401/403 responses. The SDK never retries auth errors —
+ * they fail immediately.
+ *
+ * Fix: run `deepline auth register` to obtain a valid key, or pass one via
+ * the `apiKey` option or `DEEPLINE_API_KEY` environment variable.
+ *
+ * @example
+ * ```typescript
+ * import { AuthError } from 'deepline';
+ *
+ * try {
+ *   await client.listTools();
+ * } catch (err) {
+ *   if (err instanceof AuthError) {
+ *     // Redirect user to auth flow
+ *   }
+ * }
+ * ```
+ */
+export class AuthError extends DeeplineError {
+  constructor(message = 'Authentication failed. Check your DEEPLINE_API_KEY.') {
+    super(message, 401, 'AUTH_ERROR');
+    this.name = 'AuthError';
+  }
+}
+
+/**
+ * Thrown when the API returns HTTP 429 (Too Many Requests).
+ *
+ * The SDK retries rate-limited requests automatically up to `maxRetries` times
+ * with exponential backoff. This error is only thrown when all retries are exhausted.
+ *
+ * Use {@link RateLimitError.retryAfterMs} to implement your own backoff if needed.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError } from 'deepline';
+ *
+ * try {
+ *   await client.executeTool('apollo_people_search', { query: 'cto' });
+ * } catch (err) {
+ *   if (err instanceof RateLimitError) {
+ *     console.log(`Retry after ${err.retryAfterMs}ms`);
+ *     await sleep(err.retryAfterMs);
+ *     // retry...
+ *   }
+ * }
+ * ```
+ */
+export class RateLimitError extends DeeplineError {
+  /** Milliseconds to wait before retrying, from the `Retry-After` response header. Defaults to 5000. */
+  public retryAfterMs: number;
+
+  constructor(retryAfterMs = 5000, message?: string) {
+    super(message ?? `Rate limited. Retry after ${retryAfterMs}ms.`, 429, 'RATE_LIMIT');
+    this.name = 'RateLimitError';
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/**
+ * Thrown when the SDK cannot resolve a valid configuration.
+ *
+ * Most commonly: no API key found in any of the resolution sources
+ * (explicit option, environment variable, CLI env files).
+ *
+ * @example
+ * ```typescript
+ * import { ConfigError } from 'deepline';
+ *
+ * try {
+ *   const client = new DeeplineClient();
+ * } catch (err) {
+ *   if (err instanceof ConfigError) {
+ *     console.error('Run: deepline auth register');
+ *   }
+ * }
+ * ```
+ */
+export class ConfigError extends DeeplineError {
+  constructor(message: string) {
+    super(message, undefined, 'CONFIG_ERROR');
+    this.name = 'ConfigError';
+  }
+}