engineering-memory 0.1.0

package/install/installer.mjs

@@ -0,0 +1,279 @@
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dispatcherSections } from '../dispatcher/sections.mjs';
+import { upsertManagedSection } from '../dispatcher/managed-section.mjs';
+import { normalizeApiUrl } from './api-url.mjs';
+import { runCommand } from './commands.mjs';
+import {
+  exists,
+  installManagedBridgeRuntime,
+  installManagedDirectory,
+  InstallTransaction,
+  readJson,
+  readText,
+  replaceFile,
+  writeJson,
+} from './files.mjs';
+import { applyGitHook, planGitHook } from './git-hook.mjs';
+import {
+  applyMcpRegistrations,
+  planMcpRegistrations,
+} from './mcp-registration.mjs';
+
+const currentDirectory = dirname(fileURLToPath(import.meta.url));
+const defaultClientRoot = resolve(currentDirectory, '..');
+const defaultProductRoot = resolve(defaultClientRoot, '..');
+
+export const defaultInstallPaths = Object.freeze({
+  skillSource: join(defaultClientRoot, 'skill-source', 'engineering-memory'),
+  bridgeRuntimeSource: join(defaultProductRoot, 'bridge'),
+  bridgeEntry: join(defaultProductRoot, 'bridge', 'dist', 'src', 'index.js'),
+  gateEntry: join(
+    defaultProductRoot,
+    'bridge',
+    'dist',
+    'src',
+    'git',
+    'pre-commit.js',
+  ),
+});
+
+export async function installEngineeringMemory(options = {}) {
+  const homeDir = resolve(options.homeDir ?? homedir());
+  const skillSource = resolve(
+    options.skillSource ?? defaultInstallPaths.skillSource,
+  );
+  const bridgeRuntimeSource = resolve(
+    options.bridgeRuntimeSource ?? defaultInstallPaths.bridgeRuntimeSource,
+  );
+  const sourceBridgeEntry = resolve(
+    options.bridgeEntry ?? join(bridgeRuntimeSource, 'dist', 'src', 'index.js'),
+  );
+  const sourceGateEntry = resolve(
+    options.gateEntry ??
+      join(bridgeRuntimeSource, 'dist', 'src', 'git', 'pre-commit.js'),
+  );
+  const runtimePath = join(homeDir, '.engineering-memory', 'runtime', 'bridge');
+  const bridgeEntry = stableRuntimeEntry(
+    bridgeRuntimeSource,
+    runtimePath,
+    sourceBridgeEntry,
+    'Bridge entry',
+  );
+  const gateEntry = stableRuntimeEntry(
+    bridgeRuntimeSource,
+    runtimePath,
+    sourceGateEntry,
+    'Git gate entry',
+  );
+  const nodePath = resolve(options.nodePath ?? process.execPath);
+  const development = options.development === true;
+  const apiUrl = normalizeApiUrl(options.apiUrl, { development });
+  const selectedClients = normalizeClients(
+    options.selectedClients ?? ['codex', 'claude'],
+  );
+  const commandRunner = options.commandRunner ?? runCommand;
+  await validateInputs({
+    skillSource,
+    bridgeRuntimeSource,
+    sourceBridgeEntry,
+    sourceGateEntry,
+    nodePath,
+  });
+  const statePath = join(homeDir, '.engineering-memory', 'install-state.json');
+  const existingState = await readJson(statePath);
+  if (
+    existingState &&
+    (existingState.product !== 'engineering-memory' ||
+      existingState.schemaVersion !== 1)
+  ) {
+    throw new Error(
+      `Refusing to overwrite unmanaged installer state: ${statePath}`,
+    );
+  }
+  const codexDispatcherPath = join(homeDir, '.codex', 'AGENTS.md');
+  const claudeDispatcherPath = join(homeDir, '.claude', 'CLAUDE.md');
+  const clientTargets = {
+    codex: {
+      skillPath: join(homeDir, '.agents', 'skills', 'engineering-memory'),
+      dispatcherPath: codexDispatcherPath,
+      dispatcherSection: dispatcherSections.codex,
+    },
+    claude: {
+      skillPath: join(homeDir, '.claude', 'skills', 'engineering-memory'),
+      dispatcherPath: claudeDispatcherPath,
+      dispatcherSection: dispatcherSections.claude,
+    },
+  };
+  const clientPlans = await Promise.all(
+    selectedClients.map(async (clientName) => {
+      const target = clientTargets[clientName];
+      return {
+        clientName,
+        ...target,
+        dispatcher: upsertManagedSection(
+          await readText(target.dispatcherPath),
+          target.dispatcherSection,
+        ),
+      };
+    }),
+  );
+  const mcpPlans = await planMcpRegistrations({
+    selectedClients,
+    bridgeEntry,
+    nodePath,
+    apiUrl,
+    state: existingState,
+    commandRunner,
+  });
+  const hookPlan = await planGitHook({
+    repoRoot: options.repoRoot ? resolve(options.repoRoot) : null,
+    mode: options.hookMode ?? 'cancel',
+    nodePath,
+    gateEntry,
+    apiUrl,
+    commandRunner,
+    state: existingState?.hook,
+  });
+  const transaction = new InstallTransaction();
+  let result;
+  try {
+    const runtimeHash = await installManagedBridgeRuntime(
+      bridgeRuntimeSource,
+      runtimePath,
+      transaction,
+    );
+    const mcp = {
+      ...(existingState?.mcp ?? {}),
+      ...(await applyMcpRegistrations(mcpPlans, commandRunner, transaction)),
+    };
+    let skillHash;
+    for (const plan of clientPlans) {
+      const installedHash = await installManagedDirectory(
+        skillSource,
+        plan.skillPath,
+        transaction,
+      );
+      skillHash ??= installedHash;
+      await replaceFile(plan.dispatcherPath, plan.dispatcher, transaction);
+    }
+    const hookResult = await applyGitHook(hookPlan, transaction);
+    const hook =
+      hookPlan.action === 'skip'
+        ? (existingState?.hook ?? hookResult)
+        : hookResult;
+    const state = {
+      product: 'engineering-memory',
+      schemaVersion: 1,
+      skillHash,
+      runtime: {
+        path: runtimePath,
+        sourceHash: runtimeHash,
+        bridgeEntry,
+        gateEntry,
+      },
+      bridgeEntry,
+      nodePath,
+      apiUrl,
+      development,
+      mcp,
+      hook,
+    };
+    await writeJson(statePath, state, transaction);
+    result = {
+      homeDir,
+      statePath,
+      skillPaths: clientPlans.map((plan) => plan.skillPath),
+      dispatcherPaths: clientPlans.map((plan) => plan.dispatcherPath),
+      selectedClients,
+      apiUrl,
+      runtimePath,
+      bridgeEntry,
+      gateEntry,
+      hook: hookResult,
+    };
+  } catch (error) {
+    try {
+      await transaction.rollback();
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        'Installation failed and rollback was incomplete',
+      );
+    }
+    throw error;
+  }
+  await transaction.commit();
+  return result;
+}
+
+function normalizeClients(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error('At least one client must be selected');
+  }
+  const result = [
+    ...new Set(value.map((entry) => String(entry).toLowerCase())),
+  ];
+  for (const entry of result) {
+    if (entry !== 'codex' && entry !== 'claude') {
+      throw new Error(`Unsupported client: ${entry}`);
+    }
+  }
+  return result;
+}
+
+async function validateInputs({
+  skillSource,
+  bridgeRuntimeSource,
+  sourceBridgeEntry,
+  sourceGateEntry,
+  nodePath,
+}) {
+  if (!(await exists(join(skillSource, 'SKILL.md')))) {
+    throw new Error(
+      `Engineering Memory skill source is missing: ${skillSource}`,
+    );
+  }
+  if (!(await exists(join(bridgeRuntimeSource, 'package.json')))) {
+    throw new Error(
+      `Bridge runtime source is missing package.json: ${bridgeRuntimeSource}`,
+    );
+  }
+  if (!(await exists(sourceBridgeEntry))) {
+    throw new Error(
+      `Built stdio bridge is missing: ${sourceBridgeEntry}. Build the bridge before installing.`,
+    );
+  }
+  if (!(await exists(sourceGateEntry))) {
+    throw new Error(
+      `Built Git gate is missing: ${sourceGateEntry}. Build the bridge before installing.`,
+    );
+  }
+  if (!(await exists(nodePath))) {
+    throw new Error(`Node executable is missing: ${nodePath}`);
+  }
+}
+
+function stableRuntimeEntry(sourceRoot, destinationRoot, sourceEntry, label) {
+  const relativeEntry = relative(sourceRoot, sourceEntry);
+  if (
+    relativeEntry === '' ||
+    relativeEntry === '..' ||
+    relativeEntry.startsWith(`..\\`) ||
+    relativeEntry.startsWith('../') ||
+    isAbsolute(relativeEntry)
+  ) {
+    throw new Error(
+      `${label} must be inside bridge runtime source: ${sourceRoot}`,
+    );
+  }
+  if (
+    relativeEntry !== 'dist' &&
+    !relativeEntry.startsWith('dist\\') &&
+    !relativeEntry.startsWith('dist/')
+  ) {
+    throw new Error(`${label} must be inside the built dist directory`);
+  }
+  return join(destinationRoot, relativeEntry);
+}