@remnic/core 9.3.686 → 9.3.688

package/src/connectors/paths.ts

@@ -4,46 +4,132 @@ import path from "node:path";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
 
 /**
- * Connector registry directory name. Kept under the legacy `engram` config
- * root for backward compatibility with existing installs; the rename to a
- * `remnic` path (with a legacy read-fallback) is tracked in #1518.
+ * Connector registry directory name. Kept under the canonical `remnic` config
+ * root for new installs; legacy installs that still live under `engram` are
+ * read-transparent via {@link getActiveConnectorsConfigRoot} (issue #1518).
  */
-export const REGISTRY_DIR_NAME = ".engram-connectors";
+export const REGISTRY_DIR_NAME = ".remnic-connectors";
 
 /**
- * Single source of truth for the connectors config root
- * (`$XDG_CONFIG_HOME/engram` or `~/.config/engram`). Issue #1527 flagged this
- * derivation as previously duplicated across call sites — add new callers
- * here, never re-derive the path inline.
+ * Legacy registry directory name from the engram era. Used only for the
+ * read-fallback so existing installs keep resolving until the user migrates.
+ */
+export const LEGACY_REGISTRY_DIR_NAME = ".engram-connectors";
+
+/**
+ * Config-root segment for the canonical (post-rename) layout. Issue #1518
+ * point 6: the path `~/.config/engram/...` is confusing when the product is
+ * called Remnic, so new writes land under `remnic/`.
+ */
+const CONFIG_ROOT_SEGMENT = "remnic";
+
+/**
+ * Config-root segment for the legacy engram-era layout. Read-fallback only.
+ */
+const LEGACY_CONFIG_ROOT_SEGMENT = "engram";
+
+/**
+ * Single source of truth for the canonical connectors config root
+ * (`$XDG_CONFIG_HOME/remnic` or `~/.config/remnic`). New writes ALWAYS go
+ * here. Issue #1527 flagged this derivation as previously duplicated across
+ * call sites — add new callers here, never re-derive the path inline.
  */
 export function getConnectorsConfigRoot(): string {
   const xdgConfigHome = readEnvVar("XDG_CONFIG_HOME");
   return xdgConfigHome
-    ? path.join(xdgConfigHome, "engram")
-    : path.join(resolveHomeDir(), ".config", "engram");
+    ? path.join(xdgConfigHome, CONFIG_ROOT_SEGMENT)
+    : path.join(resolveHomeDir(), ".config", CONFIG_ROOT_SEGMENT);
 }
 
-/** Path of the connector registry manifest file. */
+/**
+ * Legacy config root from the engram era (`$XDG_CONFIG_HOME/engram` or
+ * `~/.config/engram`). Exposed for tests and the migration path only —
+ * production code should call {@link getActiveConnectorsConfigRoot} so the
+ * read-fallback is applied uniformly.
+ */
+export function getLegacyConnectorsConfigRoot(): string {
+  const xdgConfigHome = readEnvVar("XDG_CONFIG_HOME");
+  return xdgConfigHome
+    ? path.join(xdgConfigHome, LEGACY_CONFIG_ROOT_SEGMENT)
+    : path.join(resolveHomeDir(), ".config", LEGACY_CONFIG_ROOT_SEGMENT);
+}
+
+/**
+ * Read-time fallback: pick the config root that actually holds (or will hold)
+ * the connector registry.
+ *
+ *   1. Canonical `remnic/` root when its `.remnic-connectors` registry dir
+ *      already exists (post-migration, or a fresh install that has already
+ *      written its first connector).
+ *   2. Legacy `engram/` root when ONLY its `.engram-connectors` registry dir
+ *      exists — an existing install we keep reading in place until the user
+ *      runs `remnic migrate`.
+ *   3. Canonical `remnic/` root otherwise (fresh install with no registry on
+ *      disk yet) so the first write lands at the new path.
+ *
+ * The probe looks for the REGISTRY SUBDIR (`.remnic-connectors` /
+ * `.engram-connectors`), not the bare config root. The config root
+ * `~/.config/remnic/` is created by unrelated daemon setup (e.g. the daemon's
+ * own `config.json`), so probing the bare root would falsely resolve to
+ * remnic and hide connector data that still lives under
+ * `~/.config/engram/.engram-connectors/` (cursor review round 1, #1620).
+ *
+ * This is a READ-time fallback. Writes go to whichever root this returns, so
+ * a legacy install keeps its data colocated for the active session; a fresh
+ * install writes straight to `remnic/`.
+ */
+export function getActiveConnectorsConfigRoot(): string {
+  const canonical = getConnectorsConfigRoot();
+  if (fs.existsSync(path.join(canonical, REGISTRY_DIR_NAME))) return canonical;
+  const legacy = getLegacyConnectorsConfigRoot();
+  if (fs.existsSync(path.join(legacy, LEGACY_REGISTRY_DIR_NAME))) return legacy;
+  return canonical;
+}
+
+/**
+ * Path of the connector registry manifest file. The registry subdir name
+ * (`.remnic-connectors` vs the legacy `.engram-connectors`) is chosen from the
+ * active root so a pre-rename install reads its existing files without a
+ * rename-side migration step (#1518).
+ */
 export function getRegistryPath(): string {
-  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, "registry.json");
+  const root = getActiveConnectorsConfigRoot();
+  const dirName = root === getConnectorsConfigRoot() ? REGISTRY_DIR_NAME : LEGACY_REGISTRY_DIR_NAME;
+  return path.join(root, dirName, "registry.json");
 }
 
-/** Directory holding one `<connector-id>.json` per installed connector. */
+/**
+ * Directory holding one `<connector-id>.json` per installed connector. The
+ * registry subdir name follows the active root (see {@link getRegistryPath}).
+ */
 export function getConnectorsDir(): string {
-  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, "connectors");
+  const root = getActiveConnectorsConfigRoot();
+  const dirName = root === getConnectorsConfigRoot() ? REGISTRY_DIR_NAME : LEGACY_REGISTRY_DIR_NAME;
+  return path.join(root, dirName, "connectors");
 }
 
 /**
  * Sticky-legacy evidence for `emitLegacyTools` (issue #1550): any persisted
- * connector entry under the legacy engram connectors dir means an existing
- * install whose clients may still address engram_* aliases. Missing or
- * unreadable dir means fresh install — no evidence, no aliases.
+ * connector entry under the LEGACY engram registry means an existing install
+ * whose clients may still address engram_* aliases. Missing or unreadable
+ * legacy dir means fresh install — no evidence, no aliases.
+ *
+ * Probes ONLY the legacy engram registry (`$XDG_CONFIG_HOME/engram/.engram-connectors`),
+ * never the active/canonical root. A fresh post-rename install that just
+ * wrote its first connector under `remnic/.remnic-connectors/` is NOT legacy
+ * evidence — counting it would flip `resolveEmitLegacyTools` to true and
+ * advertise deprecated `engram.*` aliases to users who never had them
+ * (#1620 review, codex P2). An unmigrated install still reports its entries
+ * here because its data lives under the engram tree.
  */
 export function hasLegacyConnectorEntries(): boolean {
   try {
-    return fs
-      .readdirSync(getConnectorsDir())
-      .some((name) => name.endsWith(".json"));
+    const legacyDir = path.join(
+      getLegacyConnectorsConfigRoot(),
+      LEGACY_REGISTRY_DIR_NAME,
+      "connectors",
+    );
+    return fs.readdirSync(legacyDir).some((name) => name.endsWith(".json"));
   } catch {
     return false;
   }

package/src/memory-extension/claude-code-publisher.ts

@@ -17,6 +17,7 @@ export class ClaudeCodeMemoryExtensionPublisher implements MemoryExtensionPublis
   readonly hostId = "claude-code";
 
   static readonly capabilities: PublisherCapabilities = {
+    isStub: true,
     instructionsMd: false,
     skillsFolder: false,
     citationFormat: false,

package/src/memory-extension/codex-publisher.ts

@@ -53,6 +53,7 @@ export class CodexMemoryExtensionPublisher implements MemoryExtensionPublisher {
   readonly hostId = "codex";
 
   static readonly capabilities: PublisherCapabilities = {
+    isStub: false,
     instructionsMd: true,
     skillsFolder: false,
     citationFormat: true,

package/src/memory-extension/hermes-publisher.ts

@@ -17,6 +17,7 @@ export class HermesMemoryExtensionPublisher implements MemoryExtensionPublisher
   readonly hostId = "hermes";
 
   static readonly capabilities: PublisherCapabilities = {
+    isStub: true,
     instructionsMd: false,
     skillsFolder: false,
     citationFormat: false,

package/src/memory-extension/types.ts

@@ -73,8 +73,19 @@ export interface PublishResult {
  * Declarative capability flags that describe what a given publisher
  * can produce. Useful for feature-gating UI or doctor output without
  * instantiating the publisher.
+ *
+ * `isStub` is the explicit declaration required by #1518: when true, the
+ * docs-code parity gate (`scripts/check-docs-parity.mjs`) refuses any
+ * automation claim ("installs the plugin", "configures mcp",
+ * "automatically …") in the publisher's mapped install docs, because a stub
+ * publisher writes nothing to disk. A publisher that implements any real
+ * artefact writes MUST set this false. The inferred "all flags false ⇒ stub"
+ * detection in the parity script remains as a backstop, but the explicit
+ * flag is now the source of truth.
  */
 export interface PublisherCapabilities {
+  /** Whether the publisher is an intentional no-op stub (writes nothing). */
+  readonly isStub: boolean;
   /** Whether the publisher writes an instructions.md file. */
   readonly instructionsMd: boolean;
   /** Whether the publisher populates a skills folder. */

package/dist/chunk-3BQOQYRB.js

@@ -1,33 +0,0 @@
-import {
-  readEnvVar,
-  resolveHomeDir
-} from "./chunk-JUC24CTX.js";
-
-// src/connectors/paths.ts
-import fs from "fs";
-import path from "path";
-var REGISTRY_DIR_NAME = ".engram-connectors";
-function getConnectorsConfigRoot() {
-  const xdgConfigHome = readEnvVar("XDG_CONFIG_HOME");
-  return xdgConfigHome ? path.join(xdgConfigHome, "engram") : path.join(resolveHomeDir(), ".config", "engram");
-}
-function getRegistryPath() {
-  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, "registry.json");
-}
-function getConnectorsDir() {
-  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, "connectors");
-}
-function hasLegacyConnectorEntries() {
-  try {
-    return fs.readdirSync(getConnectorsDir()).some((name) => name.endsWith(".json"));
-  } catch {
-    return false;
-  }
-}
-
-export {
-  getRegistryPath,
-  getConnectorsDir,
-  hasLegacyConnectorEntries
-};
-//# sourceMappingURL=chunk-3BQOQYRB.js.map

package/dist/chunk-3BQOQYRB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/connectors/paths.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\n\nimport { readEnvVar, resolveHomeDir } from \"../runtime/env.js\";\n\n/**\n * Connector registry directory name. Kept under the legacy `engram` config\n * root for backward compatibility with existing installs; the rename to a\n * `remnic` path (with a legacy read-fallback) is tracked in #1518.\n */\nexport const REGISTRY_DIR_NAME = \".engram-connectors\";\n\n/**\n * Single source of truth for the connectors config root\n * (`$XDG_CONFIG_HOME/engram` or `~/.config/engram`). Issue #1527 flagged this\n * derivation as previously duplicated across call sites — add new callers\n * here, never re-derive the path inline.\n */\nexport function getConnectorsConfigRoot(): string {\n  const xdgConfigHome = readEnvVar(\"XDG_CONFIG_HOME\");\n  return xdgConfigHome\n    ? path.join(xdgConfigHome, \"engram\")\n    : path.join(resolveHomeDir(), \".config\", \"engram\");\n}\n\n/** Path of the connector registry manifest file. */\nexport function getRegistryPath(): string {\n  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, \"registry.json\");\n}\n\n/** Directory holding one `<connector-id>.json` per installed connector. */\nexport function getConnectorsDir(): string {\n  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, \"connectors\");\n}\n\n/**\n * Sticky-legacy evidence for `emitLegacyTools` (issue #1550): any persisted\n * connector entry under the legacy engram connectors dir means an existing\n * install whose clients may still address engram_* aliases. Missing or\n * unreadable dir means fresh install — no evidence, no aliases.\n */\nexport function hasLegacyConnectorEntries(): boolean {\n  try {\n    return fs\n      .readdirSync(getConnectorsDir())\n      .some((name) => name.endsWith(\".json\"));\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AASV,IAAM,oBAAoB;AAQ1B,SAAS,0BAAkC;AAChD,QAAM,gBAAgB,WAAW,iBAAiB;AAClD,SAAO,gBACH,KAAK,KAAK,eAAe,QAAQ,IACjC,KAAK,KAAK,eAAe,GAAG,WAAW,QAAQ;AACrD;AAGO,SAAS,kBAA0B;AACxC,SAAO,KAAK,KAAK,wBAAwB,GAAG,mBAAmB,eAAe;AAChF;AAGO,SAAS,mBAA2B;AACzC,SAAO,KAAK,KAAK,wBAAwB,GAAG,mBAAmB,YAAY;AAC7E;AAQO,SAAS,4BAAqC;AACnD,MAAI;AACF,WAAO,GACJ,YAAY,iBAAiB,CAAC,EAC9B,KAAK,CAAC,SAAS,KAAK,SAAS,OAAO,CAAC;AAAA,EAC1C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}