@sigloch/graphcode-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sigloch Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/host-client.d.ts

@@ -0,0 +1,20 @@
+/** Socket filename inside the store dir — beside the lock it is elected by. */
+export declare const HOST_SOCK_BASENAME = "host.sock";
+/** One forwarded tool call on the wire: newline-delimited JSON, one per connection. */
+export interface ShimRequest {
+    id: number;
+    tool: string;
+    input: unknown;
+}
+/** The host's answer to a {@link ShimRequest}. */
+export type ShimResponse = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/** One forwarded tool call: connect → send → one response line → close. */
+export declare function callHost(socketPath: string, tool: string, input: unknown): Promise<unknown>;

package/dist/host-client.js

@@ -0,0 +1,76 @@
+/**
+ * host-client.ts — the CLIENT half of the graphcode host socket (CR-GC-264).
+ *
+ * A running `graphcode mcp` host owns the single Kuzu store of a repo and keeps
+ * a local Unix socket (`.graphcode/host.sock`) open. Anything that wants to reach
+ * the ONE Apply-Gate without becoming a second store owner talks to that socket:
+ * later MCP sessions (via graphcode's own proxy registry) and external readers
+ * such as the viewer/editor.
+ *
+ * This module is deliberately the *whole* dependency footprint of that path:
+ * `node:net` and nothing else. It lives outside `@sigloch/graphcode` so a
+ * consumer that only forwards tool calls does not install kuzu-wasm (~70 MB) and
+ * the MCP SDK it structurally cannot use — npm resolves dependencies per package,
+ * not per entry point, so a subpath export would not have achieved that.
+ *
+ * The SERVER half (socket creation, election, proxy registry) stays in
+ * graphcode's `host-shim.ts`; it imports the wire types from here so the two
+ * halves can never drift apart.
+ *
+ * @author andreas@siglochconsulting
+ */
+import { connect } from 'node:net';
+/** Socket filename inside the store dir — beside the lock it is elected by. */
+export const HOST_SOCK_BASENAME = 'host.sock';
+/** Connect-retry window: the election winner may still be booting its socket. */
+const CONNECT_RETRIES = 10;
+const CONNECT_RETRY_MS = 200;
+function connectOnce(socketPath) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(socketPath);
+        socket.once('connect', () => resolve(socket));
+        socket.once('error', reject);
+    });
+}
+async function connectWithRetry(socketPath) {
+    let lastErr;
+    for (let i = 0; i < CONNECT_RETRIES; i++) {
+        try {
+            return await connectOnce(socketPath);
+        }
+        catch (err) {
+            lastErr = err;
+            await new Promise((r) => setTimeout(r, CONNECT_RETRY_MS));
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+let nextRequestId = 1;
+/** One forwarded tool call: connect → send → one response line → close. */
+export async function callHost(socketPath, tool, input) {
+    const socket = await connectWithRetry(socketPath);
+    const id = nextRequestId++;
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        socket.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            const nl = buffer.indexOf('\n');
+            if (nl < 0)
+                return;
+            socket.end();
+            try {
+                const res = JSON.parse(buffer.slice(0, nl));
+                if (res.ok)
+                    resolve(res.result);
+                else
+                    reject(new Error(res.error));
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        socket.on('error', (err) => reject(err));
+        socket.on('close', () => reject(new Error(`host closed the connection before answering (${socketPath})`)));
+        socket.write(JSON.stringify({ id, tool, input }) + '\n');
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @sigloch/graphcode-client — the read-side of a running graphcode host.
+ *
+ * Everything a consumer needs to talk to an already-elected `graphcode mcp` host
+ * and to project its answers, WITHOUT owning a store: no kuzu-wasm, no MCP SDK,
+ * no harness. The write path is unchanged — `callHost` forwards to the host's
+ * ONE `mutate()` gate; this package never opens a second one.
+ *
+ * Scope split (CR-GC-264):
+ *   - here          : host-socket client, view catalog (+ readiness/panels in CR-GC-265)
+ *   - @sigloch/graphcode : store, gate, MCP server, exporters, host election
+ *
+ * @author andreas@siglochconsulting
+ */
+export { HOST_SOCK_BASENAME, callHost, type ShimRequest, type ShimResponse, } from './host-client.js';
+export { MARKDOWN_VIEWS, VIEW_FILENAMES, type MarkdownView } from './view-catalog.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @sigloch/graphcode-client — the read-side of a running graphcode host.
+ *
+ * Everything a consumer needs to talk to an already-elected `graphcode mcp` host
+ * and to project its answers, WITHOUT owning a store: no kuzu-wasm, no MCP SDK,
+ * no harness. The write path is unchanged — `callHost` forwards to the host's
+ * ONE `mutate()` gate; this package never opens a second one.
+ *
+ * Scope split (CR-GC-264):
+ *   - here          : host-socket client, view catalog (+ readiness/panels in CR-GC-265)
+ *   - @sigloch/graphcode : store, gate, MCP server, exporters, host election
+ *
+ * @author andreas@siglochconsulting
+ */
+export { HOST_SOCK_BASENAME, callHost, } from './host-client.js';
+export { MARKDOWN_VIEWS, VIEW_FILENAMES } from './view-catalog.js';

package/dist/view-catalog.d.ts

@@ -0,0 +1,22 @@
+/**
+ * view-catalog.ts — the markdown view vocabulary (CR-GC-264).
+ *
+ * Which document views exist, in which order, and under which filename they are
+ * exported to `docs/views/`. Pure data: the RENDERERS stay in graphcode's
+ * `exporter.ts`, only the catalog moved here so a viewer can list and link the
+ * views without depending on the exporter — and through it on the store.
+ *
+ * Deliberately NO Zod. A library that hands out a `ZodEnum` forces every consumer
+ * onto the exact same zod instance; the moment two copies exist (a linked sibling,
+ * a non-deduped install) the schema types stop being assignable and the failure
+ * reads as an unrelated type error. The list is the shared truth — graphcode
+ * builds `MarkdownViewSchema` from it with its OWN zod, so there is still exactly
+ * one definition and this package keeps zero runtime dependencies.
+ *
+ * @author andreas@siglochconsulting
+ */
+/** All supported views, in deterministic order. */
+export declare const MARKDOWN_VIEWS: readonly ["spec", "architecture", "cr-list", "references", "srs", "nfr", "rtm", "icd", "testconcept", "testmatrix", "intplan", "changelog", "fmea", "conops", "trade", "implplan"];
+export type MarkdownView = (typeof MARKDOWN_VIEWS)[number];
+/** Default file name for each view (under docs/views/). */
+export declare const VIEW_FILENAMES: Record<MarkdownView, string>;

package/dist/view-catalog.js

@@ -0,0 +1,57 @@
+/**
+ * view-catalog.ts — the markdown view vocabulary (CR-GC-264).
+ *
+ * Which document views exist, in which order, and under which filename they are
+ * exported to `docs/views/`. Pure data: the RENDERERS stay in graphcode's
+ * `exporter.ts`, only the catalog moved here so a viewer can list and link the
+ * views without depending on the exporter — and through it on the store.
+ *
+ * Deliberately NO Zod. A library that hands out a `ZodEnum` forces every consumer
+ * onto the exact same zod instance; the moment two copies exist (a linked sibling,
+ * a non-deduped install) the schema types stop being assignable and the failure
+ * reads as an unrelated type error. The list is the shared truth — graphcode
+ * builds `MarkdownViewSchema` from it with its OWN zod, so there is still exactly
+ * one definition and this package keeps zero runtime dependencies.
+ *
+ * @author andreas@siglochconsulting
+ */
+/** All supported views, in deterministic order. */
+export const MARKDOWN_VIEWS = [
+    // foundation (CR-GC-113)
+    'spec',
+    'architecture',
+    'cr-list',
+    'references',
+    // SE-artifact projections (CR-GC-220)
+    'srs',
+    'nfr',
+    'rtm',
+    'icd',
+    'testconcept',
+    'testmatrix',
+    'intplan',
+    'changelog',
+    'fmea',
+    'conops',
+    'trade',
+    'implplan',
+];
+/** Default file name for each view (under docs/views/). */
+export const VIEW_FILENAMES = {
+    spec: 'spec.md',
+    architecture: 'architecture.md',
+    'cr-list': 'cr-list.md',
+    references: 'references.md',
+    srs: 'srs.md',
+    nfr: 'nfr.md',
+    rtm: 'rtm.md',
+    icd: 'icd.md',
+    testconcept: 'testconcept.md',
+    testmatrix: 'testmatrix.md',
+    intplan: 'intplan.md',
+    changelog: 'changelog.md',
+    fmea: 'fmea.md',
+    conops: 'conops.md',
+    trade: 'trade.md',
+    implplan: 'implplan.md',
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@sigloch/graphcode-client",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "license": "MIT",
+  "description": "Read-side client for a running @sigloch/graphcode host — host-socket calls, dashboard panels, readiness projection and the markdown view catalog. Deliberately free of Kuzu and the MCP SDK so a viewer can depend on it without pulling an embedded graph database.",
+  "author": "sigloch-consulting",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreassigloch/sigloch-modules.git",
+    "directory": "packages/graphcode-client"
+  },
+  "homepage": "https://github.com/andreassigloch/sigloch-modules#readme",
+  "bugs": {
+    "url": "https://github.com/andreassigloch/sigloch-modules/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}