engineering-memory 0.1.0

package/install/mcp-registration.mjs

@@ -0,0 +1,457 @@
+import { createHash } from 'node:crypto';
+import { commandFailure } from './commands.mjs';
+
+const SERVER_NAME = 'engineering-memory';
+const API_URL_ENV = 'ENGINEERING_MEMORY_API_URL';
+const missingServerPattern =
+  /not found|does not exist|unknown (?:mcp )?server|no (?:mcp )?server|is not configured/i;
+
+const clients = Object.freeze({
+  codex: {
+    executable: 'codex',
+    addArgs: (registration) => [
+      'mcp',
+      'add',
+      SERVER_NAME,
+      ...environmentArgs(registration),
+      '--',
+      registration.nodePath,
+      registration.bridgeEntry,
+    ],
+    getArgs: ['mcp', 'get', SERVER_NAME, '--json'],
+    removeArgs: ['mcp', 'remove', SERVER_NAME],
+  },
+  claude: {
+    executable: 'claude',
+    addArgs: (registration) => [
+      'mcp',
+      'add',
+      '--scope',
+      'user',
+      SERVER_NAME,
+      ...environmentArgs(registration),
+      '--',
+      registration.nodePath,
+      registration.bridgeEntry,
+    ],
+    getArgs: ['mcp', 'get', SERVER_NAME],
+    removeArgs: ['mcp', 'remove', '--scope', 'user', SERVER_NAME],
+  },
+});
+
+export async function planMcpRegistrations({
+  selectedClients,
+  bridgeEntry,
+  nodePath,
+  apiUrl,
+  state,
+  commandRunner,
+}) {
+  const plans = [];
+  for (const clientName of selectedClients) {
+    const client = clients[clientName];
+    if (!client) throw new Error(`Unsupported client: ${clientName}`);
+    const version = await commandRunner(client.executable, ['--version']);
+    if (version.code !== 0) {
+      throw new Error(
+        `${clientName} CLI is unavailable. Install its native CLI, ensure it is on PATH, then rerun the installer. ${commandFailure(client.executable, version)}`,
+      );
+    }
+    const existing = await commandRunner(client.executable, client.getArgs);
+    const managed = state?.mcp?.[clientName];
+    const registration = createRegistration(clientName, {
+      nodePath,
+      bridgeEntry,
+      apiUrl,
+    });
+    if (existing.code === 0) {
+      if (!isOwnedRegistration(clientName, managed)) {
+        throw new Error(
+          `Refusing to overwrite the existing ${clientName} MCP server named ${SERVER_NAME}. Remove or rename it explicitly, then rerun the installer.`,
+        );
+      }
+      const actual = parseExistingRegistration(clientName, existing.stdout);
+      if (!sameCanonicalRegistration(actual, canonicalRegistration(managed))) {
+        throw new Error(
+          `Refusing to modify the existing ${clientName} MCP server named ${SERVER_NAME}: its actual command, arguments, or environment differ from installer-managed state. Restore or remove it explicitly, then rerun the installer.`,
+        );
+      }
+      if (sameRegistration(managed, registration)) {
+        plans.push({
+          clientName,
+          client,
+          action: 'unchanged',
+          registration,
+        });
+        continue;
+      }
+      plans.push({
+        clientName,
+        client,
+        action: 'replace',
+        registration,
+        previousRegistration: managed,
+      });
+      continue;
+    }
+    const output = `${existing.stderr}\n${existing.stdout}`;
+    if (existing.error || !missingServerPattern.test(output)) {
+      throw new Error(
+        `Could not safely determine whether ${clientName} MCP server ${SERVER_NAME} exists. ${commandFailure(client.executable, existing)}`,
+      );
+    }
+    if (managed && !isOwnedRegistration(clientName, managed)) {
+      throw new Error(
+        `The managed ${clientName} MCP registration points to a different bridge. Remove it explicitly before changing bridge paths.`,
+      );
+    }
+    if (managed) {
+      throw new Error(
+        `Refusing to recreate the missing ${clientName} MCP server named ${SERVER_NAME}: installer state says it was previously managed. Remove the stale installer state explicitly, then rerun the installer.`,
+      );
+    }
+    plans.push({ clientName, client, action: 'add', registration });
+  }
+  return plans;
+}
+
+export async function applyMcpRegistrations(plans, commandRunner, transaction) {
+  const result = {};
+  for (const plan of plans) {
+    if (plan.action === 'add') {
+      await addRegistration(plan, plan.registration, commandRunner);
+      transaction.add(() => removeRegistration(plan, commandRunner));
+    } else if (plan.action === 'replace') {
+      await replaceRegistration(plan, commandRunner);
+      transaction.add(() => restoreRegistration(plan, commandRunner));
+    }
+    result[plan.clientName] = plan.registration;
+  }
+  return result;
+}
+
+async function replaceRegistration(plan, commandRunner) {
+  await removeRegistration(plan, commandRunner);
+  try {
+    await addRegistration(plan, plan.registration, commandRunner);
+  } catch (error) {
+    try {
+      await addRegistration(plan, plan.previousRegistration, commandRunner);
+    } catch (restoreError) {
+      throw new AggregateError(
+        [error, restoreError],
+        `Failed to update and restore ${plan.clientName} MCP registration`,
+      );
+    }
+    throw error;
+  }
+}
+
+async function restoreRegistration(plan, commandRunner) {
+  await removeRegistration(plan, commandRunner);
+  await addRegistration(plan, plan.previousRegistration, commandRunner);
+}
+
+async function addRegistration(plan, registration, commandRunner) {
+  const added = await commandRunner(
+    plan.client.executable,
+    plan.client.addArgs(registration),
+  );
+  if (added.code !== 0) {
+    throw new Error(
+      `Failed to register ${plan.clientName} MCP server. ${commandFailure(plan.client.executable, added)}`,
+    );
+  }
+}
+
+async function removeRegistration(plan, commandRunner) {
+  const removed = await commandRunner(
+    plan.client.executable,
+    plan.client.removeArgs,
+  );
+  if (removed.code !== 0) {
+    throw new Error(
+      `Failed to remove ${plan.clientName} MCP registration. ${commandFailure(plan.client.executable, removed)}`,
+    );
+  }
+}
+
+function environmentArgs(registration) {
+  return registration.apiUrl
+    ? ['--env', `${API_URL_ENV}=${registration.apiUrl}`]
+    : [];
+}
+
+function createRegistration(clientName, values) {
+  return {
+    ...values,
+    fingerprint: registrationFingerprint(clientName, values),
+  };
+}
+
+function registrationFingerprint(clientName, registration) {
+  return createHash('sha256')
+    .update(
+      JSON.stringify({
+        clientName,
+        nodePath: registration.nodePath,
+        bridgeEntry: registration.bridgeEntry,
+        apiUrl: registration.apiUrl ?? null,
+      }),
+    )
+    .digest('hex');
+}
+
+function sameRegistration(left, right) {
+  return (
+    left?.nodePath === right.nodePath &&
+    left?.bridgeEntry === right.bridgeEntry &&
+    left?.apiUrl === right.apiUrl &&
+    left?.fingerprint === right.fingerprint
+  );
+}
+
+function parseExistingRegistration(clientName, stdout) {
+  try {
+    return clientName === 'codex'
+      ? parseCodexRegistration(stdout)
+      : parseClaudeRegistration(stdout);
+  } catch (error) {
+    throw new Error(
+      `Could not safely inspect the existing ${clientName} MCP server ${SERVER_NAME}; refusing to modify it. ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+function parseCodexRegistration(stdout) {
+  const document = parseJsonDocument(
+    stripAnsi(stdout).trim(),
+    'The native JSON output was malformed.',
+  );
+  const server = isRecord(document.server) ? document.server : document;
+  const transport = isRecord(server.transport) ? server.transport : server;
+  const type = transport.type ?? server.type;
+  if (type !== undefined && String(type).toLowerCase() !== 'stdio') {
+    throw new Error(`Expected a stdio transport, received ${String(type)}.`);
+  }
+  if (server.enabled === false) {
+    throw new Error('The registration is disabled.');
+  }
+  if (
+    transport.cwd !== undefined &&
+    transport.cwd !== null &&
+    transport.cwd !== ''
+  ) {
+    throw new Error('A custom working directory is not installer-managed.');
+  }
+  const inheritedEnvironment = transport.env_vars ?? transport.envVars;
+  if (
+    inheritedEnvironment !== undefined &&
+    (!Array.isArray(inheritedEnvironment) || inheritedEnvironment.length > 0)
+  ) {
+    throw new Error(
+      'Inherited environment variables are not installer-managed.',
+    );
+  }
+  return canonicalRegistrationFromValues({
+    command: transport.command,
+    args: transport.args,
+    env: transport.env,
+  });
+}
+
+function parseClaudeRegistration(stdout) {
+  const output = stripAnsi(stdout).replaceAll('\r\n', '\n').trim();
+  if (output.startsWith('{')) {
+    const document = parseJsonDocument(
+      output,
+      'The native JSON output was malformed.',
+    );
+    const server = isRecord(document.server) ? document.server : document;
+    const transport = isRecord(server.transport) ? server.transport : server;
+    return canonicalRegistrationFromValues({
+      command: transport.command,
+      args: transport.args,
+      env: transport.env,
+    });
+  }
+
+  const lines = output.split('\n');
+  if (!lines.some((line) => line.trim() === `${SERVER_NAME}:`)) {
+    throw new Error('The native output did not identify the requested server.');
+  }
+  const scope = readClaudeField(lines, 'Scope');
+  if (!/^user(?:\s+config|\s*\(|$)/i.test(scope)) {
+    throw new Error(`Expected user scope, received ${scope}.`);
+  }
+  const type = readClaudeField(lines, 'Type');
+  if (type.toLowerCase() !== 'stdio') {
+    throw new Error(`Expected a stdio transport, received ${type}.`);
+  }
+  const command = unquote(readClaudeField(lines, 'Command'));
+  const args = parseClaudeArgs(readClaudeField(lines, 'Args'));
+  const env = readClaudeEnvironment(lines);
+  return canonicalRegistrationFromValues({ command, args, env });
+}
+
+function readClaudeField(lines, label) {
+  const expression = new RegExp(`^\\s*${label}:\\s*(.*?)\\s*$`, 'i');
+  for (const line of lines) {
+    const match = line.match(expression);
+    if (match?.[1]) return match[1];
+  }
+  throw new Error(`The native output omitted ${label}.`);
+}
+
+function parseClaudeArgs(value) {
+  if (/^(?:\(none\)|none|\[\])$/i.test(value.trim())) return [];
+  if (value.trim().startsWith('[')) {
+    const parsed = parseJsonDocument(value, 'Args contains malformed JSON.');
+    if (!Array.isArray(parsed)) throw new Error('Args is not an array.');
+    return parsed;
+  }
+  return [unquote(value.trim())];
+}
+
+function readClaudeEnvironment(lines) {
+  const environmentIndex = lines.findIndex((line) =>
+    /^\s*Environment:\s*/i.test(line),
+  );
+  if (environmentIndex < 0) {
+    throw new Error('The native output omitted Environment.');
+  }
+  const header = lines[environmentIndex];
+  const inline = header.replace(/^\s*Environment:\s*/i, '').trim();
+  if (inline && !/^(?:\(none\)|none|\{\})$/i.test(inline)) {
+    const parsed = parseJsonDocument(
+      inline,
+      'Environment contains malformed JSON.',
+    );
+    return normalizeEnvironment(parsed);
+  }
+
+  const headerIndent = header.length - header.trimStart().length;
+  const env = {};
+  for (const line of lines.slice(environmentIndex + 1)) {
+    if (!line.trim()) continue;
+    const indent = line.length - line.trimStart().length;
+    if (indent <= headerIndent) break;
+    const entry = line.trim();
+    const separator = entry.indexOf('=');
+    if (separator <= 0) {
+      throw new Error('Environment contains an unparseable entry.');
+    }
+    const key = entry.slice(0, separator).trim();
+    if (Object.hasOwn(env, key)) {
+      throw new Error(`Environment contains duplicate key ${key}.`);
+    }
+    env[key] = unquote(entry.slice(separator + 1).trim());
+  }
+  return env;
+}
+
+function canonicalRegistration(registration) {
+  return canonicalRegistrationFromValues({
+    command: registration.nodePath,
+    args: [registration.bridgeEntry],
+    env:
+      registration.apiUrl === undefined
+        ? {}
+        : { [API_URL_ENV]: registration.apiUrl },
+  });
+}
+
+function canonicalRegistrationFromValues({ command, args = [], env = {} }) {
+  if (typeof command !== 'string' || command.length === 0) {
+    throw new Error('Command must be a non-empty string.');
+  }
+  if (!Array.isArray(args) || args.some((value) => typeof value !== 'string')) {
+    throw new Error('Args must be an array of strings.');
+  }
+  return {
+    command,
+    args: [...args],
+    env: normalizeEnvironment(env),
+  };
+}
+
+function normalizeEnvironment(environment) {
+  if (environment === null || environment === undefined) return {};
+  const entries = Array.isArray(environment)
+    ? environment.map((entry) => {
+        if (typeof entry !== 'string') {
+          throw new Error('Environment entries must be strings.');
+        }
+        const separator = entry.indexOf('=');
+        if (separator <= 0) {
+          throw new Error('Environment entries must use KEY=value format.');
+        }
+        return [entry.slice(0, separator), entry.slice(separator + 1)];
+      })
+    : isRecord(environment)
+      ? Object.entries(environment)
+      : null;
+  if (!entries) throw new Error('Environment must be an object or array.');
+
+  const normalized = {};
+  for (const [key, value] of entries.sort(([left], [right]) =>
+    left.localeCompare(right),
+  )) {
+    if (!key || typeof value !== 'string') {
+      throw new Error('Environment keys and values must be strings.');
+    }
+    if (Object.hasOwn(normalized, key)) {
+      throw new Error(`Environment contains duplicate key ${key}.`);
+    }
+    normalized[key] = value;
+  }
+  return normalized;
+}
+
+function sameCanonicalRegistration(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function parseJsonDocument(value, message) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new Error(message);
+  }
+}
+
+function stripAnsi(value) {
+  return String(value).replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '');
+}
+
+function unquote(value) {
+  if (
+    value.length >= 2 &&
+    ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'")))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isOwnedRegistration(clientName, managed) {
+  if (!managed) return false;
+  if (managed.apiUrl === undefined && managed.fingerprint === undefined) {
+    return (
+      typeof managed.nodePath === 'string' &&
+      typeof managed.bridgeEntry === 'string'
+    );
+  }
+  return (
+    typeof managed.apiUrl === 'string' &&
+    managed.fingerprint === registrationFingerprint(clientName, managed)
+  );
+}
+
+export const mcpServerName = SERVER_NAME;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "engineering-memory",
+  "version": "0.1.0",
+  "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "engineering-memory": "bin/engineering-memory.mjs"
+  },
+  "files": [
+    "bin",
+    "dispatcher",
+    "install",
+    "skill",
+    "runtime"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "minimatch": "10.2.6",
+    "zod": "4.4.3"
+  },
+  "engineeringMemory": {
+    "apiUrl": "https://coral-app-zqmj6.ondigitalocean.app"
+  }
+}

package/runtime/dist/src/auth/browser-auth.js

@@ -0,0 +1,184 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { endpoints } from '../config.js';
+export class BrowserAuthCoordinator {
+    client;
+    credentials;
+    server = null;
+    pending = null;
+    constructor(client, credentials) {
+        this.client = client;
+        this.credentials = credentials;
+    }
+    async ensureAuthenticated(options = {}) {
+        if (await this.credentials.get('access-token')) {
+            return null;
+        }
+        if (options.restart) {
+            await this.discardPendingAuthentication();
+        }
+        if (this.pending && Date.parse(this.pending.expiresAt) > Date.now()) {
+            return {
+                authenticationRequired: true,
+                authorizationUrl: this.pending.authorizationUrl,
+                expiresAt: this.pending.expiresAt,
+            };
+        }
+        await this.discardPendingAuthentication();
+        const codeVerifier = randomBytes(32).toString('base64url');
+        const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+        try {
+            const callbackUrl = await this.startCallbackServer();
+            const envelope = await this.client.request(endpoints.authBrowserStart, {
+                method: 'POST',
+                authenticated: false,
+                body: {
+                    codeChallenge,
+                    callbackUrl,
+                    clientName: 'Engineering Memory MCP Bridge',
+                },
+            });
+            if (!isBrowserAuthStart(envelope.data)) {
+                throw new Error('Browser authentication start response is invalid');
+            }
+            this.pending = {
+                requestId: envelope.data.requestId,
+                codeVerifier,
+                authorizationUrl: envelope.data.authorizationUrl,
+                expiresAt: envelope.data.expiresAt,
+            };
+            await this.credentials.set('browser-session', JSON.stringify(this.pending));
+            return {
+                authenticationRequired: true,
+                authorizationUrl: this.pending.authorizationUrl,
+                expiresAt: this.pending.expiresAt,
+            };
+        }
+        catch (error) {
+            await this.discardPendingAuthentication();
+            throw error;
+        }
+    }
+    async status() {
+        if (await this.credentials.get('access-token')) {
+            return { authenticated: true, pending: false };
+        }
+        if (this.pending && Date.parse(this.pending.expiresAt) > Date.now()) {
+            return {
+                authenticated: false,
+                pending: true,
+                authorizationUrl: this.pending.authorizationUrl,
+                expiresAt: this.pending.expiresAt,
+            };
+        }
+        if (this.pending) {
+            await this.discardPendingAuthentication();
+        }
+        return { authenticated: false, pending: false };
+    }
+    async dispose() {
+        await this.discardPendingAuthentication();
+    }
+    async startCallbackServer() {
+        this.server = createServer((request, response) => {
+            void this.handleCallback(request.url ?? '/', response);
+        });
+        await new Promise((resolvePromise, reject) => {
+            this.server?.once('error', reject);
+            this.server?.listen(0, '127.0.0.1', resolvePromise);
+        });
+        const address = this.server.address();
+        return `http://127.0.0.1:${address.port}/callback`;
+    }
+    async handleCallback(requestUrl, response) {
+        try {
+            const url = new URL(requestUrl, 'http://127.0.0.1');
+            const requestId = url.searchParams.get('requestId');
+            const authorizationCode = url.searchParams.get('code');
+            if (!this.pending ||
+                requestId !== this.pending.requestId ||
+                !authorizationCode ||
+                Date.parse(this.pending.expiresAt) <= Date.now()) {
+                response.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                response.end('<!doctype html><html><body>Authentication request is invalid.</body></html>');
+                return;
+            }
+            const envelope = await this.client.request(endpoints.authBrowserExchange, {
+                method: 'POST',
+                authenticated: false,
+                body: {
+                    requestId,
+                    authorizationCode,
+                    codeVerifier: this.pending.codeVerifier,
+                },
+            });
+            if (!isTokenPair(envelope.data)) {
+                throw new Error('Browser authentication exchange response is invalid');
+            }
+            await this.persistTokenPair(envelope.data.accessToken, envelope.data.refreshToken);
+            this.pending = null;
+            response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            response.end('<!doctype html><html><body>Authentication completed. You can return to the coding agent.</body></html>');
+            await this.stopServer();
+        }
+        catch {
+            await this.clearCredentialsBestEffort();
+            this.pending = null;
+            response.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' });
+            response.end('<!doctype html><html><body>Authentication could not be completed.</body></html>');
+            await this.stopServer();
+            process.stderr.write('Browser authentication failed\n');
+        }
+    }
+    async persistTokenPair(accessToken, refreshToken) {
+        try {
+            await this.credentials.set('refresh-token', refreshToken);
+            await this.credentials.set('access-token', accessToken);
+            await this.credentials.delete('browser-session');
+        }
+        catch (error) {
+            await this.clearCredentialsBestEffort();
+            throw error;
+        }
+    }
+    async discardPendingAuthentication() {
+        this.pending = null;
+        try {
+            await this.credentials.delete('browser-session');
+        }
+        catch {
+            process.stderr.write('Browser authentication state cleanup failed\n');
+        }
+        await this.stopServer();
+    }
+    async clearCredentialsBestEffort() {
+        try {
+            await this.credentials.clear();
+        }
+        catch {
+            process.stderr.write('Browser authentication credential rollback failed\n');
+        }
+    }
+    async stopServer() {
+        const server = this.server;
+        this.server = null;
+        if (!server) {
+            return;
+        }
+        await new Promise((resolvePromise) => {
+            server.close(() => resolvePromise());
+        });
+    }
+}
+function isBrowserAuthStart(value) {
+    return (value !== null &&
+        typeof value.requestId === 'string' &&
+        typeof value.authorizationUrl === 'string' &&
+        typeof value.expiresAt === 'string');
+}
+function isTokenPair(value) {
+    return (value !== null &&
+        typeof value.accessToken === 'string' &&
+        typeof value.refreshToken === 'string');
+}
+//# sourceMappingURL=browser-auth.js.map