@remnic/core 9.3.671 → 9.3.673

package/src/emit-legacy-tools.test.ts

@@ -0,0 +1,297 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  resolveEmitLegacyTools,
+  resolveNamespaceCatalogEnabled,
+} from "./emit-legacy-tools.js";
+
+/**
+ * Run `body` with XDG_CONFIG_HOME pointing at a throwaway dir so the
+ * sticky-legacy `hasLegacyConnectorEntries()` check inside the resolvers
+ * never reads the real machine state. `withLegacyEntry` seeds one
+ * persisted connector file under the standard
+ * `$XDG_CONFIG_HOME/engram/.engram-connectors/connectors/` layout.
+ */
+function withIsolatedConnectorsDir<T>(
+  withLegacyEntry: boolean,
+  body: () => T,
+): T {
+  const prev = process.env.XDG_CONFIG_HOME;
+  const root = mkdtempSync(path.join(tmpdir(), "emit-legacy-tools-test-"));
+  process.env.XDG_CONFIG_HOME = root;
+  try {
+    if (withLegacyEntry) {
+      const dir = path.join(root, "engram", ".engram-connectors", "connectors");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(path.join(dir, "codex-cli.json"), "{}\n");
+    }
+    return body();
+  } finally {
+    if (prev === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = prev;
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ============================================================================
+// resolveEmitLegacyTools
+// ============================================================================
+
+test("resolveEmitLegacyTools: fresh install with absent raw falls through to sticky-legacy (false)", () => {
+  // No legacy connector evidence on disk → sticky-legacy returns false.
+  withIsolatedConnectorsDir(false, () => {
+    assert.equal(resolveEmitLegacyTools(false, {}), false);
+    // Same shape with legacy connector evidence → sticky-legacy true.
+  });
+  withIsolatedConnectorsDir(true, () => {
+    assert.equal(resolveEmitLegacyTools(false, {}), true);
+  });
+});
+
+test("resolveEmitLegacyTools: explicit operator opt-out via raw honored", () => {
+  // Raw has the key with a real value (false) and configValue agrees.
+  withIsolatedConnectorsDir(false, () => {
+    assert.equal(
+      resolveEmitLegacyTools(false, { emitLegacyTools: false }),
+      false,
+      "raw operator opt-out via file is honored",
+    );
+    // Even on a sticky-legacy true install, raw false wins.
+  });
+  withIsolatedConnectorsDir(true, () => {
+    assert.equal(
+      resolveEmitLegacyTools(false, { emitLegacyTools: false }),
+      false,
+      "raw operator opt-out overrides sticky-legacy",
+    );
+  });
+});
+
+test("resolveEmitLegacyTools: raw null/undefined treated as absent (round-2 review)", () => {
+  withIsolatedConnectorsDir(false, () => {
+    // Fresh install: raw null + merged null → sticky-legacy false.
+    assert.equal(
+      resolveEmitLegacyTools(null, { emitLegacyTools: null }),
+      false,
+      "fresh install with raw null resolves to false via sticky-legacy",
+    );
+    assert.equal(
+      resolveEmitLegacyTools(undefined, { emitLegacyTools: undefined }),
+      false,
+      "fresh install with raw undefined resolves to false via sticky-legacy",
+    );
+    assert.equal(
+      resolveEmitLegacyTools(undefined, { emitLegacyTools: null }),
+      false,
+      "mixed null/undefined in raw resolves to false via sticky-legacy",
+    );
+  });
+  withIsolatedConnectorsDir(true, () => {
+    // Upgraded install: raw null + sticky evidence → true.
+    assert.equal(
+      resolveEmitLegacyTools(null, { emitLegacyTools: null }),
+      true,
+      "upgraded install with raw null resolves to true via sticky-legacy",
+    );
+    assert.equal(
+      resolveEmitLegacyTools(undefined, { emitLegacyTools: undefined }),
+      true,
+      "upgraded install with raw undefined resolves to true via sticky-legacy",
+    );
+  });
+});
+
+test("resolveEmitLegacyTools: runtime true overrides schema default (round-2 review)", () => {
+  // Schema default is `false`. When raw is missing the key but merged
+  // carries `true` (runtime gateway set it), the resolver honors the
+  // runtime override instead of dropping it as schema-default
+  // materialization.
+  withIsolatedConnectorsDir(false, () => {
+    assert.equal(
+      resolveEmitLegacyTools(true, {}),
+      true,
+      "merged true with empty raw treated as runtime operator intent",
+    );
+    // Merged false (the schema default) with empty raw → sticky fallback.
+    assert.equal(
+      resolveEmitLegacyTools(false, {}),
+      false,
+      "merged false (schema default) with empty raw falls through to sticky-legacy",
+    );
+  });
+});
+
+test("resolveEmitLegacyTools: null raw passed directly (not via undefined) is normalized (round-3 review)", () => {
+  withIsolatedConnectorsDir(false, () => {
+    // Null raw + merged schema-default false → sticky-legacy fallback (no throw).
+    assert.equal(
+      resolveEmitLegacyTools(false, null),
+      false,
+      "null raw with emitLegacyTools merged schema default falls through to sticky-legacy",
+    );
+    // Null raw + emitLegacyTools merged true (runtime intent) → honored.
+    assert.equal(
+      resolveEmitLegacyTools(true, null),
+      true,
+      "null raw with emitLegacyTools runtime true honored as operator intent",
+    );
+  });
+  withIsolatedConnectorsDir(true, () => {
+    assert.equal(
+      resolveEmitLegacyTools(false, null),
+      true,
+      "null raw with legacy evidence keeps aliases on",
+    );
+  });
+});
+
+test("resolveEmitLegacyTools: runtime-over-file precedence (round-4 review)", () => {
+  // File says false, runtime sets true → merged configValue (true) wins.
+  withIsolatedConnectorsDir(false, () => {
+    assert.equal(
+      resolveEmitLegacyTools(true, { emitLegacyTools: false }),
+      true,
+      "runtime true overrides file false (rawOperatorConfig has the key)",
+    );
+    // Symmetric: file says true, runtime says false → merged false wins.
+    assert.equal(
+      resolveEmitLegacyTools(false, { emitLegacyTools: true }),
+      false,
+      "runtime false overrides file true",
+    );
+  });
+});
+
+test("resolveEmitLegacyTools: raw has key with non-boolean value coerced or throws", () => {
+  // Boolean-like strings coerce; garbage throws via coerceBooleanLikeOrThrow.
+  assert.equal(
+    resolveEmitLegacyTools("true", {}),
+    true,
+    "string 'true' coerces to true",
+  );
+  assert.equal(
+    resolveEmitLegacyTools("false", {}),
+    false,
+    "string 'false' coerces to false",
+  );
+  assert.equal(
+    resolveEmitLegacyTools(1, {}),
+    true,
+    "number 1 coerces to true",
+  );
+  assert.equal(
+    resolveEmitLegacyTools(0, {}),
+    false,
+    "number 0 coerces to false",
+  );
+  assert.throws(
+    () => resolveEmitLegacyTools("maybe", {}),
+    /emitLegacyTools must be a boolean-like value/,
+    "unrecognized string throws via coerceBooleanLikeOrThrow",
+  );
+  assert.throws(
+    () => resolveEmitLegacyTools(2, {}),
+    /emitLegacyTools must be a boolean-like value/,
+    "unrecognized number throws via coerceBooleanLikeOrThrow",
+  );
+});
+
+test("resolveEmitLegacyTools: env var overrides (REMNIC_ preferred, ENGRAM_ legacy)", () => {
+  const prevRemnic = process.env.REMNIC_EMIT_LEGACY_TOOLS;
+  const prevEngram = process.env.ENGRAM_EMIT_LEGACY_TOOLS;
+  try {
+    process.env.REMNIC_EMIT_LEGACY_TOOLS = "false";
+    assert.equal(resolveEmitLegacyTools(undefined, undefined), false);
+    process.env.REMNIC_EMIT_LEGACY_TOOLS = "true";
+    assert.equal(resolveEmitLegacyTools(undefined, undefined), true);
+    delete process.env.REMNIC_EMIT_LEGACY_TOOLS;
+    process.env.ENGRAM_EMIT_LEGACY_TOOLS = "false";
+    assert.equal(resolveEmitLegacyTools(undefined, undefined), false);
+    process.env.ENGRAM_EMIT_LEGACY_TOOLS = "true";
+    assert.equal(resolveEmitLegacyTools(undefined, undefined), true);
+  } finally {
+    if (prevRemnic === undefined) delete process.env.REMNIC_EMIT_LEGACY_TOOLS;
+    else process.env.REMNIC_EMIT_LEGACY_TOOLS = prevRemnic;
+    if (prevEngram === undefined) delete process.env.ENGRAM_EMIT_LEGACY_TOOLS;
+    else process.env.ENGRAM_EMIT_LEGACY_TOOLS = prevEngram;
+  }
+});
+
+// ============================================================================
+// resolveNamespaceCatalogEnabled
+// ============================================================================
+
+test("resolveNamespaceCatalogEnabled: default is true when absent", () => {
+  assert.equal(
+    resolveNamespaceCatalogEnabled(undefined, undefined),
+    true,
+    "absent configValue + absent raw → schema default true",
+  );
+  assert.equal(
+    resolveNamespaceCatalogEnabled(undefined, {}),
+    true,
+    "absent configValue + empty raw → schema default true",
+  );
+  assert.equal(
+    resolveNamespaceCatalogEnabled(true, {}),
+    true,
+    "merged true (schema default) with empty raw → fall through to default",
+  );
+});
+
+test("resolveNamespaceCatalogEnabled: merged false (different from schema default) honored as runtime intent", () => {
+  // Schema default is true. A merged `false` from the runtime API is
+  // operator intent to disable → honor it even though the schema default
+  // would be `true`.
+  assert.equal(
+    resolveNamespaceCatalogEnabled(false, {}),
+    false,
+    "merged false differs from schema default true — runtime operator intent honored",
+  );
+});
+
+test("resolveNamespaceCatalogEnabled: runtime (merged) value wins over raw file value", () => {
+  assert.equal(
+    resolveNamespaceCatalogEnabled(true, { namespaceCatalogEnabled: false }),
+    true,
+    "merged true wins over raw false (runtime-over-file precedence)",
+  );
+  assert.equal(
+    resolveNamespaceCatalogEnabled(false, { namespaceCatalogEnabled: true }),
+    false,
+    "merged false wins over raw true (runtime-over-file precedence)",
+  );
+});
+
+test("resolveNamespaceCatalogEnabled: null raw normalized (round-3 review)", () => {
+  // Schema default true. Merged false with null raw differs from default →
+  // runtime intent honored.
+  assert.equal(
+    resolveNamespaceCatalogEnabled(false, null),
+    false,
+    "null raw with merged false (runtime intent) honored",
+  );
+  // Merged true (schema default) with null raw → fall through to default.
+  assert.equal(
+    resolveNamespaceCatalogEnabled(true, null),
+    true,
+    "null raw with merged true (schema default) preserved",
+  );
+});
+
+test("resolveNamespaceCatalogEnabled: malformed values throw (rule #51)", () => {
+  assert.throws(
+    () => resolveNamespaceCatalogEnabled("maybe", {}),
+    /namespaceCatalogEnabled must be a boolean-like value/,
+    "unrecognized string throws via coerceBooleanLikeOrThrow",
+  );
+  assert.throws(
+    () => resolveNamespaceCatalogEnabled(2, {}),
+    /namespaceCatalogEnabled must be a boolean-like value/,
+    "unrecognized number throws via coerceBooleanLikeOrThrow",
+  );
+});

package/src/emit-legacy-tools.ts

@@ -0,0 +1,204 @@
+/**
+ * emit-legacy-tools — resolution cluster for the `emitLegacyTools` and
+ * `namespaceCatalogEnabled` config gates (issues #1427, #1499, #1550).
+ *
+ * Extracted from packages/remnic-core/src/config.ts (PR #1593, round 6)
+ * so the raw-vs-effective split, runtime-override precedence, and
+ * fileConfig-null normalization logic specific to these two gates
+ * stays out of the god-file `config.ts`. The export surface is exactly
+ * the two resolvers plus the `coerceBooleanLikeOrThrow` helper that
+ * wraps the local `coerceBooleanLike` — every other config gate in
+ * `parseConfig` keeps using its own inline coercion or the
+ * `coerceBooleanLike` already exported from
+ * `packages/remnic-core/src/connectors/coerce.ts`.
+ *
+ * Precedence (PR #1593 rounds 1-4, plus the null/loader hardening from
+ * rounds 3-5):
+ *
+ *   1. `configValue` (the first arg) is the MERGED config
+ *      (runtime-over-file via the
+ *      `{...fileConfig, ...api.pluginConfig}` spread in src/index.ts).
+ *      If it's a real boolean, it represents what the operator wants,
+ *      so honor it. We only fall through when it's the schema-default
+ *      materialization with no operator authoring in raw.
+ *   2. `rawOperatorConfig` (the second arg) is the operator-supplied
+ *      config block BEFORE the OpenClaw manifest layer applies schema
+ *      defaults — i.e. the file-backed `loadPluginConfigFromFile` output.
+ *      When raw has the key with a non-null/undefined value, the file
+ *      layer authored it. The merged `configValue` reflects the full
+ *      operator intent (file + runtime), so `configValue` is still
+ *      authoritative. raw presence is used only as the "operator
+ *      authored this key" signal — if raw is missing AND configValue
+ *      equals the schema default, only the schema layer materialized the
+ *      key (no operator intent anywhere) and we fall through to env /
+ *      sticky-legacy.
+ *   3. Legacy callers (raw undefined): trust configValue as before to
+ *      preserve the 121+ existing call sites that pass only one arg.
+ *
+ * Defensive normalization (PR #1593 round 3): JSON null on disk for the
+ * operator config block surfaces as `null` in rawOperatorConfig. Both
+ * resolvers normalize `null` to `{}` so the `"key" in rawOperatorConfig`
+ * check never throws. The file loader
+ * (`loadPluginConfigFromFile`) also normalizes null to undefined
+ * before reaching here.
+ */
+
+import { readEnvVar } from "./runtime/env.js";
+import { hasLegacyConnectorEntries } from "./connectors/paths.js";
+
+/**
+ * Coerce common string/number representations of a boolean to a real
+ * boolean. Returns `undefined` when the value cannot be interpreted, so
+ * callers can fail fast via `coerceBooleanLikeOrThrow`. Guards against
+ * the "string `false` is truthy" footgun (CLAUDE.md gotcha #36) when
+ * config values arrive from CLI/env/JSON sources where booleans are
+ * sometimes string-typed.
+ *
+ * Local copy — the canonical implementation lives in
+ * `packages/remnic-core/src/connectors/coerce.ts` but is private to that
+ * module's `coerceBool` export; duplicating here keeps the god-file
+ * contract clean (no cross-module pull) for the two gates that need
+ * fail-fast rejection.
+ */
+function coerceBooleanLike(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+    return undefined;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (
+      normalized === "true" ||
+      normalized === "1" ||
+      normalized === "yes" ||
+      normalized === "on"
+    ) {
+      return true;
+    }
+    if (
+      normalized === "false" ||
+      normalized === "0" ||
+      normalized === "no" ||
+      normalized === "off"
+    ) {
+      return false;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Coerce a present boolean-like gate value or fail fast. A PRESENT but
+ * unrecognized value ("fales", 2) is REJECTED rather than silently
+ * defaulting (CLAUDE.md rule #51) — shared by both resolvers below so
+ * the rejection behavior cannot drift between them.
+ */
+function coerceBooleanLikeOrThrow(label: string, value: unknown): boolean {
+  const coerced = coerceBooleanLike(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `${label} must be a boolean-like value (true/false/1/0/yes/no/on/off); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+/**
+ * Resolve the `emitLegacyTools` opt-out (issue #1427, defaults revised in
+ * #1550). Precedence: operator-set raw config, then merged (post-defaults)
+ * config, then the REMNIC_/ENGRAM_ env var, then a sticky-legacy default —
+ * `true` only when existing legacy connector entries are present on disk
+ * (`hasLegacyConnectorEntries`), `false` for fresh installs.
+ */
+export function resolveEmitLegacyTools(
+  configValue: unknown,
+  rawOperatorConfig: Record<string, unknown> | undefined | null,
+  runtimeSet?: ReadonlySet<string>,
+): boolean {
+  // Defensive null normalization — see file header for the rationale.
+  if (rawOperatorConfig === null) rawOperatorConfig = {};
+  // Schema default for `emitLegacyTools` is `false` (issue #1550).
+  const SCHEMA_DEFAULT = false;
+  // Round 8: `runtimeAuthored` is now informational only — the resolver
+  // does not consult it (see the comment on the check below). Kept as a
+  // local so the signature-bound `runtimeSet` parameter remains useful
+  // for future refactors and tests can read this state if needed.
+  const runtimeAuthored = runtimeSet?.has("emitLegacyTools") ?? false;
+  if (rawOperatorConfig !== undefined) {
+    if (configValue !== undefined && configValue !== null) {
+      const rawValue = (rawOperatorConfig as Record<string, unknown>).emitLegacyTools;
+      const rawAuthored =
+        "emitLegacyTools" in rawOperatorConfig &&
+        rawValue !== null &&
+        rawValue !== undefined;
+      // Round 8 (PR #1593): revert the runtimeAuthored gate. OpenClaw's
+      // `applyDefaults: true` materialization means api.pluginConfig keys
+      // can't reliably signal operator authorship; the schema-default
+      // comparison alone is the right signal (chatgpt-codex-connector P1
+      // on src/index.ts:1348, round 8).
+      if (rawAuthored || configValue !== SCHEMA_DEFAULT) {
+        return coerceBooleanLikeOrThrow("emitLegacyTools", configValue);
+      }
+    } else if ("emitLegacyTools" in rawOperatorConfig) {
+      const rawValue = (rawOperatorConfig as Record<string, unknown>).emitLegacyTools;
+      if (rawValue !== null && rawValue !== undefined) {
+        return coerceBooleanLikeOrThrow("emitLegacyTools", rawValue);
+      }
+    }
+  } else if (configValue !== undefined && configValue !== null) {
+    // Legacy caller (no rawOperatorConfig) — trust the merged value.
+    return coerceBooleanLikeOrThrow("emitLegacyTools", configValue);
+  }
+  const envRaw =
+    readEnvVar("REMNIC_EMIT_LEGACY_TOOLS") ?? readEnvVar("ENGRAM_EMIT_LEGACY_TOOLS");
+  if (envRaw !== undefined) {
+    return coerceBooleanLikeOrThrow("REMNIC_EMIT_LEGACY_TOOLS", envRaw);
+  }
+  return hasLegacyConnectorEntries();
+}
+
+/**
+ * Resolve the `namespaceCatalogEnabled` opt-out (issue #1499). Same
+ * raw-vs-effective split as `resolveEmitLegacyTools` — schema-default
+ * hardening at the helper level so adding a `false` default later cannot
+ * silently flip behavior on upgraded installs (#1550 class hardening).
+ */
+export function resolveNamespaceCatalogEnabled(
+  configValue: unknown,
+  rawOperatorConfig: Record<string, unknown> | undefined | null,
+  runtimeSet?: ReadonlySet<string>,
+): boolean {
+  // Defensive null normalization — see file header for the rationale.
+  if (rawOperatorConfig === null) rawOperatorConfig = {};
+  // Schema default is `true` (the catalog is opt-out).
+  const SCHEMA_DEFAULT = true;
+  // Round 8: same as the emit variant — `runtimeAuthored` is
+  // informational only, the resolver does not consult it.
+  const runtimeAuthored = runtimeSet?.has("namespaceCatalogEnabled") ?? false;
+  if (rawOperatorConfig !== undefined) {
+    if (configValue !== undefined && configValue !== null) {
+      const rawValue = (rawOperatorConfig as Record<string, unknown>)
+        .namespaceCatalogEnabled;
+      const rawAuthored =
+        "namespaceCatalogEnabled" in rawOperatorConfig &&
+        rawValue !== null &&
+        rawValue !== undefined;
+      // Round 8: same rollback as resolveEmitLegacyTools.
+      if (rawAuthored || configValue !== SCHEMA_DEFAULT) {
+        return coerceBooleanLikeOrThrow("namespaceCatalogEnabled", configValue);
+      }
+    } else if ("namespaceCatalogEnabled" in rawOperatorConfig) {
+      const rawValue = (rawOperatorConfig as Record<string, unknown>)
+        .namespaceCatalogEnabled;
+      if (rawValue !== null && rawValue !== undefined) {
+        return coerceBooleanLikeOrThrow("namespaceCatalogEnabled", rawValue);
+      }
+    }
+  } else if (configValue !== undefined && configValue !== null) {
+    // Legacy caller (no rawOperatorConfig) — trust the merged value.
+    return coerceBooleanLikeOrThrow("namespaceCatalogEnabled", configValue);
+  }
+  return SCHEMA_DEFAULT;
+}

package/src/index.ts

@@ -1311,3 +1311,25 @@ export {
   type ForkCapsuleResult,
   type ForkLineage,
 } from "./transfer/capsule-fork.js";
+
+
+// ---------------------------------------------------------------------------
+// Coding-graph engine contract (#1551 PR1) — types owned by core,
+// implemented by @remnic/coding-graph (à-la-carte optional).
+// ---------------------------------------------------------------------------
+
+export {
+  CODING_GRAPH_ENGINE_VERSION,
+  TIER_1_LANGUAGES,
+} from "./coding/coding-graph-types.js";
+
+export type {
+  CodingGraphEngine,
+  CodingGraphErrorCode,
+  CodingGraphLanguage,
+  CreateCodingGraphEngineOptions,
+  FileIR,
+  ParseFileInput,
+  ParseResult,
+  SymbolIR,
+} from "./coding/coding-graph-types.js";