@remnic/core 1.1.2 → 1.1.3

package/dist/chunk-6TBWYBJ3.js

@@ -0,0 +1,236 @@
+import {
+  expandTildePath
+} from "./chunk-IXEJRKCZ.js";
+
+// src/connectors/live/state-store.ts
+import { promises as fs } from "fs";
+import path from "path";
+
+// src/connectors/live/framework.ts
+var CONNECTOR_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+function isValidConnectorId(id) {
+  return typeof id === "string" && CONNECTOR_ID_PATTERN.test(id);
+}
+
+// src/connectors/live/state-store.ts
+var STATE_DIR_NAME = "state";
+var CONNECTORS_DIR_NAME = "connectors";
+var MAX_ERROR_LENGTH = 1024;
+var VALID_SYNC_STATUSES = /* @__PURE__ */ new Set([
+  "success",
+  "error",
+  "never"
+]);
+var ConnectorStateCorruptionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectorStateCorruptionError";
+  }
+};
+function resolveConnectorsDir(memoryDir) {
+  if (typeof memoryDir !== "string" || memoryDir.length === 0) {
+    throw new TypeError("memoryDir must be a non-empty string");
+  }
+  return path.join(expandTildePath(memoryDir), STATE_DIR_NAME, CONNECTORS_DIR_NAME);
+}
+function resolveConnectorStatePath(memoryDir, id) {
+  if (!isValidConnectorId(id)) {
+    throw new TypeError(
+      `invalid connector id ${JSON.stringify(id)} \u2014 must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`
+    );
+  }
+  return path.join(resolveConnectorsDir(memoryDir), `${id}.json`);
+}
+function isConnectorStateShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.id !== "string") return false;
+  if (typeof v.lastSyncStatus !== "string") return false;
+  if (!["success", "error", "never"].includes(v.lastSyncStatus)) return false;
+  if (typeof v.totalDocsImported !== "number" || !Number.isInteger(v.totalDocsImported)) return false;
+  if (v.totalDocsImported < 0) return false;
+  if (typeof v.updatedAt !== "string") return false;
+  if (v.lastSyncAt !== null && typeof v.lastSyncAt !== "string") return false;
+  if (v.cursor !== null) {
+    if (typeof v.cursor !== "object" || v.cursor === null) return false;
+    const c = v.cursor;
+    if (typeof c.kind !== "string" || typeof c.value !== "string" || typeof c.updatedAt !== "string") {
+      return false;
+    }
+  }
+  if (v.lastSyncError !== void 0 && typeof v.lastSyncError !== "string") return false;
+  return true;
+}
+async function assertNoSymlinkOnPath(memoryDir, filePath) {
+  const expandedRoot = expandTildePath(memoryDir);
+  const root = path.resolve(expandedRoot);
+  const target = path.resolve(filePath);
+  const rel = path.relative(root, target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(
+      `connector state path ${target} escapes memory root ${root}`
+    );
+  }
+  const segments = rel.length === 0 ? [] : rel.split(path.sep);
+  let current = root;
+  const componentsToCheck = [current];
+  for (const seg of segments) {
+    current = path.join(current, seg);
+    componentsToCheck.push(current);
+  }
+  for (const component of componentsToCheck) {
+    let stat;
+    try {
+      stat = await fs.lstat(component);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        continue;
+      }
+      throw err;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `connector state path component ${component} is a symlink; refusing to follow`
+      );
+    }
+  }
+}
+async function readConnectorState(memoryDir, id) {
+  const filePath = resolveConnectorStatePath(memoryDir, id);
+  await assertNoSymlinkOnPath(memoryDir, filePath);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new ConnectorStateCorruptionError(
+      `connector state at ${filePath} is not valid JSON: ${err.message}`
+    );
+  }
+  if (!isConnectorStateShape(parsed)) {
+    throw new ConnectorStateCorruptionError(
+      `connector state at ${filePath} does not match ConnectorState shape`
+    );
+  }
+  if (parsed.id !== id) {
+    throw new ConnectorStateCorruptionError(
+      `connector state at ${filePath} has mismatched id ${JSON.stringify(parsed.id)}; expected ${JSON.stringify(id)}`
+    );
+  }
+  return parsed;
+}
+async function writeConnectorState(memoryDir, id, state) {
+  if (!isValidConnectorId(id)) {
+    throw new TypeError(
+      `invalid connector id ${JSON.stringify(id)} \u2014 must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`
+    );
+  }
+  if (state.id !== id) {
+    throw new Error(
+      `writeConnectorState(): state.id ${JSON.stringify(state.id)} does not match id argument ${JSON.stringify(id)}`
+    );
+  }
+  if (!VALID_SYNC_STATUSES.has(state.lastSyncStatus)) {
+    throw new Error(
+      `writeConnectorState(): lastSyncStatus must be one of ${[...VALID_SYNC_STATUSES].join(", ")}, got ${JSON.stringify(state.lastSyncStatus)}`
+    );
+  }
+  if (state.lastSyncAt !== null && typeof state.lastSyncAt !== "string") {
+    throw new Error(
+      `writeConnectorState(): lastSyncAt must be a string or null, got ${typeof state.lastSyncAt}`
+    );
+  }
+  if (state.cursor !== null) {
+    if (typeof state.cursor !== "object") {
+      throw new Error(`writeConnectorState(): cursor must be an object or null`);
+    }
+    if (typeof state.cursor.kind !== "string" || typeof state.cursor.value !== "string" || typeof state.cursor.updatedAt !== "string") {
+      throw new Error(
+        `writeConnectorState(): cursor must have string kind, value, and updatedAt`
+      );
+    }
+  }
+  if (typeof state.totalDocsImported !== "number" || !Number.isInteger(state.totalDocsImported) || state.totalDocsImported < 0) {
+    throw new Error(
+      `writeConnectorState(): totalDocsImported must be a non-negative integer`
+    );
+  }
+  if (state.lastSyncError !== void 0 && typeof state.lastSyncError !== "string") {
+    throw new Error(`writeConnectorState(): lastSyncError must be a string when provided`);
+  }
+  const truncatedError = state.lastSyncError !== void 0 && state.lastSyncError.length > MAX_ERROR_LENGTH ? state.lastSyncError.slice(0, MAX_ERROR_LENGTH) : state.lastSyncError;
+  const finalState = {
+    id: state.id,
+    cursor: state.cursor,
+    lastSyncAt: state.lastSyncAt,
+    lastSyncStatus: state.lastSyncStatus,
+    ...truncatedError !== void 0 ? { lastSyncError: truncatedError } : {},
+    totalDocsImported: state.totalDocsImported,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const dir = resolveConnectorsDir(memoryDir);
+  const targetPath = path.join(dir, `${id}.json`);
+  await assertNoSymlinkOnPath(memoryDir, targetPath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const body = `${JSON.stringify(finalState, null, 2)}
+`;
+  try {
+    await fs.writeFile(tmpPath, body, { encoding: "utf-8", mode: 384 });
+    await fs.rename(tmpPath, targetPath);
+  } catch (err) {
+    try {
+      await fs.unlink(tmpPath);
+    } catch {
+    }
+    throw err;
+  }
+  return finalState;
+}
+async function listConnectorStates(memoryDir) {
+  const dir = resolveConnectorsDir(memoryDir);
+  await assertNoSymlinkOnPath(memoryDir, dir);
+  let entries;
+  try {
+    entries = await fs.readdir(dir);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const id = entry.slice(0, -".json".length);
+    if (!isValidConnectorId(id)) continue;
+    try {
+      const state = await readConnectorState(memoryDir, id);
+      if (state !== null) out.push(state);
+    } catch (err) {
+      if (err instanceof ConnectorStateCorruptionError) {
+        continue;
+      }
+      throw err;
+    }
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+function _connectorStatePathForTest(memoryDir, id) {
+  return resolveConnectorStatePath(memoryDir, id);
+}
+
+export {
+  CONNECTOR_ID_PATTERN,
+  isValidConnectorId,
+  readConnectorState,
+  writeConnectorState,
+  listConnectorStates,
+  _connectorStatePathForTest
+};
+//# sourceMappingURL=chunk-6TBWYBJ3.js.map

package/dist/chunk-6TBWYBJ3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connectors/live/state-store.ts","../src/connectors/live/framework.ts"],"sourcesContent":["/**\n * @remnic/core — Live Connectors State Store (issue #683 PR 1/N)\n *\n * Persists per-connector cursor + sync metadata to\n *   `<memoryDir>/state/connectors/<id>.json`\n *\n * Reasons this lives next to memory data, not in user config:\n *   - cursors are *operational* state that should travel with the memory\n *     directory when a user moves it across machines;\n *   - it keeps memory + ingest provenance co-located so tooling that backs up\n *     the memory directory captures cursor state too.\n *\n * Atomic-write contract (CLAUDE.md gotcha #54):\n *   - We NEVER `rmSync(target)` before `renameSync(tmp, target)`.\n *   - Writes go to a sibling tmp file and `rename()` swaps it in.\n *   - On error, the tmp file is best-effort cleaned up; the previous good\n *     state file is left untouched.\n *\n * Privacy: cursors are opaque connector-defined strings. We do not log them\n * and do not surface them through user-visible APIs. Document content NEVER\n * touches this module.\n */\n\nimport { promises as fs } from \"node:fs\";\nimport path from \"node:path\";\n\nimport { expandTildePath } from \"../../utils/path.js\";\n\nimport {\n  isValidConnectorId,\n  type ConnectorCursor,\n} from \"./framework.js\";\n\n/**\n * Status of the most recent sync attempt for a connector.\n *\n * `\"never\"` is distinct from `\"success\"` so callers can detect\n * \"registered but never run\" without inspecting timestamps. Per CLAUDE.md\n * gotcha #34, we deliberately distinguish empty/unknown from failure states.\n */\nexport type ConnectorSyncStatus = \"success\" | \"error\" | \"never\";\n\n/**\n * Persisted per-connector state.\n *\n * Stored as pretty-printed JSON for human inspection — the file is small\n * (one record per connector) and operators may need to debug stuck cursors\n * by hand.\n */\nexport interface ConnectorState {\n  /** Connector id. Matches the filename stem. */\n  readonly id: string;\n  /** Last persisted cursor, or `null` if the connector has never synced. */\n  readonly cursor: ConnectorCursor | null;\n  /** ISO 8601 timestamp of the last completed sync attempt, or `null`. */\n  readonly lastSyncAt: string | null;\n  /** Status of the last completed sync attempt. */\n  readonly lastSyncStatus: ConnectorSyncStatus;\n  /** Optional error message from the last failed sync. Truncated to 1 KB. */\n  readonly lastSyncError?: string;\n  /** Cumulative count of documents successfully imported across all syncs. */\n  readonly totalDocsImported: number;\n  /** ISO 8601 timestamp of when this state record was last written. */\n  readonly updatedAt: string;\n}\n\nconst STATE_DIR_NAME = \"state\";\nconst CONNECTORS_DIR_NAME = \"connectors\";\nconst MAX_ERROR_LENGTH = 1024;\nconst VALID_SYNC_STATUSES: ReadonlySet<ConnectorSyncStatus> = new Set([\n  \"success\",\n  \"error\",\n  \"never\",\n]);\n\n/**\n * Internal error thrown when a state file's JSON is unparseable or its shape\n * doesn't match `ConnectorState`. Used by `listConnectorStates` to distinguish\n * \"skip this corrupt file\" cases from genuine I/O failures (`EACCES`, `EIO`)\n * that the caller must see.\n */\nclass ConnectorStateCorruptionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ConnectorStateCorruptionError\";\n  }\n}\n\n/**\n * Resolve `<memoryDir>/state/connectors/`, expanding `~` per CLAUDE.md #17.\n */\nfunction resolveConnectorsDir(memoryDir: string): string {\n  if (typeof memoryDir !== \"string\" || memoryDir.length === 0) {\n    throw new TypeError(\"memoryDir must be a non-empty string\");\n  }\n  return path.join(expandTildePath(memoryDir), STATE_DIR_NAME, CONNECTORS_DIR_NAME);\n}\n\n/**\n * Resolve the state file path for a single connector. Throws on invalid id\n * to prevent path traversal via crafted ids.\n */\nfunction resolveConnectorStatePath(memoryDir: string, id: string): string {\n  if (!isValidConnectorId(id)) {\n    throw new TypeError(\n      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,\n    );\n  }\n  return path.join(resolveConnectorsDir(memoryDir), `${id}.json`);\n}\n\n/**\n * Type guard for parsed state records. Validates the on-disk shape so a\n * corrupted/edited file produces a clear error rather than crashing later.\n *\n * Per CLAUDE.md gotcha #18, JSON.parse('null') yields `null` which would\n * pass a naive truthy check. We explicitly require an object.\n */\nfunction isConnectorStateShape(value: unknown): value is ConnectorState {\n  if (typeof value !== \"object\" || value === null) return false;\n  const v = value as Record<string, unknown>;\n  if (typeof v.id !== \"string\") return false;\n  if (typeof v.lastSyncStatus !== \"string\") return false;\n  if (![\"success\", \"error\", \"never\"].includes(v.lastSyncStatus)) return false;\n  // totalDocsImported is a cumulative count — fractional values would corrupt\n  // metrics on later increments. Mirror the boundary check in writeConnectorState.\n  if (typeof v.totalDocsImported !== \"number\" || !Number.isInteger(v.totalDocsImported)) return false;\n  if (v.totalDocsImported < 0) return false;\n  if (typeof v.updatedAt !== \"string\") return false;\n  if (v.lastSyncAt !== null && typeof v.lastSyncAt !== \"string\") return false;\n  if (v.cursor !== null) {\n    if (typeof v.cursor !== \"object\" || v.cursor === null) return false;\n    const c = v.cursor as Record<string, unknown>;\n    if (typeof c.kind !== \"string\" || typeof c.value !== \"string\" || typeof c.updatedAt !== \"string\") {\n      return false;\n    }\n  }\n  if (v.lastSyncError !== undefined && typeof v.lastSyncError !== \"string\") return false;\n  return true;\n}\n\n/**\n * Reject any path component along `<memoryDir>/state/connectors/<id>.json`\n * that is a symlink. Without this guard, a symlink in any of those\n * components would let `fs.readFile` escape the memory root and consume an\n * arbitrary outside file as cursor state — silently poisoning sync state and\n * violating the project-wide rule against symlink traversal.\n *\n * `lstat` is used (not `stat`) so we observe the link itself rather than its\n * target. Missing components are tolerated — the caller's `readFile` /\n * `mkdir` will surface ENOENT in its normal way.\n *\n * (PR #724 review.)\n */\nasync function assertNoSymlinkOnPath(memoryDir: string, filePath: string): Promise<void> {\n  const expandedRoot = expandTildePath(memoryDir);\n  // Normalize so `..` segments can't bypass the prefix check below.\n  const root = path.resolve(expandedRoot);\n  const target = path.resolve(filePath);\n  const rel = path.relative(root, target);\n  // path.relative() yields a \"../...\" prefix when target escapes root.\n  if (rel.startsWith(\"..\") || path.isAbsolute(rel)) {\n    throw new Error(\n      `connector state path ${target} escapes memory root ${root}`,\n    );\n  }\n  // Walk every component from root to target (inclusive) and lstat each.\n  const segments = rel.length === 0 ? [] : rel.split(path.sep);\n  let current = root;\n  const componentsToCheck = [current];\n  for (const seg of segments) {\n    current = path.join(current, seg);\n    componentsToCheck.push(current);\n  }\n  for (const component of componentsToCheck) {\n    let stat: import(\"node:fs\").Stats;\n    try {\n      stat = await fs.lstat(component);\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n        // Not yet created — that's fine; caller's readFile/mkdir handles it.\n        continue;\n      }\n      throw err;\n    }\n    if (stat.isSymbolicLink()) {\n      throw new Error(\n        `connector state path component ${component} is a symlink; refusing to follow`,\n      );\n    }\n  }\n}\n\n/**\n * Read the persisted state for a single connector.\n *\n * Returns `null` if the file does not exist (ENOENT). Throws on any other\n * I/O error or on shape mismatch — operators should see corruption loudly.\n *\n * Rejects symlinks anywhere on the path so a planted symlink can't redirect\n * reads outside the memory root. (PR #724 review.)\n */\nexport async function readConnectorState(\n  memoryDir: string,\n  id: string,\n): Promise<ConnectorState | null> {\n  const filePath = resolveConnectorStatePath(memoryDir, id);\n  await assertNoSymlinkOnPath(memoryDir, filePath);\n  let raw: string;\n  try {\n    raw = await fs.readFile(filePath, \"utf-8\");\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n    throw err;\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (err) {\n    throw new ConnectorStateCorruptionError(\n      `connector state at ${filePath} is not valid JSON: ${(err as Error).message}`,\n    );\n  }\n  if (!isConnectorStateShape(parsed)) {\n    throw new ConnectorStateCorruptionError(\n      `connector state at ${filePath} does not match ConnectorState shape`,\n    );\n  }\n  if (parsed.id !== id) {\n    throw new ConnectorStateCorruptionError(\n      `connector state at ${filePath} has mismatched id ${JSON.stringify(parsed.id)}; expected ${JSON.stringify(id)}`,\n    );\n  }\n  return parsed;\n}\n\n/**\n * Write state atomically: create-tmp + rename. Never destroys the previous\n * file before the new one is in place — see CLAUDE.md gotcha #54.\n *\n * We accept `Omit<ConnectorState, \"updatedAt\">` and stamp `updatedAt`\n * ourselves so callers can't accidentally persist a stale timestamp.\n */\nexport async function writeConnectorState(\n  memoryDir: string,\n  id: string,\n  state: Omit<ConnectorState, \"updatedAt\">,\n): Promise<ConnectorState> {\n  if (!isValidConnectorId(id)) {\n    throw new TypeError(\n      `invalid connector id ${JSON.stringify(id)} — must match /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/`,\n    );\n  }\n  if (state.id !== id) {\n    throw new Error(\n      `writeConnectorState(): state.id ${JSON.stringify(state.id)} does not match id argument ${JSON.stringify(id)}`,\n    );\n  }\n  // Full boundary validation. Persisting an out-of-shape record would brick\n  // the connector's cursor file: subsequent `readConnectorState` calls would\n  // throw `ConnectorStateCorruptionError` until manual repair. JS callers\n  // bypassing TS types must be rejected here, not later. (PR #724 review.)\n  if (!VALID_SYNC_STATUSES.has(state.lastSyncStatus as ConnectorSyncStatus)) {\n    throw new Error(\n      `writeConnectorState(): lastSyncStatus must be one of ${[...VALID_SYNC_STATUSES].join(\", \")}, got ${JSON.stringify(state.lastSyncStatus)}`,\n    );\n  }\n  if (state.lastSyncAt !== null && typeof state.lastSyncAt !== \"string\") {\n    throw new Error(\n      `writeConnectorState(): lastSyncAt must be a string or null, got ${typeof state.lastSyncAt}`,\n    );\n  }\n  if (state.cursor !== null) {\n    if (typeof state.cursor !== \"object\") {\n      throw new Error(`writeConnectorState(): cursor must be an object or null`);\n    }\n    if (\n      typeof state.cursor.kind !== \"string\" ||\n      typeof state.cursor.value !== \"string\" ||\n      typeof state.cursor.updatedAt !== \"string\"\n    ) {\n      throw new Error(\n        `writeConnectorState(): cursor must have string kind, value, and updatedAt`,\n      );\n    }\n  }\n  if (\n    typeof state.totalDocsImported !== \"number\" ||\n    !Number.isInteger(state.totalDocsImported) ||\n    state.totalDocsImported < 0\n  ) {\n    throw new Error(\n      `writeConnectorState(): totalDocsImported must be a non-negative integer`,\n    );\n  }\n  if (state.lastSyncError !== undefined && typeof state.lastSyncError !== \"string\") {\n    throw new Error(`writeConnectorState(): lastSyncError must be a string when provided`);\n  }\n  const truncatedError =\n    state.lastSyncError !== undefined && state.lastSyncError.length > MAX_ERROR_LENGTH\n      ? state.lastSyncError.slice(0, MAX_ERROR_LENGTH)\n      : state.lastSyncError;\n\n  const finalState: ConnectorState = {\n    id: state.id,\n    cursor: state.cursor,\n    lastSyncAt: state.lastSyncAt,\n    lastSyncStatus: state.lastSyncStatus,\n    ...(truncatedError !== undefined ? { lastSyncError: truncatedError } : {}),\n    totalDocsImported: state.totalDocsImported,\n    updatedAt: new Date().toISOString(),\n  };\n\n  const dir = resolveConnectorsDir(memoryDir);\n  const targetPath = path.join(dir, `${id}.json`);\n  // Reject planted symlinks before mkdir/write so a redirected target can't\n  // overwrite an arbitrary file outside the memory root. (PR #724 review.)\n  await assertNoSymlinkOnPath(memoryDir, targetPath);\n  await fs.mkdir(dir, { recursive: true });\n  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n\n  const body = `${JSON.stringify(finalState, null, 2)}\\n`;\n  try {\n    await fs.writeFile(tmpPath, body, { encoding: \"utf-8\", mode: 0o600 });\n    await fs.rename(tmpPath, targetPath);\n  } catch (err) {\n    // Best-effort cleanup of the tmp file. Never touch `targetPath` — the\n    // previous good state must remain readable on failure.\n    try {\n      await fs.unlink(tmpPath);\n    } catch {\n      // ignore\n    }\n    throw err;\n  }\n  return finalState;\n}\n\n/**\n * Enumerate every persisted connector state. Returns an empty array when\n * the directory does not exist yet (clean install, no syncs ever run).\n *\n * Files that do not match the `<id>.json` naming rule are skipped — this\n * keeps stray editor backups (`.json~`, `.swp`) from breaking enumeration.\n *\n * Corruption (unparseable JSON, shape mismatch, id mismatch) is also\n * skipped so one bad file doesn't take down the listing. Operators\n * inspecting `state/connectors/` can still see the offending file by hand.\n *\n * **Genuine I/O failures (`EACCES`, `EIO`, etc.) are NOT swallowed** —\n * silently returning an incomplete state set would make active connectors\n * appear missing and trigger duplicate ingestion on the next scheduler tick.\n * (PR #724 review.)\n */\nexport async function listConnectorStates(memoryDir: string): Promise<ConnectorState[]> {\n  const dir = resolveConnectorsDir(memoryDir);\n  // Refuse to enumerate through a symlinked state directory — a planted\n  // symlink at <memoryDir>/state or <memoryDir>/state/connectors would\n  // otherwise let reads escape the memory root. (PR #724 review.)\n  await assertNoSymlinkOnPath(memoryDir, dir);\n  let entries: string[];\n  try {\n    entries = await fs.readdir(dir);\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n    throw err;\n  }\n  const out: ConnectorState[] = [];\n  for (const entry of entries) {\n    if (!entry.endsWith(\".json\")) continue;\n    const id = entry.slice(0, -\".json\".length);\n    if (!isValidConnectorId(id)) continue;\n    try {\n      const state = await readConnectorState(memoryDir, id);\n      if (state !== null) out.push(state);\n    } catch (err) {\n      if (err instanceof ConnectorStateCorruptionError) {\n        // Skip corrupt files; preserve availability of the rest.\n        continue;\n      }\n      // Anything else (EACCES, EIO, ENOTDIR, ...) is a real operational\n      // failure. Fail loudly so the scheduler / CLI can surface it.\n      throw err;\n    }\n  }\n  out.sort((a, b) => a.id.localeCompare(b.id));\n  return out;\n}\n\n/**\n * Test-only helper: resolve where a given connector's state lives. Exported\n * so tests can assert the on-disk layout without duplicating the path math.\n * Not part of the stable public API.\n *\n * @internal\n */\nexport function _connectorStatePathForTest(memoryDir: string, id: string): string {\n  return resolveConnectorStatePath(memoryDir, id);\n}\n","/**\n * @remnic/core — Live Connectors Framework (issue #683 PR 1/N)\n *\n * Defines the contract that every \"live\" connector (Drive, Notion, Gmail,\n * GitHub, ...) must satisfy. A live connector is **continuous**: it runs on a\n * schedule, persists a cursor to disk, and ingests *new* documents since the\n * last sync. This is distinct from one-shot importers in\n * `packages/remnic-core/src/importers/` which transform an entire export file\n * in a single pass.\n *\n * This module is intentionally pure types + interfaces. No I/O. No schedule\n * wiring. Concrete connectors (PRs 2–5), the maintenance scheduler hookup\n * (separate PR), and the CLI surface (PR 6) are deferred.\n *\n * Naming caveat: `packages/remnic-core/src/connectors/` is already scoped to\n * the Codex marketplace integration. The live-connector framework lives under\n * the `live/` subdirectory to avoid collision. Do not import Codex symbols\n * from here, and do not import live-connector symbols from the Codex code.\n */\n\n/**\n * Free-form connector configuration. Validated by each connector's\n * `validateConfig` implementation. Stored alongside the cursor in the state\n * store. MUST be JSON-serializable: no functions, no class instances, no\n * circular references.\n *\n * Connectors MUST NOT persist secrets here — credentials belong in OS keychain\n * / OAuth token storage (PR 2 design).\n */\nexport type ConnectorConfig = Record<string, unknown>;\n\n/**\n * Opaque cursor describing \"where the last sync left off\". Each connector\n * defines what `kind` and `value` mean (e.g. Drive: `{kind: \"pageToken\",\n * value: \"...\"}`, Gmail: `{kind: \"historyId\", value: \"...\"}`). The orchestrator\n * treats it as opaque and only round-trips it through the state store.\n *\n * `updatedAt` is an ISO 8601 timestamp set by the framework when the cursor is\n * written. It is informational — connectors MUST NOT use it to decide\n * monotonicity. They own the `value` semantics.\n */\nexport interface ConnectorCursor {\n  /** Connector-defined cursor kind (e.g. `\"pageToken\"`, `\"historyId\"`, `\"sinceTs\"`). */\n  readonly kind: string;\n  /** Connector-defined opaque cursor value. */\n  readonly value: string;\n  /** ISO 8601 timestamp of when this cursor was last written. */\n  readonly updatedAt: string;\n}\n\n/**\n * Provenance for a connector-ingested document. Required so downstream recall\n * can attribute facts back to their origin and avoid re-ingesting on the next\n * incremental pass.\n */\nexport interface ConnectorDocumentSource {\n  /** Stable connector id (matches `LiveConnector.id`). */\n  readonly connector: string;\n  /** Source-system identifier (Drive file id, Notion page id, Gmail msg id, ...). */\n  readonly externalId: string;\n  /** Optional source-system revision/version (etag, page version, history id). */\n  readonly externalRevision?: string;\n  /** Optional canonical URL pointing back at the source document. */\n  readonly externalUrl?: string;\n  /** ISO 8601 timestamp of when the connector fetched this document. */\n  readonly fetchedAt: string;\n}\n\n/**\n * A single document yielded by an incremental sync. Connectors are responsible\n * for chunking large source documents themselves if needed; the orchestrator\n * ingests `content` as a unit.\n */\nexport interface ConnectorDocument {\n  /** Connector-local stable id for this document. SHOULD match `source.externalId`. */\n  readonly id: string;\n  /** Optional human-readable title. */\n  readonly title?: string;\n  /** Body content. Plaintext or Markdown — connectors document their format. */\n  readonly content: string;\n  /** Provenance. Required. */\n  readonly source: ConnectorDocumentSource;\n}\n\n/**\n * Arguments passed to `syncIncremental`. The framework owns cursor/config\n * lifecycle; connectors only read these and return the next cursor.\n */\nexport interface SyncIncrementalArgs {\n  /** Last persisted cursor, or `null` on the first ever sync. */\n  readonly cursor: ConnectorCursor | null;\n  /** Validated connector config (already passed through `validateConfig`). */\n  readonly config: ConnectorConfig;\n  /** Optional abort signal. Connectors SHOULD honor it for cooperative cancellation. */\n  readonly abortSignal?: AbortSignal;\n}\n\n/**\n * Result of a single incremental sync pass.\n *\n * `newDocs` MAY be empty (no new documents since the last cursor). `nextCursor`\n * MUST always be returned — even on no-op syncs the framework persists it so\n * `updatedAt` reflects the most recent attempt.\n */\nexport interface SyncIncrementalResult {\n  readonly newDocs: ConnectorDocument[];\n  readonly nextCursor: ConnectorCursor;\n}\n\n/**\n * The contract every live connector implements.\n *\n * Connectors MUST be:\n *   - **Idempotent**: re-running with the same cursor MUST NOT duplicate\n *     documents. The `source.externalId` + `source.externalRevision` pair is\n *     used downstream for dedup.\n *   - **Read-only on the source**: live connectors never mutate the upstream\n *     system (no marking emails read, no editing Notion pages).\n *   - **Cancellable**: long-running syncs SHOULD periodically check\n *     `abortSignal.aborted` and bail cleanly.\n *   - **Privacy-aware**: connectors MUST NOT log document content. Logging\n *     metadata (counts, ids, timings) is fine.\n */\nexport interface LiveConnector {\n  /**\n   * Stable connector id. MUST match `CONNECTOR_ID_PATTERN` — lowercase\n   * alphanumeric plus dash, 1–64 chars, must start AND end with alphanumeric\n   * (no leading or trailing dash). The registry enforces this.\n   */\n  readonly id: string;\n  /** Short human-readable name shown in CLI / status output. */\n  readonly displayName: string;\n  /** Optional longer description. */\n  readonly description?: string;\n\n  /**\n   * Validate raw user-supplied config. MUST throw on malformed input — never\n   * silently default. The returned object is what gets persisted and passed\n   * back to `syncIncremental`. Connectors SHOULD strip unknown fields.\n   */\n  validateConfig(raw: unknown): ConnectorConfig;\n\n  /**\n   * Run one incremental sync pass. See `SyncIncrementalArgs` /\n   * `SyncIncrementalResult` for the contract.\n   */\n  syncIncremental(args: SyncIncrementalArgs): Promise<SyncIncrementalResult>;\n}\n\n/**\n * Regex enforcing the connector-id naming rule. Exported so connectors and\n * tests can validate ids consistently with the registry.\n *\n * Rule: lowercase alphanumeric + dash, 1..64 chars, must start AND end with\n * alphanumeric (no leading or trailing dash). Single-char ids are allowed.\n */\nexport const CONNECTOR_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;\n\n/**\n * Returns `true` if `id` is a syntactically valid connector id.\n */\nexport function isValidConnectorId(id: unknown): id is string {\n  return typeof id === \"string\" && CONNECTOR_ID_PATTERN.test(id);\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-74EMIVE4.js

@@ -0,0 +1,329 @@
+// src/capsule-cli.ts
+import path from "path";
+function parseCapsuleOutputFormat(raw) {
+  if (raw === void 0 || raw === null) return "text";
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw new Error(
+      `--format expects one of text, markdown, json; got ${JSON.stringify(raw)}`
+    );
+  }
+  const v = raw.trim();
+  if (v !== "text" && v !== "markdown" && v !== "json") {
+    throw new Error(
+      `--format expects one of text, markdown, json; got ${JSON.stringify(raw)}`
+    );
+  }
+  return v;
+}
+function parseCapsuleImportMode(raw) {
+  if (raw === void 0 || raw === null) return "skip";
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw new Error(
+      `--mode expects one of skip, overwrite, fork; got ${JSON.stringify(raw)}`
+    );
+  }
+  const v = raw.trim();
+  if (v !== "skip" && v !== "overwrite" && v !== "fork") {
+    throw new Error(
+      `--mode expects one of skip, overwrite, fork; got ${JSON.stringify(raw)}`
+    );
+  }
+  return v;
+}
+function parseCapsuleConflictMode(raw) {
+  if (raw === void 0 || raw === null) return "skip-conflicts";
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw new Error(
+      `--conflict-mode expects one of skip-conflicts, prefer-source, prefer-local; got ${JSON.stringify(raw)}`
+    );
+  }
+  const v = raw.trim();
+  if (v !== "skip-conflicts" && v !== "prefer-source" && v !== "prefer-local") {
+    throw new Error(
+      `--conflict-mode expects one of skip-conflicts, prefer-source, prefer-local; got ${JSON.stringify(raw)}`
+    );
+  }
+  return v;
+}
+var ISO_8601_RE = /^\d{4}-\d{2}-\d{2}(?:[Tt]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:[Zz]|[+-]\d{2}:?\d{2}))?$/;
+function parseCapsuleSince(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (typeof raw !== "string") {
+    throw new Error(
+      `--since expects an ISO 8601 timestamp; got ${JSON.stringify(raw)}`
+    );
+  }
+  if (raw.trim() === "") {
+    throw new Error(`--since expects an ISO 8601 timestamp; received empty string`);
+  }
+  if (!ISO_8601_RE.test(raw)) {
+    throw new Error(
+      `--since is not a valid ISO 8601 timestamp: ${raw}. Accepted forms: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SSZ, YYYY-MM-DDTHH:MM:SS\xB1HH:MM`
+    );
+  }
+  const ms = Date.parse(raw);
+  if (!Number.isFinite(ms)) {
+    throw new Error(`--since is not a valid ISO 8601 timestamp: ${raw}`);
+  }
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(raw);
+  if (m) {
+    const offsetMatch = /([+-])(\d{2}):?(\d{2})$/.exec(raw);
+    let displayMs = ms;
+    if (offsetMatch) {
+      const sign = offsetMatch[1] === "-" ? -1 : 1;
+      const offsetMin = sign * (Number(offsetMatch[2]) * 60 + Number(offsetMatch[3]));
+      displayMs = ms + offsetMin * 6e4;
+    }
+    const dd = new Date(displayMs);
+    if (dd.getUTCFullYear() !== Number(m[1]) || dd.getUTCMonth() + 1 !== Number(m[2]) || dd.getUTCDate() !== Number(m[3])) {
+      throw new Error(
+        `--since: calendar overflow \u2014 ${raw} normalises to a different calendar date`
+      );
+    }
+  }
+  return raw;
+}
+function parseCapsuleIncludeKinds(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (typeof raw !== "string") {
+    throw new Error(
+      `--include-kinds expects a comma-separated list of directory names; got ${JSON.stringify(raw)}`
+    );
+  }
+  if (raw.trim() === "") {
+    throw new Error(
+      `--include-kinds expects at least one non-empty kind name`
+    );
+  }
+  const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (parts.length === 0) {
+    throw new Error(`--include-kinds expects at least one non-empty kind name`);
+  }
+  for (const p of parts) {
+    if (p.includes("/") || p.includes("\\")) {
+      throw new Error(
+        `--include-kinds entries must be top-level directory names (no path separators): ${p}`
+      );
+    }
+  }
+  return [...new Set(parts)];
+}
+function parseCapsulePeers(raw) {
+  if (raw === void 0 || raw === null) return void 0;
+  if (typeof raw !== "string") {
+    throw new Error(
+      `--peers expects a comma-separated list of peer ids; got ${JSON.stringify(raw)}`
+    );
+  }
+  if (raw.trim() === "") {
+    throw new Error(`--peers expects at least one non-empty peer id`);
+  }
+  const parts = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (parts.length === 0) {
+    throw new Error(`--peers expects at least one non-empty peer id`);
+  }
+  for (const p of parts) {
+    if (p.includes("/") || p.includes("\\") || p === "." || p === "..") {
+      throw new Error(
+        `--peers entries must be plain id tokens (no path separators): ${p}`
+      );
+    }
+  }
+  return [...new Set(parts)];
+}
+function parseCapsuleExportOptions(nameArg, opts) {
+  if (typeof nameArg !== "string" || nameArg.trim() === "") {
+    throw new Error(
+      `capsule export: <name> is required (e.g. "remnic capsule export my-capsule")`
+    );
+  }
+  const name = nameArg.trim();
+  const out = typeof opts.out === "string" && opts.out.trim() !== "" ? opts.out.trim() : void 0;
+  const since = parseCapsuleSince(opts.since);
+  const includeKinds = parseCapsuleIncludeKinds(opts.includeKinds);
+  const peers = parseCapsulePeers(opts.peers);
+  return { name, out, since, includeKinds, peers };
+}
+function parseCapsuleImportOptions(archiveArg, opts) {
+  if (typeof archiveArg !== "string" || archiveArg.trim() === "") {
+    throw new Error(
+      `capsule import: <archive> path is required (e.g. "remnic capsule import /path/to/my-capsule.capsule.json.gz")`
+    );
+  }
+  const archive = archiveArg.trim();
+  const mode = parseCapsuleImportMode(opts.mode);
+  return { archive, mode };
+}
+function parseCapsuleMergeOptions(archiveArg, opts) {
+  if (typeof archiveArg !== "string" || archiveArg.trim() === "") {
+    throw new Error(
+      `capsule merge: <archive> path is required (e.g. "remnic capsule merge /path/to/my-capsule.capsule.json.gz")`
+    );
+  }
+  const archive = archiveArg.trim();
+  const conflictMode = parseCapsuleConflictMode(opts.conflictMode);
+  return { archive, conflictMode };
+}
+function parseCapsuleListOptions(opts, defaultCapsulesDir2) {
+  const format = parseCapsuleOutputFormat(opts.format);
+  const rawDir = typeof opts.dir === "string" && opts.dir.trim() !== "" ? opts.dir.trim() : void 0;
+  const capsulesDir = rawDir ?? defaultCapsulesDir2;
+  return { format, capsulesDir };
+}
+function parseCapsuleInspectOptions(archiveArg, opts) {
+  if (typeof archiveArg !== "string" || archiveArg.trim() === "") {
+    throw new Error(
+      `capsule inspect: <archive> path is required (e.g. "remnic capsule inspect my-capsule.capsule.json.gz")`
+    );
+  }
+  const archive = archiveArg.trim();
+  const format = parseCapsuleOutputFormat(opts.format);
+  return { archive, format };
+}
+function defaultCapsulesDir(memoryDir) {
+  return path.join(memoryDir, ".capsules");
+}
+function escapeMarkdownCell(v) {
+  return v.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+function renderCapsuleList(entries, format) {
+  if (format === "json") {
+    return JSON.stringify({ capsules: entries }, null, 2);
+  }
+  if (entries.length === 0) {
+    if (format === "markdown") return "_No capsule archives found._\n";
+    return "No capsule archives found.\n";
+  }
+  if (format === "markdown") {
+    const rows = entries.map((e) => {
+      const id = escapeMarkdownCell(e.id);
+      const date = escapeMarkdownCell(e.createdAt?.slice(0, 10) ?? "\u2014");
+      const ver = escapeMarkdownCell(e.pluginVersion ?? "\u2014");
+      const files = e.fileCount !== null ? String(e.fileCount) : "\u2014";
+      const desc = escapeMarkdownCell(
+        e.description != null && e.description.trim() !== "" ? e.description.trim() : "\u2014"
+      );
+      return `| \`${id}\` | ${date} | ${ver} | ${files} | ${desc} |`;
+    });
+    return [
+      "# Capsule archives",
+      "",
+      "| ID | Created | Version | Files | Description |",
+      "| -- | ------- | ------- | ----- | ----------- |",
+      ...rows,
+      ""
+    ].join("\n");
+  }
+  const lines = entries.map((e) => {
+    const date = e.createdAt?.slice(0, 10) ?? "\u2014";
+    const files = e.fileCount !== null ? `${e.fileCount} file${e.fileCount !== 1 ? "s" : ""}` : "? files";
+    const desc = e.description != null && e.description.trim() !== "" ? `  ${e.description.trim()}` : "";
+    return `${e.id}  [${date}] [${files}]${desc}`;
+  });
+  return lines.join("\n") + "\n";
+}
+function renderCapsuleInspect(manifest, format) {
+  if (format === "json") {
+    return JSON.stringify(manifest, null, 2);
+  }
+  const {
+    capsuleId,
+    version,
+    schemaVersion,
+    createdAt,
+    pluginVersion,
+    fileCount,
+    includesTranscripts,
+    description,
+    parentCapsule,
+    retrievalPolicy,
+    includes,
+    topFiles
+  } = manifest;
+  if (format === "markdown") {
+    const policyLines = Object.entries(retrievalPolicy.tierWeights ?? {}).map(
+      ([k, v]) => `  - ${k}: ${v}`
+    );
+    const policyBlock = policyLines.length > 0 ? policyLines.join("\n") : "  _(no tier weight overrides)_";
+    return [
+      `# Capsule: \`${capsuleId}\``,
+      "",
+      `**Version:** ${version}  `,
+      `**Schema version:** ${schemaVersion}  `,
+      `**Created:** ${createdAt ?? "\u2014"}  `,
+      `**Plugin version:** ${pluginVersion ?? "\u2014"}  `,
+      `**Files:** ${fileCount}  `,
+      `**Includes transcripts:** ${includesTranscripts ? "yes" : "no"}  `,
+      `**Parent capsule:** ${parentCapsule ?? "_none_"}  `,
+      `**Description:** ${description && description.trim() !== "" ? description.trim() : "_none_"}  `,
+      "",
+      "## Includes",
+      `- taxonomy: ${includes.taxonomy ? "yes" : "no"}`,
+      `- identityAnchors: ${includes.identityAnchors ? "yes" : "no"}`,
+      `- peerProfiles: ${includes.peerProfiles ? "yes" : "no"}`,
+      `- procedural: ${includes.procedural ? "yes" : "no"}`,
+      "",
+      "## Retrieval policy",
+      `- directAnswerEnabled: ${retrievalPolicy.directAnswerEnabled ? "yes" : "no"}`,
+      `- tierWeights:`,
+      policyBlock,
+      "",
+      ...topFiles.length > 0 ? [
+        `## Files (${fileCount} total, showing first ${topFiles.length})`,
+        ...topFiles.map((f) => `- \`${f}\``),
+        ""
+      ] : [`## Files (${fileCount} total)`, "_Empty capsule._", ""]
+    ].join("\n");
+  }
+  const lines = [
+    `Capsule: ${capsuleId}`,
+    `  version:          ${version}`,
+    `  schema:           ${schemaVersion}`,
+    `  created:          ${createdAt ?? "\u2014"}`,
+    `  plugin:           ${pluginVersion ?? "\u2014"}`,
+    `  files:            ${fileCount}`,
+    `  transcripts:      ${includesTranscripts ? "yes" : "no"}`,
+    `  parent:           ${parentCapsule ?? "(none)"}`,
+    `  description:      ${description && description.trim() !== "" ? description.trim() : "(none)"}`,
+    "",
+    `  includes.taxonomy:        ${includes.taxonomy ? "yes" : "no"}`,
+    `  includes.identityAnchors: ${includes.identityAnchors ? "yes" : "no"}`,
+    `  includes.peerProfiles:    ${includes.peerProfiles ? "yes" : "no"}`,
+    `  includes.procedural:      ${includes.procedural ? "yes" : "no"}`,
+    "",
+    `  policy.directAnswer:   ${retrievalPolicy.directAnswerEnabled ? "yes" : "no"}`
+  ];
+  const weights = Object.entries(retrievalPolicy.tierWeights ?? {});
+  if (weights.length > 0) {
+    for (const [k, v] of weights) {
+      lines.push(`  policy.tierWeight[${k}]: ${v}`);
+    }
+  } else {
+    lines.push(`  policy.tierWeights:    (none)`);
+  }
+  if (topFiles.length > 0) {
+    lines.push("", `  files (first ${topFiles.length} of ${fileCount}):`);
+    for (const f of topFiles) {
+      lines.push(`    ${f}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+export {
+  parseCapsuleOutputFormat,
+  parseCapsuleImportMode,
+  parseCapsuleConflictMode,
+  parseCapsuleSince,
+  parseCapsuleIncludeKinds,
+  parseCapsulePeers,
+  parseCapsuleExportOptions,
+  parseCapsuleImportOptions,
+  parseCapsuleMergeOptions,
+  parseCapsuleListOptions,
+  parseCapsuleInspectOptions,
+  defaultCapsulesDir,
+  renderCapsuleList,
+  renderCapsuleInspect
+};
+//# sourceMappingURL=chunk-74EMIVE4.js.map