@remnic/core 1.1.12 → 1.1.14

package/dist/connectors/index.d.ts

@@ -0,0 +1,444 @@
+export { MATERIALIZE_VERSION, MaterializeOptions, MaterializeResult, MemoryMdValidation, RolloutSummaryInput, SENTINEL_FILE, TMP_DIR, approximateTokenCount, describeMemoriesDir, ensureSentinel, materializeForNamespace, renderMemoryMd, renderMemorySummary, renderRawMemories, renderRolloutSummary, truncateToTokenBudget, validateMemoryMd } from './codex-materialize.js';
+export { RunMaterializeOptions, runCodexMaterialize } from './codex-materialize-runner.js';
+import { PluginConfig } from '../types.js';
+import '../index-DJ9QWMw-.js';
+
+/**
+ * Coerce the `installExtension` config value from a string (e.g. from CLI
+ * `--config installExtension=false`) to a proper boolean.
+ *
+ * Delegates to the generic `coerceBool` helper. Kept for backward compatibility.
+ */
+declare function coerceInstallExtension(value: unknown): boolean | undefined;
+
+/**
+ * codex-marketplace.ts — Codex marketplace installation support (#418)
+ *
+ * Provides types and functions for integrating Remnic with the Codex CLI
+ * marketplace system (`codex marketplace add`). This module handles:
+ *
+ *  - Generating a `marketplace.json` manifest describing Remnic as an
+ *    installable plugin in the Codex marketplace ecosystem.
+ *  - Validating marketplace manifest files against the expected schema.
+ *  - Writing manifests to disk atomically.
+ *  - Installing plugins from marketplace sources (GitHub, git, local, URL).
+ *
+ * Privacy
+ * -------
+ * This module does not persist any user content. It only reads package
+ * metadata (name, version, description) and writes public marketplace
+ * manifest files.
+ */
+
+/** Source type for marketplace installation. */
+type MarketplaceInstallType = "github" | "git" | "local" | "url";
+/** A single plugin entry within a marketplace manifest. */
+interface MarketplaceEntry {
+    /** Plugin name (e.g. "remnic"). */
+    name: string;
+    /** Semver version string. */
+    version: string;
+    /** Human-readable description. */
+    description: string;
+    /** Repository identifier (e.g. "joshuaswarren/remnic"). */
+    repository: string;
+    /** How this plugin should be installed. */
+    installType: MarketplaceInstallType;
+    /** Optional direct URL to the plugin manifest. */
+    manifestUrl?: string;
+    /** Optional entry point path within the repository. */
+    entry?: string;
+    /** Optional config schema reference. */
+    configSchema?: string;
+}
+/** Top-level marketplace manifest. */
+interface MarketplaceManifest {
+    /** Schema version. Must be 1. */
+    version: 1;
+    /** Marketplace name. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** Available plugins. */
+    plugins: MarketplaceEntry[];
+}
+/** Configuration for the marketplace subsystem. */
+interface MarketplaceConfig {
+    /** Whether marketplace features are enabled. Default: true. */
+    enabled: boolean;
+    /** Local path where marketplace data is cached. */
+    registryPath: string;
+    /** Whether to auto-update marketplace data on install. Default: false. */
+    autoUpdate: boolean;
+}
+/** Result of a marketplace install operation. */
+interface MarketplaceInstallResult {
+    /** Whether the install succeeded. */
+    ok: boolean;
+    /** Human-readable message. */
+    message: string;
+    /** Source that was installed from. */
+    source: string;
+    /** Source type. */
+    sourceType: MarketplaceInstallType;
+    /** Plugins that were discovered. */
+    pluginsFound: string[];
+    /** Errors encountered (empty on success). */
+    errors: string[];
+}
+/** Logger interface accepted by marketplace functions. */
+interface MarketplaceLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    debug?: (msg: string) => void;
+}
+/** Current marketplace schema version. */
+declare const MARKETPLACE_SCHEMA_VERSION: 1;
+/** Default marketplace manifest filename. */
+declare const MARKETPLACE_MANIFEST_FILENAME = "marketplace.json";
+/**
+ * Generate a marketplace manifest describing Remnic as an installable plugin.
+ *
+ * Reads version from the workspace root `package.json` at the resolved path,
+ * or falls back to a default version string.
+ */
+declare function generateMarketplaceManifest(options?: {
+    packageVersion?: string;
+}): MarketplaceManifest;
+/** Validation result with structured errors. */
+interface MarketplaceValidation {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate that an unknown value conforms to the MarketplaceManifest schema.
+ *
+ * Returns a typed manifest on success. Throws on invalid input with a
+ * descriptive error message listing all schema violations.
+ */
+declare function validateMarketplaceManifest(manifest: unknown): MarketplaceManifest;
+/**
+ * Non-throwing validation. Returns a structured result with error details.
+ */
+declare function checkMarketplaceManifest(manifest: unknown): MarketplaceValidation;
+/**
+ * Write a marketplace manifest to disk atomically.
+ *
+ * Uses write-to-temp-then-rename to avoid partial writes (CLAUDE.md gotcha #54).
+ */
+declare function writeMarketplaceManifest(outputDir: string, manifest: MarketplaceManifest): Promise<void>;
+/**
+ * Install from a marketplace source.
+ *
+ * Reads the marketplace.json from the given source, validates it, and
+ * returns a result describing what was found.
+ */
+declare function installFromMarketplace(source: string, sourceType: MarketplaceInstallType, config: PluginConfig, logger?: MarketplaceLogger): Promise<MarketplaceInstallResult>;
+
+/**
+ * @remnic/core — Connector Manager
+ *
+ * Metadata-driven registry for host adapters (Codex CLI, Claude Code, Cursor, etc.).
+ * Manages connector lifecycle: install, remove, configure, health.
+ */
+
+interface ConnectorManifest {
+    /** Unique connector ID (e.g. "claude-code", "codex-cli") */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Version */
+    version: string;
+    /** Description */
+    description: string;
+    /** Capabilities */
+    capabilities: ConnectorCapability;
+    /** Required config fields */
+    configSchema?: Record<string, string>;
+    /** Whether currently installed */
+    installed?: boolean;
+    /** Homepage URL */
+    homepage?: string;
+    /** Author */
+    author?: string;
+    /** Repository URL */
+    repository?: string;
+    /** Tags */
+    tags?: string[];
+    /**
+     * Whether this connector requires a bearer token for daemon authentication.
+     * When false (the default), installConnector will NOT generate or persist a
+     * token entry in tokens.json — credentials are never materialized on disk for
+     * connectors that use MCP, embedded, CLI, or SDK transports that don't need
+     * token auth.  Set to true only for HTTP connectors that actually authenticate
+     * requests with a bearer token (e.g. hermes, replit, generic-mcp).
+     */
+    requiresToken?: boolean;
+}
+interface ConnectorCapability {
+    /** Can observe conversations */
+    observe: boolean;
+    /** Can recall/query memories */
+    recall: boolean;
+    /** Can store memories */
+    store: boolean;
+    /** Can search */
+    search: boolean;
+    /** Can manage entities */
+    entities: boolean;
+    /** Supports real-time sync */
+    realtimeSync: boolean;
+    /** Supports batch operations */
+    batch: boolean;
+    /** Max memory budget in chars */
+    maxBudgetChars?: number;
+    /** Connection type */
+    connectionType: "mcp" | "http" | "cli" | "sdk" | "embedded";
+}
+interface ConnectorInstance {
+    /** Connector ID */
+    connectorId: string;
+    /** Resolved config */
+    config: Record<string, unknown>;
+    /** Status */
+    status: "installed" | "running" | "error" | "disabled";
+    /** Installed at timestamp */
+    installedAt?: string;
+    /** Error message if erro */
+    error?: string;
+}
+interface ConnectorRegistry {
+    /** Known connectors */
+    connectors: ConnectorManifest[];
+    /** Registry file path */
+    registryPath: string;
+}
+interface InstallOptions {
+    /** Connector ID to install */
+    connectorId: string;
+    /** Config values */
+    config?: Record<string, unknown>;
+    /** Memory directory */
+    memoryDir?: string;
+    /** Whether to force reinstall */
+    force?: boolean;
+}
+interface InstallResult {
+    /** Connector ID */
+    connectorId: string;
+    /** Status */
+    status: "installed" | "already_installed" | "config_required" | "error";
+    /** Config path */
+    configPath?: string;
+    /** Message */
+    message: string;
+}
+interface RemoveResult {
+    /** Connector ID */
+    connectorId: string;
+    /** Removed config path */
+    configPath: string;
+    /** Message */
+    message: string;
+    /** Status: "removed" on success, "error" if the removal failed partway, "not_found" if the connector was not installed, "skipped" if removal was aborted (e.g. malformed config). */
+    status: "removed" | "error" | "not_found" | "skipped";
+    /** Machine-readable skip reason (present when status === "skipped"). */
+    reason?: string;
+}
+interface DoctorResult {
+    /** Connector ID */
+    connectorId: string;
+    /** Checks */
+    checks: DoctorCheck[];
+    /** All healthy */
+    healthy: boolean;
+}
+interface DoctorCheck {
+    /** Check name */
+    name: string;
+    /** Passed */
+    ok: boolean;
+    /** Detail */
+    detail: string;
+}
+
+declare function getRegistryPath(): string;
+declare function loadRegistry(): ConnectorRegistry;
+declare function saveRegistry(registry: ConnectorRegistry): void;
+declare function listConnectors(): {
+    installed: ConnectorInstance[];
+    available: ConnectorManifest[];
+};
+declare function getConnectorToken(connectorId: string): string | undefined;
+declare function installConnector(options: InstallOptions): InstallResult;
+declare function removeConnector(connectorId: string): RemoveResult;
+interface HermesConfigResult {
+    updated: boolean;
+    skipped: boolean;
+    reason?: string;
+    configPath: string;
+    /**
+     * The exact byte-for-byte content of the config.yaml that existed BEFORE
+     * this upsert ran. `null` when the file did not exist (new file was created).
+     * `undefined` when the write was skipped (priorContent is irrelevant).
+     * Used by installConnector to roll back the YAML write if commitTokenEntry
+     * subsequently throws.
+     */
+    priorContent?: string | null;
+}
+/**
+ * Upsert the `remnic:` block in a Hermes profile config.yaml.
+ *
+ * Rules:
+ * - If the profile directory does not exist, skip with a warning (we do not
+ *   create arbitrary Hermes state).
+ * - If config.yaml does not exist, create it with only the remnic: block.
+ * - If config.yaml exists and already contains a `remnic:` block, update the
+ *   host/port/token lines in-place (line-based, preserves comments elsewhere).
+ * - If config.yaml exists with no `remnic:` block, append one.
+ * - Idempotent on repeated calls.
+ */
+declare function upsertHermesConfig(opts: {
+    profile: string;
+    host: string;
+    port: number;
+    token: string;
+}): HermesConfigResult;
+/**
+ * Remove the `remnic:` block from a Hermes profile config.yaml.
+ * Idempotent — if the block is absent, returns skipped.
+ */
+declare function removeHermesConfig(opts: {
+    profile: string;
+}): HermesConfigResult;
+declare function doctorConnector(connectorId: string): Promise<DoctorResult>;
+interface CodexMemoryExtensionPaths {
+    /** Resolved Codex home directory (e.g. `~/.codex`). */
+    codexHome: string;
+    /** Resolved Codex memories directory (`<codex_home>/memories`). */
+    memoriesDir: string;
+    /** Sibling extensions root (`<codex_home>/memories_extensions`). */
+    extensionsRoot: string;
+    /** The specific Remnic extension directory inside the extensions root. */
+    remnicExtensionDir: string;
+}
+interface InstallCodexMemoryExtensionOptions {
+    /** Optional override for `$CODEX_HOME`. Highest priority. */
+    codexHome?: string | null;
+    /** Optional override for the plugin-codex extension source directory. */
+    sourceDir?: string | null;
+}
+interface InstallCodexMemoryExtensionResult extends CodexMemoryExtensionPaths {
+    /** Absolute path to the installed `instructions.md`. */
+    instructionsPath: string;
+    /** Number of files copied. */
+    filesCopied: number;
+    /**
+     * Commit the install: permanently remove the backup of the prior extension
+     * (if one existed). Call this once the config write has succeeded.
+     */
+    commit(): void;
+    /**
+     * Roll back the install: restore the prior extension if one existed, or
+     * remove the newly-installed directory for a fresh install. Call this when
+     * a subsequent step (e.g. config write) has failed.
+     */
+    rollback(): void;
+}
+interface RemoveCodexMemoryExtensionOptions {
+    codexHome?: string | null;
+}
+interface RemoveCodexMemoryExtensionResult extends CodexMemoryExtensionPaths {
+    /** True if an existing `remnic` extension directory was removed. */
+    removed: boolean;
+}
+/**
+ * Resolve the Codex home directory. Precedence:
+ *   1. explicit `override` argument (from config)
+ *   2. `$CODEX_HOME` env var
+ *   3. `$HOME/.codex`, `$USERPROFILE/.codex`, or the OS home directory
+ */
+declare function resolveCodexHome(override?: string | null): string;
+/**
+ * Compute the Codex memories + memory-extensions layout for a given Codex home.
+ *
+ * The extensions root is computed as a **sibling** of the memories dir by
+ * taking `path.dirname(memoriesDir)` and joining `memories_extensions`. This
+ * mirrors Rust's `with_file_name("memories_extensions")` semantics used by
+ * Codex's `memory_extensions_root()`. Do NOT place the extension inside
+ * `<codex_home>/memories/`.
+ */
+declare function resolveCodexMemoryExtensionPaths(codexHomeOverride?: string | null): CodexMemoryExtensionPaths;
+/**
+ * Locate the plugin-codex `memories_extensions/remnic/` source directory on
+ * disk. Search order:
+ *   1. explicit `override`
+ *   2. resolve via `@remnic/plugin-codex` package (handles global npm installs)
+ *   3. sibling `node_modules/@remnic/plugin-codex` relative to this module
+ *   4. walk upward from this file's location (monorepo development)
+ *   5. walk upward from `process.cwd()` (monorepo fallback)
+ *
+ * Returns the absolute path or throws a descriptive error listing all paths
+ * searched when none exist.
+ */
+declare function locatePluginCodexExtensionSource(override?: string | null): string;
+/**
+ * Install the Remnic memory extension into `<codex_home>/memories_extensions/remnic/`
+ * atomically. The copy is written to a sibling `.remnic.tmp-<pid>-<ts>` directory
+ * and then renamed into place, so a concurrent Codex phase-2 run never sees a
+ * half-written extension.
+ *
+ * This function is **idempotent and scoped**: it only touches the `remnic`
+ * subfolder inside `memories_extensions/`. Adjacent extensions (other
+ * vendors) are never read, written, or removed.
+ */
+declare function installCodexMemoryExtension(options?: InstallCodexMemoryExtensionOptions): InstallCodexMemoryExtensionResult;
+/**
+ * Remove the Remnic memory extension. Only touches
+ * `<codex_home>/memories_extensions/remnic/` — never adjacent extensions.
+ */
+declare function removeCodexMemoryExtension(options?: RemoveCodexMemoryExtensionOptions): RemoveCodexMemoryExtensionResult;
+/**
+ * Resolve the path to ~/.remnic/connectors/weclone.json for the current user.
+ * Honours REMNIC_HOME / ENGRAM_HOME env overrides so tests can point the
+ * install at a temp dir without leaking into the real home directory.
+ *
+ * Always returns an absolute path via `path.resolve` so install-time and
+ * run-time resolution agree even when the override is a relative path like
+ * `tmp/remnic` (which would otherwise be interpreted against the caller's
+ * current working directory). Must stay in lockstep with the proxy CLI's
+ * `defaultConfigPath()` in @remnic/connector-weclone/src/cli.ts.
+ *
+ * `HOME=""` edge case: a nullish fallback would keep the
+ * empty string (empty is not nullish), which `path.resolve("", ...)` then
+ * interprets as CWD. `os.homedir()` by contrast falls back to the OS
+ * password database when HOME is empty, so the two code paths would
+ * disagree. We therefore treat empty HOME as absent and delegate to
+ * `os.homedir()` in both places — the same rule the proxy CLI follows.
+ */
+declare function resolveWeCloneProxyConfigPath(): string;
+interface WeCloneProxyConfig {
+    wecloneApiUrl: string;
+    wecloneModelName: string;
+    proxyPort: number;
+    remnicDaemonUrl: string;
+    remnicAuthToken?: string;
+    sessionStrategy: "caller-id" | "single";
+    memoryInjection: {
+        maxTokens: number;
+        position: "system-append" | "system-prepend";
+        template: string;
+    };
+}
+/**
+ * Compose a WeCloneProxyConfig from user-supplied overrides and any prior
+ * saved config, filling in defaults for every required field. The returned
+ * shape is exactly what the proxy's parseConfig() expects.
+ */
+declare function buildWeCloneProxyConfig(args: {
+    userConfig: Record<string, unknown>;
+    priorConfig: Record<string, unknown> | null;
+    authToken?: string;
+}): WeCloneProxyConfig;
+
+export { type CodexMemoryExtensionPaths, type ConnectorCapability, type ConnectorInstance, type ConnectorManifest, type ConnectorRegistry, type DoctorCheck, type DoctorResult, type InstallCodexMemoryExtensionOptions, type InstallCodexMemoryExtensionResult, type InstallOptions, type InstallResult, MARKETPLACE_MANIFEST_FILENAME, MARKETPLACE_SCHEMA_VERSION, type MarketplaceConfig, type MarketplaceEntry, type MarketplaceInstallResult, type MarketplaceInstallType, type MarketplaceLogger, type MarketplaceManifest, type MarketplaceValidation, type RemoveCodexMemoryExtensionOptions, type RemoveCodexMemoryExtensionResult, type RemoveResult, buildWeCloneProxyConfig, checkMarketplaceManifest, coerceInstallExtension, doctorConnector, generateMarketplaceManifest, getConnectorToken, getRegistryPath, installCodexMemoryExtension, installConnector, installFromMarketplace, listConnectors, loadRegistry, locatePluginCodexExtensionSource, removeCodexMemoryExtension, removeConnector, removeHermesConfig, resolveCodexHome, resolveCodexMemoryExtensionPaths, resolveWeCloneProxyConfigPath, saveRegistry, upsertHermesConfig, validateMarketplaceManifest, writeMarketplaceManifest };

package/dist/connectors/index.js

@@ -0,0 +1,115 @@
+import {
+  MARKETPLACE_MANIFEST_FILENAME,
+  MARKETPLACE_SCHEMA_VERSION,
+  buildWeCloneProxyConfig,
+  checkMarketplaceManifest,
+  doctorConnector,
+  generateMarketplaceManifest,
+  getConnectorToken,
+  getRegistryPath,
+  installCodexMemoryExtension,
+  installConnector,
+  installFromMarketplace,
+  listConnectors,
+  loadRegistry,
+  locatePluginCodexExtensionSource,
+  removeCodexMemoryExtension,
+  removeConnector,
+  removeHermesConfig,
+  resolveCodexHome,
+  resolveCodexMemoryExtensionPaths,
+  resolveWeCloneProxyConfigPath,
+  saveRegistry,
+  upsertHermesConfig,
+  validateMarketplaceManifest,
+  writeMarketplaceManifest
+} from "../chunk-326G7DJK.js";
+import "../chunk-MSWG7JI6.js";
+import {
+  runCodexMaterialize
+} from "../chunk-ME6ESPZU.js";
+import {
+  MATERIALIZE_VERSION,
+  SENTINEL_FILE,
+  TMP_DIR,
+  approximateTokenCount,
+  describeMemoriesDir,
+  ensureSentinel,
+  materializeForNamespace,
+  renderMemoryMd,
+  renderMemorySummary,
+  renderRawMemories,
+  renderRolloutSummary,
+  truncateToTokenBudget,
+  validateMemoryMd
+} from "../chunk-RHY3HH7P.js";
+import "../chunk-3UXOZBHV.js";
+import {
+  coerceInstallExtension
+} from "../chunk-PHK3HARR.js";
+import "../chunk-NNVTUXEB.js";
+import "../chunk-U3PN77QT.js";
+import "../chunk-7AAT6G4Q.js";
+import "../chunk-5UZXUTVO.js";
+import "../chunk-YNJHCGDT.js";
+import "../chunk-P7FMDTKL.js";
+import "../chunk-NN2DKE4T.js";
+import "../chunk-Q7P4WJDP.js";
+import "../chunk-SCU65EZI.js";
+import "../chunk-3KW65B36.js";
+import "../chunk-3HPAPHUK.js";
+import "../chunk-PFV5C235.js";
+import "../chunk-RULE4VG5.js";
+import "../chunk-DM2T26WE.js";
+import "../chunk-QSVPYQPG.js";
+import "../chunk-FVQJYWH7.js";
+import "../chunk-G7D6GZ5J.js";
+import "../chunk-FAAFWE4G.js";
+import "../chunk-QRNI5JBH.js";
+import "../chunk-4DJQYKMN.js";
+import "../chunk-XIG5PDM7.js";
+import "../chunk-2ODBA7MQ.js";
+import "../chunk-A6XUJE5D.js";
+import "../chunk-PZ5AY32C.js";
+export {
+  MARKETPLACE_MANIFEST_FILENAME,
+  MARKETPLACE_SCHEMA_VERSION,
+  MATERIALIZE_VERSION,
+  SENTINEL_FILE,
+  TMP_DIR,
+  approximateTokenCount,
+  buildWeCloneProxyConfig,
+  checkMarketplaceManifest,
+  coerceInstallExtension,
+  describeMemoriesDir,
+  doctorConnector,
+  ensureSentinel,
+  generateMarketplaceManifest,
+  getConnectorToken,
+  getRegistryPath,
+  installCodexMemoryExtension,
+  installConnector,
+  installFromMarketplace,
+  listConnectors,
+  loadRegistry,
+  locatePluginCodexExtensionSource,
+  materializeForNamespace,
+  removeCodexMemoryExtension,
+  removeConnector,
+  removeHermesConfig,
+  renderMemoryMd,
+  renderMemorySummary,
+  renderRawMemories,
+  renderRolloutSummary,
+  resolveCodexHome,
+  resolveCodexMemoryExtensionPaths,
+  resolveWeCloneProxyConfigPath,
+  runCodexMaterialize,
+  saveRegistry,
+  truncateToTokenBudget,
+  upsertHermesConfig,
+  validateMarketplaceManifest,
+  validateMemoryMd,
+  writeMarketplaceManifest
+};
+//# sourceMappingURL=index.js.map

package/dist/connectors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}