@zackbart/connecta 0.15.1 → 0.16.1

package/src/storage/file.ts

@@ -1,123 +0,0 @@
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname } from "node:path";
-import type { KVStorage, Logger } from "../types.js";
-
-interface Entry {
-  value: string;
-  exp?: number; // epoch ms
-}
-
-export interface FileStorageOptions {
-  /** Destination for the corrupt-state-file recovery report. Default console. */
-  logger?: Logger;
-}
-
-/**
- * JSON-file-backed KVStorage for Node. Loads once, persists on every write via
- * a temp-file + rename (atomic-ish). Only reachable via the "@zackbart/connecta/node"
- * subpath so the main entry stays Workers-clean.
- */
-export function fileStorage(
-  path: string,
-  opts: FileStorageOptions = {},
-): KVStorage {
-  const logger: Logger = opts.logger ?? console;
-  // The state file holds downstream OAuth access/refresh tokens in cleartext,
-  // so keep it owner-only. Repair is best-effort: chmod is a no-op or throws on
-  // non-POSIX filesystems, and a loose mode must never keep the store from
-  // starting.
-  const tighten = () => {
-    try {
-      chmodSync(path, 0o600);
-    } catch {
-      // Non-POSIX filesystem or a race on the file — leave the mode as-is.
-    }
-  };
-  let data: Record<string, Entry> = {};
-  if (existsSync(path)) {
-    tighten();
-    try {
-      data = JSON.parse(readFileSync(path, "utf8")) as Record<string, Entry>;
-    } catch (error) {
-      // Never let a damaged state file be silently replaced by an empty one:
-      // the next set() would persist {} over irreplaceable downstream OAuth
-      // tokens and credential-vault entries. Quarantine the bytes so they
-      // survive for manual recovery, and refuse to start if even that fails —
-      // losing the file loudly beats losing it quietly.
-      const quarantine = `${path}.corrupt-${Date.now()}`;
-      try {
-        renameSync(path, quarantine);
-      } catch (renameError) {
-        throw new Error(
-          `[connecta] state file ${path} is not valid JSON and could not be ` +
-            `moved aside (${String(renameError)}). Refusing to start rather ` +
-            `than overwrite it. Move or repair the file, then restart.`,
-        );
-      }
-      logger.error(
-        `[connecta] state file ${path} is not valid JSON ` +
-          `(${error instanceof Error ? error.message : String(error)}) — ` +
-          `moved to ${quarantine}, starting from empty state. Downstream ` +
-          `OAuth connectors must be re-authorized and stored credentials ` +
-          `re-entered.`,
-      );
-      data = {};
-    }
-  }
-  const persist = () => {
-    // Physical expiry rides on an operation that was already going to write.
-    // A read must not flush this instance's load-once snapshot: another live
-    // instance may have written newer unrelated values since we loaded it.
-    const now = Date.now();
-    for (const [key, entry] of Object.entries(data)) {
-      if (entry.exp && now > entry.exp) delete data[key];
-    }
-    const dir = dirname(path);
-    if (dir) mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const tmp = `${path}.tmp`;
-    // 0o600 on the tmp file; the atomic rename below preserves it, so the live
-    // state file is never briefly world-readable.
-    writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
-    renameSync(tmp, path);
-    tighten();
-  };
-  const fresh = (key: string): Entry | null => {
-    const e = data[key];
-    if (!e) return null;
-    if (e.exp && Date.now() > e.exp) {
-      delete data[key];
-      return null;
-    }
-    return e;
-  };
-  return {
-    async get(key) {
-      return fresh(key)?.value ?? null;
-    },
-    async set(key, value, opts) {
-      data[key] = {
-        value,
-        ...(opts?.ttlSeconds
-          ? { exp: Date.now() + opts.ttlSeconds * 1000 }
-          : {}),
-      };
-      persist();
-    },
-    async delete(key) {
-      delete data[key];
-      persist();
-    },
-    async list(prefix) {
-      return Object.keys(data)
-        .filter((key) => Boolean(fresh(key)) && key.startsWith(prefix))
-        .sort();
-    },
-  };
-}

package/src/storage/memory.ts

@@ -1,44 +0,0 @@
-import type { KVStorage } from "../types.js";
-
-interface Entry {
-  value: string;
-  exp?: number; // epoch ms
-}
-
-/** In-memory KV store with expiry. The default for dev and Node. */
-export function memoryStorage(): KVStorage {
-  const map = new Map<string, Entry>();
-  const fresh = (key: string): Entry | null => {
-    const e = map.get(key);
-    if (!e) return null;
-    if (e.exp && Date.now() > e.exp) {
-      map.delete(key);
-      return null;
-    }
-    return e;
-  };
-  return {
-    async get(key) {
-      return fresh(key)?.value ?? null;
-    },
-    async set(key, value, opts) {
-      map.set(key, {
-        value,
-        ...(opts?.ttlSeconds
-          ? { exp: Date.now() + opts.ttlSeconds * 1000 }
-          : {}),
-      });
-    },
-    async delete(key) {
-      map.delete(key);
-    },
-    async list(prefix) {
-      return [...map.keys()]
-        .filter((key) => {
-          fresh(key);
-          return key.startsWith(prefix) && map.has(key);
-        })
-        .sort();
-    },
-  };
-}

package/src/timeout.ts

@@ -1,84 +0,0 @@
-// The deadline vocabulary shared by downstream discovery probes and tool calls.
-// One definition keeps those waits bounded consistently.
-
-/**
- * Generous default bound for a single downstream probe/catalog call. High enough
- * to trip only on a pathological hang, not a realistically slow probe.
- */
-export const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
-
-/** A finite, positive integer number of milliseconds, or undefined. */
-export function normalizeTimeoutMs(
-  value: number | undefined,
-): number | undefined {
-  if (value === undefined || !Number.isFinite(value) || !(value > 0)) {
-    return undefined;
-  }
-  return Math.max(1, Math.trunc(value));
-}
-
-/**
- * Reject `promise` after `ms` if it has not settled, so one hung downstream
- * cannot stall a whole fan-out. This form bounds only the caller-facing wait;
- * use `withAbortableTimeout` when the operation accepts an AbortSignal and the
- * underlying work must stop too.
- */
-export function withTimeout<T>(
-  promise: Promise<T>,
-  ms: number,
-  label: string,
-): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new Error(`${label} timed out after ${ms}ms`));
-    }, ms);
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (err) => {
-        clearTimeout(timer);
-        reject(err);
-      },
-    );
-  });
-}
-
-/**
- * Give one operation a caller-facing deadline and the matching cancellation
- * signal. The timeout rejects with the stable, labelled error while aborting
- * any in-flight work that honors the signal.
- */
-export function withAbortableTimeout<T>(
-  operation: (signal: AbortSignal) => Promise<T>,
-  ms: number,
-  label: string,
-): Promise<T> {
-  const controller = new AbortController();
-  return new Promise<T>((resolve, reject) => {
-    const timeoutError = new Error(`${label} timed out after ${ms}ms`);
-    const timer = setTimeout(() => {
-      controller.abort(timeoutError);
-      reject(timeoutError);
-    }, ms);
-    let promise: Promise<T>;
-    try {
-      promise = operation(controller.signal);
-    } catch (err) {
-      clearTimeout(timer);
-      reject(err);
-      return;
-    }
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (err) => {
-        clearTimeout(timer);
-        reject(err);
-      },
-    );
-  });
-}

package/src/tool-safety.ts

@@ -1,15 +0,0 @@
-import type { ToolDef } from "./types.js";
-
-/**
- * The one fail-closed classification shared by discovery and invocation.
- *
- * A tool is read-only only when it says so without also saying it is
- * destructive. Missing, false, and contradictory annotations all require the
- * approval-visible call path.
- */
-export function isExplicitlyReadOnly(definition: ToolDef): boolean {
-  return (
-    definition.annotations?.readOnlyHint === true &&
-    definition.annotations?.destructiveHint !== true
-  );
-}