@hames-ai/connectors 0.1.0

package/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @hames-ai/connectors — the connectors companion (#225 PR-3).
+ *
+ * Microsoft Graph app-side tools, the Neo4j non-agentic layer, and the
+ * MCP-gateway namespace catalog — moved out of the host app behind injected
+ * seams so a consumer supplies identity, tokens, content classification and
+ * storage while this package owns the protocols and the query shapes.
+ *
+ * ## What the root barrel carries (and what it deliberately does not)
+ *
+ * The root is the CLIENT-SAFE surface: the namespace catalog (pure data) and
+ * the Neo4j→Cytoscape transform (pure functions, type-only cytoscape import).
+ * Everything else is server-only and reached through its subpath, resolved by
+ * the `./*` wildcard export:
+ *
+ *   - `@hames-ai/connectors/neo4j` and `@hames-ai/connectors/neo4j/client` — the
+ *     explicit-config driver factory (`configureNeo4j`, no env fallback);
+ *   - `@hames-ai/connectors/neo4j/queries` / `neo4j/graph-edit.server` — the
+ *     identity-free ops the host's `'use server'` wrappers gate and delegate
+ *     to;
+ *   - `@hames-ai/connectors/app-tools/registry` — the generic in-process tool
+ *     registry (`createAppToolRegistry`);
+ *   - `@hames-ai/connectors/graph/graph-tools.server` —
+ *     `registerGraphConnectorTools(deps)` and its REQUIRED supplier bag.
+ *
+ * The app that hosted these modules composes them in its
+ * `app-tools/index.server.ts` composition root (which stays host-side): it
+ * builds the registry with its own identity resolver, hands the Graph tools
+ * their `graphFetch` / content / stash suppliers, and registers the transport
+ * on core's seam.
+ */
+
+export { mcpNamespace, MCP_TOOL_CATALOG } from './mcp-catalog'
+export {
+  transformNeo4jToCytoscape,
+  parseNeo4jResults,
+  type Neo4jNode,
+  type Neo4jRelationship,
+  type Neo4jQueryResult,
+} from './neo4j/transform'

package/mcp-catalog.ts

@@ -0,0 +1,149 @@
+/**
+ * The MCP gateway tool→namespace catalog — THIS DEPLOYMENT'S data.
+ *
+ * Moved here from core (`harness-patterns/tools.server.ts`, where it lived as
+ * `KNOWN_TOOL_SERVERS`) by Lane B2 (#225 L5): which tool names exist behind the
+ * gateway is a property of this deployment's `configs/mcp-config.yaml`, not of
+ * the library, so the catalog lives in `app-tools/` beside the rest of the
+ * app's own tooling (docs/plan/harness-npm-lib.md §"stays in app/"). Core keeps
+ * only the consultation ORDER and the deployment-independent heuristic.
+ *
+ * It is registered ONCE, at the same boot point as the app-tool transport:
+ * `app-tools/index.server.ts` (imported by `src/middleware.ts`) calls
+ * `registerToolNamespaces(mcpNamespace)`, so `inferServer` — and therefore both
+ * `Tools()`'s grouping and `withInjectionGuard`'s `isUntrusted` — see this map
+ * without any call site passing it. The `Tools({ namespaces })` argument
+ * (REQUIRED, owner ruling B-iii) is the same map passed explicitly.
+ *
+ * For a package consumer, the registration is not advisory: since #242 item 4
+ * the guard REFUSES a declared namespace it cannot verify, and the refusal
+ * names this registration. Skipping it is a build-time error, not a silent
+ * pass-through.
+ *
+ * 86 distinct names across 6 namespaces. The app-side per-user tools are NOT
+ * here — they declare their own namespaces (`registry.server.ts`), which ride
+ * `inferServer` through the app transport's `namespaceFor`.
+ */
+
+/** Explicit mapping of tool names to server groups. Covers tools whose names
+ *  don't encode the server identity (memory, context7, redis, filesystem, web)
+ *  and pins names the heuristic already gets right (neo4j) so a future edit to
+ *  the heuristic's verb list can't silently regroup them. */
+const MCP_TOOL_CATALOG: Record<string, string> = {}
+
+// Memory Knowledge Graph server
+for (const t of [
+  'create_entities',
+  'create_relations',
+  'add_observations',
+  'delete_entities',
+  'delete_relations',
+  'delete_observations',
+  'open_nodes',
+  'search_nodes',
+  'read_graph',
+])
+  MCP_TOOL_CATALOG[t] = 'memory'
+
+// Neo4j Cypher server. These already resolve to 'neo4j' via the verb-strip
+// heuristic in core (read_/write_/get_ → parts[1]), but pin them explicitly so
+// a future edit to the `verbs` list can't silently regroup them.
+for (const t of ['read_neo4j_cypher', 'write_neo4j_cypher', 'get_neo4j_schema'])
+  MCP_TOOL_CATALOG[t] = 'neo4j'
+
+// Context7 documentation server
+for (const t of ['resolve-library-id', 'get-library-docs']) MCP_TOOL_CATALOG[t] = 'context7'
+
+// Web search / fetch server
+for (const t of ['search', 'fetch', 'fetch_content']) MCP_TOOL_CATALOG[t] = 'web'
+
+// Redis server
+for (const t of [
+  'get',
+  'set',
+  'delete',
+  'expire',
+  'rename',
+  'type',
+  'dbsize',
+  'info',
+  'hget',
+  'hset',
+  'hdel',
+  'hexists',
+  'hgetall',
+  'lpush',
+  'rpush',
+  'lpop',
+  'rpop',
+  'lrange',
+  'llen',
+  'sadd',
+  'srem',
+  'smembers',
+  'zadd',
+  'zrange',
+  'zrem',
+  'json_get',
+  'json_set',
+  'json_del',
+  'xadd',
+  'xdel',
+  'xrange',
+  'publish',
+  'subscribe',
+  'unsubscribe',
+  'scan_keys',
+  'scan_all_keys',
+  'search_redis_documents',
+  'create_vector_index_hash',
+  'set_vector_in_hash',
+  'get_vector_from_hash',
+  'vector_search_hash',
+  'get_indexed_keys_number',
+  'get_indexes',
+  'get_index_info',
+])
+  MCP_TOOL_CATALOG[t] = 'redis'
+
+// Filesystem server
+for (const t of [
+  'read_file',
+  'write_file',
+  'edit_file',
+  'create_directory',
+  'list_directory',
+  'list_directory_with_sizes',
+  'directory_tree',
+  'move_file',
+  'search_files',
+  'search_files_content',
+  'get_file_info',
+  'read_file_lines',
+  'head_file',
+  'tail_file',
+  'read_text_file',
+  'read_multiple_text_files',
+  'read_media_file',
+  'read_multiple_media_files',
+  'find_duplicate_files',
+  'find_empty_directories',
+  'calculate_directory_size',
+  'list_allowed_directories',
+  'zip_directory',
+  'zip_files',
+  'unzip_file',
+])
+  MCP_TOOL_CATALOG[t] = 'filesystem'
+
+/** The catalog, for introspection (the app-side namespace test reads it). */
+export { MCP_TOOL_CATALOG }
+
+/**
+ * The catalog as a `NamespaceResolver` — the value this module hands to
+ * `registerToolNamespaces()` and to every `Tools({ namespaces })` call site.
+ * Undefined for names it does not know, so the caller's chain falls through.
+ */
+export function mcpNamespace(toolName: string): string | undefined {
+  return MCP_TOOL_CATALOG[toolName]
+}

package/neo4j/client.ts

@@ -0,0 +1,112 @@
+/**
+ * Neo4j Driver Client (Non-Agentic Layer)
+ *
+ * Direct neo4j-driver connection for operations that don't require BAML/UTCP:
+ * - Schema fetching
+ * - Manual Cypher queries from a graph visualization
+ *
+ * ## Configuration is explicit-only (design S5, #225 PR-3)
+ * `configureNeo4j({ url, user, password })` is called by the HOST — at app
+ * boot in `middleware.ts`, or explicitly by a standalone script — before the
+ * first `getNeo4jDriver()`. There is NO env fallback in the package, on
+ * purpose: a client that silently guessed a connection would send a
+ * deployment's data at whatever the ambient environment happened to name.
+ * Unset config is a NAMED error at first use (`Neo4jNotConfiguredError`),
+ * never a default — the C1-deferred work the peel disclosed.
+ *
+ * Note: This module runs server-side only; the ops that consume it carry the
+ * `assertServerOnImport()` guard.
+ */
+
+import neo4j, { Driver } from 'neo4j-driver'
+
+// ============================================================================
+// Driver Management
+// ============================================================================
+
+/** Explicit connection config, set by the host (design S5). */
+export interface Neo4jConfig {
+  /** Bolt URI, e.g. `bolt://localhost:7687`. */
+  url: string
+  user: string
+  password: string
+}
+
+/**
+ * The driver was used before `configureNeo4j()` ran — a NAMED error at first
+ * use rather than a default, so a misconfigured deployment fails loudly at
+ * the first query instead of connecting to a guessed endpoint.
+ */
+export class Neo4jNotConfiguredError extends Error {
+  constructor() {
+    super(
+      'Neo4j is not configured: call configureNeo4j({ url, user, password }) ' +
+        'before the first getNeo4jDriver(). The package deliberately has no env ' +
+        'fallback — the host owns the connection details.',
+    )
+    this.name = 'Neo4jNotConfiguredError'
+  }
+}
+
+let config: Neo4jConfig | null = null
+let driver: Driver | null = null
+
+/**
+ * Configure the Neo4j connection explicitly (design S5).
+ *
+ * Called once by the host — app boot (`middleware.ts`) or a standalone
+ * script's entry — with the bolt URI and credentials the host resolved.
+ * Later calls win: the live driver is dropped so the next
+ * `getNeo4jDriver()` reconnects with the new config (and `resetDriver` keeps
+ * its "next call reconnects" contract).
+ */
+export function configureNeo4j(next: Neo4jConfig): void {
+  if (!next || typeof next.url !== 'string' || !next.url.trim()) {
+    throw new Error('configureNeo4j: a non-empty bolt url is required')
+  }
+  config = next
+  driver = null
+}
+
+/**
+ * Get or create the Neo4j driver singleton. Throws
+ * {@link Neo4jNotConfiguredError} when no explicit config was handed over.
+ */
+export function getNeo4jDriver(): Driver {
+  if (!driver) {
+    if (!config) throw new Neo4jNotConfiguredError()
+    driver = neo4j.driver(config.url, neo4j.auth.basic(config.user, config.password))
+
+    console.log('✅ Neo4j driver initialized')
+    console.log(`   - URI: ${config.url}`)
+    console.log(`   - User: ${config.user}`)
+  }
+
+  return driver
+}
+
+/**
+ * Reset the driver connection
+ * Closes the singleton so the next call reconnects
+ */
+export async function resetDriver(): Promise<void> {
+  if (driver) {
+    await driver.close()
+    driver = null
+    console.log('✅ Neo4j driver reset')
+  }
+}
+
+/**
+ * Verify driver connectivity
+ */
+export async function verifyConnection(): Promise<boolean> {
+  try {
+    const drv = getNeo4jDriver()
+    await drv.verifyConnectivity()
+    return true
+  } catch (error) {
+    console.error('Neo4j connection verification failed:', error)
+    return false
+  }
+}

package/neo4j/graph-edit.server.ts

@@ -0,0 +1,127 @@
+/**
+ * Neo4j Graph Edit Ops (#226 C2) — identity-free by construction.
+ *
+ * Intent-shaped operations for a graph visualization UI's edit affordances
+ * (create node, link nodes, edit a property). Replaces the deleted
+ * `write-action.ts`, whose `executeCypherWrite(cypher, params)` was a
+ * browser-reachable arbitrary-Cypher endpoint with no auth.
+ *
+ * Every operation:
+ *  - is gated by the HOST's thin `'use server'` wrapper (per-module
+ *    duplicated gate, SD-13) before it reaches this module — the ops
+ *    themselves carry no identity;
+ *  - owns its Cypher — the client sends intent, never query text;
+ *  - passes all values as Cypher parameters;
+ *  - validates identifiers (label / relationship type / property key), which
+ *    cannot be parameters, against a strict charset allowlist before
+ *    interpolating them backtick-quoted.
+ *
+ * The `'use server'` directive this module carried in the host app is
+ * stripped by the package move (#225 PR-C2); `assertServerOnImport()` is the
+ * load-time guard that replaces it.
+ */
+
+import { assertServerOnImport } from '@hames-ai/harness-patterns/assert.server'
+import { getNeo4jDriver } from './client'
+
+assertServerOnImport()
+
+// Labels, relationship types and property keys cannot be Cypher parameters,
+// so they are interpolated — restricted to a charset that cannot terminate
+// the backtick quoting or smuggle query syntax. The UI legitimately mints NEW
+// labels/relationship types (free-text inputs, defaults `Concept` /
+// `RELATES_TO`), so validation is by shape, not by membership in
+// db.labels()/db.relationshipTypes() — a catalog check would reject the first
+// node of every new label.
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+function assertSafeIdentifier(kind: string, value: string): string {
+  if (!SAFE_IDENTIFIER.test(value)) {
+    throw new Error(`Invalid ${kind} ${JSON.stringify(value)}: must match ${SAFE_IDENTIFIER}`)
+  }
+  return value
+}
+
+async function run(cypher: string, params: Record<string, unknown>) {
+  const session = getNeo4jDriver().session()
+  try {
+    return await session.run(cypher, params)
+  } finally {
+    await session.close()
+  }
+}
+
+/** The single summary record every op's final RETURN produces. A zero-match
+ *  MATCH turns the write into a no-op that resolves exactly like a success
+ *  (#314), so callers read this rather than assuming a row came back. */
+function summaryRecord(result: { records: { get: (key: string) => unknown }[] }) {
+  const record = result.records[0]
+  if (!record) throw new Error('Graph edit query returned no summary record')
+  return record
+}
+
+/** The write's final `RETURN count(*)` — how many nodes the MATCH bound. */
+function matchedCount(
+  result: { records: { get: (key: string) => unknown }[] },
+  key: string,
+): number {
+  return Number(summaryRecord(result).get(key))
+}
+
+/** Create a node with the given label, name and optional description.
+ *  Resolves with the created node's Neo4j elementId: the canvas keys a fresh
+ *  node by its user-typed name (#323 B1), so later edits and relations in the
+ *  same session need the real id to target it with. */
+export async function createGraphNode(
+  label: string,
+  name: string,
+  description?: string,
+): Promise<string> {
+  const safeLabel = assertSafeIdentifier('label', label)
+  if (description) {
+    const result = await run(
+      `CREATE (n:\`${safeLabel}\` {name: $name, description: $description}) RETURN elementId(n) AS elementId`,
+      { name, description },
+    )
+    return String(summaryRecord(result).get('elementId'))
+  }
+  const result = await run(
+    `CREATE (n:\`${safeLabel}\` {name: $name}) RETURN elementId(n) AS elementId`,
+    { name },
+  )
+  return String(summaryRecord(result).get('elementId'))
+}
+
+/** Create a relationship of the given type between two nodes, matched by
+ * elementId. MERGE keeps a second click on the same pair idempotent instead of
+ * stacking duplicate edges. */
+export async function linkGraphNodes(
+  sourceId: string,
+  targetId: string,
+  relType: string,
+): Promise<void> {
+  const safeType = assertSafeIdentifier('relationship type', relType)
+  const result = await run(
+    `MATCH (a), (b) WHERE elementId(a) = $sourceId AND elementId(b) = $targetId MERGE (a)-[:\`${safeType}\`]->(b) RETURN count(*) AS linked`,
+    { sourceId, targetId },
+  )
+  if (matchedCount(result, 'linked') === 0) {
+    throw new Error('Graph edit matched no graph node for that relation — nothing was created')
+  }
+}
+
+/** Set one property on the node with the given elementId. */
+export async function setGraphNodeProperty(
+  nodeId: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  const safeKey = assertSafeIdentifier('property key', key)
+  const result = await run(
+    `MATCH (n) WHERE elementId(n) = $nodeId SET n.\`${safeKey}\` = $value RETURN count(n) AS matched`,
+    { nodeId, value },
+  )
+  if (matchedCount(result, 'matched') === 0) {
+    throw new Error('Graph edit matched no graph node with that id — nothing was written')
+  }
+}

package/neo4j/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Neo4j Module (Non-Agentic Layer)
+ *
+ * Exports direct Neo4j driver functionality for operations that don't require BAML/UTCP:
+ * - Schema fetching
+ * - Manual Cypher queries from graph visualizations
+ * - Connection management
+ *
+ * The host's `'use server'` wrappers (which gate every export on an
+ * authenticated caller before delegating here) live in the host app at the
+ * paths its clients already import.
+ */
+
+// Client
+export {
+  getNeo4jDriver,
+  resetDriver,
+  verifyConnection,
+  configureNeo4j,
+  Neo4jNotConfiguredError,
+  type Neo4jConfig,
+} from './client'
+
+// Query ops (identity-free — the host gates them)
+export {
+  getSchema,
+  getSimplifiedSchema,
+  runManualCypher,
+  resetNeo4jConnection,
+  testNeo4jConnection,
+  type SchemaResult,
+  type CypherResult,
+  type ConnectionResult,
+} from './queries'

package/neo4j/plain.ts

@@ -0,0 +1,153 @@
+/**
+ * Plain projections of neo4j-driver values.
+ *
+ * Everything the driver hands back is a class instance — `Node`, `Relationship`,
+ * `Path`, `Integer`, the temporal types — and SolidStart serialises a
+ * `'use server'` return value with seroval, which refuses any object whose
+ * prototype it does not know:
+ *
+ *   SerovalUnsupportedTypeError: The value [object Object] of type "object"
+ *   cannot be parsed/serialized.
+ *
+ * That throw lands *after* the response headers are on the wire, so the browser
+ * never sees an error envelope — it sees a truncated stream and reports
+ * `Malformed server function stream header`. Which is why a query returning
+ * scalars worked while `MATCH (n) RETURN n LIMIT 5` did not (#237 follow-up).
+ *
+ * `toPlainNeo4jValue` walks a driver value into arrays, plain objects and
+ * primitives. The unknown-object fallback is deliberate: a driver type nobody
+ * anticipated degrades to its own enumerable properties instead of killing the
+ * response.
+ */
+
+import neo4j, { type Integer } from 'neo4j-driver'
+
+/** Stands in for a reference that points back into its own ancestry. */
+export const CIRCULAR_PLACEHOLDER = '[Circular]'
+
+/**
+ * Project a neo4j-driver value into something seroval (and `JSON.stringify`)
+ * can encode.
+ *
+ * - `Integer`/`bigint` → a `number` when it fits exactly, otherwise a decimal
+ *   string. Silently rounding an int64 past 2^53 would be worse than a string.
+ * - `Node` → `{ elementId, identity, labels, properties }`, `Relationship` →
+ *   the same plus `type` and its endpoints, `Path` → `{ start, end, segments }`.
+ *   These keep the field names `neo4j/transform.ts` duck-types on, so the
+ *   Cytoscape projection is built from the plain form too.
+ * - temporal types and points → their `toString()` / component form.
+ * - anything else object-shaped → its own enumerable keys, recursively.
+ */
+export function toPlainNeo4jValue(value: unknown): unknown {
+  return project(value, new Set())
+}
+
+function project(value: unknown, ancestors: Set<object>): unknown {
+  if (value === null || value === undefined) return value
+  if (typeof value === 'bigint') return fromBigInt(value)
+  if (typeof value !== 'object') return value
+
+  if (neo4j.isInt(value)) return fromInteger(value)
+
+  if (
+    neo4j.isDate(value) ||
+    neo4j.isDateTime(value) ||
+    neo4j.isLocalDateTime(value) ||
+    neo4j.isTime(value) ||
+    neo4j.isLocalTime(value) ||
+    neo4j.isDuration(value)
+  ) {
+    return String(value)
+  }
+
+  // A reference already open further up the walk: emitting it again would
+  // recurse forever. Siblings that merely share a reference are unaffected —
+  // `ancestors` only holds the current path (see the `delete` below).
+  if (ancestors.has(value)) return CIRCULAR_PLACEHOLDER
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) return value.map((item) => project(item, ancestors))
+
+    if (neo4j.isPoint(value)) {
+      return {
+        srid: project(value.srid, ancestors),
+        x: value.x,
+        y: value.y,
+        z: value.z,
+      }
+    }
+
+    if (neo4j.isNode(value)) {
+      return {
+        elementId: value.elementId,
+        identity: project(value.identity, ancestors),
+        labels: [...value.labels],
+        properties: projectProperties(value.properties, ancestors),
+      }
+    }
+
+    if (neo4j.isRelationship(value)) {
+      return {
+        elementId: value.elementId,
+        identity: project(value.identity, ancestors),
+        type: value.type,
+        start: project(value.start, ancestors),
+        end: project(value.end, ancestors),
+        startNodeElementId: value.startNodeElementId,
+        endNodeElementId: value.endNodeElementId,
+        properties: projectProperties(value.properties, ancestors),
+      }
+    }
+
+    if (neo4j.isUnboundRelationship(value)) {
+      return {
+        elementId: value.elementId,
+        identity: project(value.identity, ancestors),
+        type: value.type,
+        properties: projectProperties(value.properties, ancestors),
+      }
+    }
+
+    if (neo4j.isPathSegment(value)) {
+      return {
+        start: project(value.start, ancestors),
+        relationship: project(value.relationship, ancestors),
+        end: project(value.end, ancestors),
+      }
+    }
+
+    if (neo4j.isPath(value)) {
+      return {
+        start: project(value.start, ancestors),
+        end: project(value.end, ancestors),
+        length: value.length,
+        segments: value.segments.map((segment) => project(segment, ancestors)),
+      }
+    }
+
+    return projectProperties(value as Record<string, unknown>, ancestors)
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+function projectProperties(
+  properties: Record<string, unknown> | undefined,
+  ancestors: Set<object>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, entry] of Object.entries(properties ?? {})) {
+    out[key] = project(entry, ancestors)
+  }
+  return out
+}
+
+function fromInteger(value: Integer): number | string {
+  return value.inSafeRange() ? value.toNumber() : value.toString()
+}
+
+function fromBigInt(value: bigint): number | string {
+  return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
+    ? Number(value)
+    : value.toString()
+}