engineering-memory 0.1.0

package/install/files.mjs

@@ -0,0 +1,416 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  chmod,
+  cp,
+  lstat,
+  mkdtemp,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+
+export class InstallTransaction {
+  constructor() {
+    this.rollbacks = [];
+    this.cleanups = [];
+  }
+
+  add(rollback, cleanup = async () => {}) {
+    this.rollbacks.push(rollback);
+    this.cleanups.push(cleanup);
+  }
+
+  async commit() {
+    const errors = [];
+    for (const cleanup of this.cleanups) {
+      try {
+        await cleanup();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    this.rollbacks = [];
+    this.cleanups = [];
+    if (errors.length > 0) {
+      throw new AggregateError(
+        errors,
+        'Installation succeeded but backup cleanup failed',
+      );
+    }
+  }
+
+  async rollback() {
+    const errors = [];
+    for (const rollback of [...this.rollbacks].reverse()) {
+      try {
+        await rollback();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    this.rollbacks = [];
+    this.cleanups = [];
+    if (errors.length > 0) {
+      throw new AggregateError(errors, 'Installer rollback failed');
+    }
+  }
+}
+
+export async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export async function readText(path) {
+  if (!(await exists(path))) return '';
+  return readFile(path, 'utf8');
+}
+
+export async function readJson(path) {
+  if (!(await exists(path))) return null;
+  let value;
+  try {
+    value = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    throw new Error(`Managed state is not valid JSON: ${path}`);
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Managed state must be an object: ${path}`);
+  }
+  return value;
+}
+
+export async function replaceFile(path, content, transaction, mode) {
+  const previous = (await exists(path)) ? await readFile(path) : null;
+  await writeAtomic(path, content, mode);
+  transaction.add(async () => {
+    if (previous === null) await rm(path, { force: true });
+    else await writeAtomic(path, previous, mode);
+  });
+}
+
+export async function writeJson(path, value, transaction) {
+  await replaceFile(path, `${JSON.stringify(value, null, 2)}\n`, transaction);
+}
+
+export async function installManagedDirectory(
+  source,
+  destination,
+  transaction,
+  options = {},
+) {
+  const artifact = options.artifact ?? 'skill';
+  const artifactLabel = artifact === 'skill' ? 'skill' : 'bridge runtime';
+  const sourceHash = await hashDirectory(source);
+  const manifestPath = join(destination, '.engineering-memory-install.json');
+  if (await exists(destination)) {
+    const manifest = await readJson(manifestPath);
+    if (
+      manifest?.product !== 'engineering-memory' ||
+      manifest?.schemaVersion !== 1 ||
+      (manifest.artifact ?? 'skill') !== artifact
+    ) {
+      throw new Error(
+        `Refusing to overwrite an unmanaged ${artifactLabel} directory: ${destination}`,
+      );
+    }
+    const destinationHash = await hashDirectory(destination, {
+      exclude: ['.engineering-memory-install.json'],
+    });
+    if (destinationHash !== manifest.sourceHash) {
+      throw new Error(
+        `Refusing to overwrite a locally modified managed ${artifactLabel}: ${destination}`,
+      );
+    }
+    if (manifest.sourceHash === sourceHash) return sourceHash;
+  }
+  await mkdir(dirname(destination), { recursive: true });
+  const stage = join(
+    dirname(destination),
+    `.${basename(destination)}.stage-${randomUUID()}`,
+  );
+  const backup = join(
+    dirname(destination),
+    `.${basename(destination)}.backup-${randomUUID()}`,
+  );
+  await copyDirectory(source, stage);
+  await writeAtomic(
+    join(stage, '.engineering-memory-install.json'),
+    `${JSON.stringify(
+      {
+        product: 'engineering-memory',
+        schemaVersion: 1,
+        artifact,
+        sourceHash,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  const hadDestination = await exists(destination);
+  try {
+    if (hadDestination) await rename(destination, backup);
+    await rename(stage, destination);
+  } catch (error) {
+    await rm(stage, { recursive: true, force: true });
+    if (hadDestination && (await exists(backup))) {
+      await rename(backup, destination);
+    }
+    throw error;
+  }
+  transaction.add(
+    async () => {
+      await rm(destination, { recursive: true, force: true });
+      if (hadDestination) await rename(backup, destination);
+    },
+    async () => {
+      await rm(backup, { recursive: true, force: true });
+    },
+  );
+  return sourceHash;
+}
+
+export async function installManagedBridgeRuntime(
+  source,
+  destination,
+  transaction,
+) {
+  const packageJsonPath = join(source, 'package.json');
+  const packageLockPath = join(source, 'package-lock.json');
+  const nodeModulesPath = join(source, 'node_modules');
+  const packageJson = await readRequiredJson(
+    packageJsonPath,
+    'Bridge package metadata',
+  );
+  const packageLock = await readRequiredJson(
+    packageLockPath,
+    'Bridge dependency lockfile',
+  );
+  if (!(await exists(join(source, 'dist')))) {
+    throw new Error(
+      `Built bridge runtime is missing ${join(source, 'dist')}. Run npm run build in the bridge directory before installing.`,
+    );
+  }
+  if (!(await exists(nodeModulesPath))) {
+    throw new Error(
+      `Bridge runtime dependencies are missing: ${nodeModulesPath}. Run npm ci in the bridge directory before installing.`,
+    );
+  }
+  const productionPackages = resolveProductionPackagePaths(
+    packageJson,
+    packageLock,
+  );
+  await mkdir(dirname(destination), { recursive: true });
+  const bundle = await mkdtemp(
+    join(dirname(destination), '.bridge-runtime-source-'),
+  );
+  try {
+    await copyDirectory(join(source, 'dist'), join(bundle, 'dist'));
+    await copyFile(packageJsonPath, join(bundle, 'package.json'));
+    await copyFile(packageLockPath, join(bundle, 'package-lock.json'));
+    for (const packageEntry of productionPackages) {
+      const sourcePath = join(source, ...packageEntry.path.split('/'));
+      if (!(await exists(sourcePath))) {
+        if (packageEntry.optional) continue;
+        throw new Error(
+          `Bridge production dependency is missing: ${sourcePath}. Run npm ci in the bridge directory before installing.`,
+        );
+      }
+      await copyPackageDirectory(
+        sourcePath,
+        join(bundle, ...packageEntry.path.split('/')),
+      );
+    }
+    return await installManagedDirectory(bundle, destination, transaction, {
+      artifact: 'bridge-runtime',
+    });
+  } finally {
+    await rm(bundle, { recursive: true, force: true });
+  }
+}
+
+export async function hashDirectory(root, options = {}) {
+  const hash = createHash('sha256');
+  const excluded = new Set(options.exclude ?? []);
+  const entries = (await listFiles(root)).filter(
+    (entry) => !excluded.has(entry.replaceAll('\\', '/')),
+  );
+  for (const relativePath of entries) {
+    hash.update(relativePath.replaceAll('\\', '/'));
+    hash.update('\0');
+    hash.update(await readFile(join(root, relativePath)));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+async function copyDirectory(source, destination) {
+  await assertSafeTree(source);
+  await cp(source, destination, {
+    recursive: true,
+    errorOnExist: true,
+    force: false,
+    verbatimSymlinks: true,
+  });
+}
+
+async function copyPackageDirectory(source, destination) {
+  const status = await lstat(source);
+  if (!status.isDirectory()) {
+    throw new Error(`Bridge dependency is not a directory: ${source}`);
+  }
+  await mkdir(destination, { recursive: true });
+  const entries = await readdir(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = join(source, entry.name);
+    const destinationPath = join(destination, entry.name);
+    if (entry.isSymbolicLink()) {
+      throw new Error(
+        `Bridge dependency cannot contain symbolic links: ${sourcePath}`,
+      );
+    }
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules') {
+        await copyPackageDirectory(sourcePath, destinationPath);
+      }
+    } else if (entry.isFile()) {
+      await copyFile(sourcePath, destinationPath);
+    } else {
+      throw new Error(
+        `Bridge dependency contains an unsupported entry: ${sourcePath}`,
+      );
+    }
+  }
+}
+
+async function copyFile(source, destination) {
+  await mkdir(dirname(destination), { recursive: true });
+  await cp(source, destination, {
+    errorOnExist: true,
+    force: false,
+  });
+}
+
+async function readRequiredJson(path, label) {
+  if (!(await exists(path))) {
+    throw new Error(`${label} is missing: ${path}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    throw new Error(`${label} is not valid JSON: ${path}`);
+  }
+  if (!value || Array.isArray(value)) {
+    throw new Error(`${label} must be a JSON object: ${path}`);
+  }
+  return value;
+}
+
+export function resolveProductionPackagePaths(packageJson, packageLock) {
+  if (
+    packageLock.lockfileVersion !== 3 ||
+    !packageLock.packages ||
+    typeof packageLock.packages !== 'object' ||
+    Array.isArray(packageLock.packages)
+  ) {
+    throw new Error(
+      'Bridge package-lock.json must use lockfileVersion 3 and contain package records',
+    );
+  }
+  const rootDependencies = Object.keys(packageJson.dependencies ?? {});
+  for (const dependency of rootDependencies) {
+    if (!packageLock.packages[`node_modules/${dependency}`]) {
+      throw new Error(
+        `Bridge lockfile does not contain production dependency ${dependency}. Run npm ci in the bridge directory before installing.`,
+      );
+    }
+  }
+  return Object.entries(packageLock.packages)
+    .filter(
+      ([path, metadata]) =>
+        path.startsWith('node_modules/') &&
+        metadata &&
+        typeof metadata === 'object' &&
+        metadata.dev !== true &&
+        metadata.link !== true,
+    )
+    .map(([path, metadata]) => {
+      if (
+        path.includes('\\') ||
+        path.split('/').some((segment) => segment === '..' || segment === '')
+      ) {
+        throw new Error(
+          `Bridge lockfile contains an unsafe package path: ${path}`,
+        );
+      }
+      return { path, optional: metadata.optional === true };
+    })
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+async function assertSafeTree(root) {
+  const status = await lstat(root);
+  if (!status.isDirectory())
+    throw new Error(`Skill source is not a directory: ${root}`);
+  const queue = [root];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Skill source cannot contain symbolic links: ${path}`);
+      }
+      if (entry.isDirectory()) queue.push(path);
+      else if (!entry.isFile()) {
+        throw new Error(`Skill source contains an unsupported entry: ${path}`);
+      }
+    }
+  }
+}
+
+async function listFiles(root) {
+  await assertSafeTree(root);
+  const result = [];
+  const visit = async (current, prefix) => {
+    const entries = await readdir(current, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const relativePath = prefix ? join(prefix, entry.name) : entry.name;
+      if (entry.isDirectory())
+        await visit(join(current, entry.name), relativePath);
+      else result.push(relativePath);
+    }
+  };
+  await visit(root, '');
+  return result;
+}
+
+async function writeAtomic(path, content, mode) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = join(
+    dirname(path),
+    `.${basename(path)}.${randomUUID()}.tmp`,
+  );
+  try {
+    await writeFile(
+      temporary,
+      content,
+      mode === undefined ? undefined : { mode },
+    );
+    await rename(temporary, path);
+    if (mode !== undefined) await chmod(path, mode);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}

package/install/git-hook.mjs

@@ -0,0 +1,270 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, rename } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { commandFailure } from './commands.mjs';
+import { exists, replaceFile } from './files.mjs';
+
+const MANAGED_MARKER = 'ENGINEERING_MEMORY_MANAGED=1';
+const modes = new Set(['chain', 'verify-only', 'cancel']);
+
+export async function planGitHook({
+  repoRoot,
+  mode,
+  nodePath,
+  gateEntry,
+  apiUrl,
+  commandRunner,
+  state,
+}) {
+  if (!repoRoot) return { action: 'skip', mode: 'cancel' };
+  if (!modes.has(mode)) {
+    throw new Error('Hook mode must be chain, verify-only, or cancel');
+  }
+  if (mode === 'cancel') return { action: 'skip', mode };
+  const { hooksPath } = await resolveRepositoryHooks(repoRoot, commandRunner);
+  const preCommitPath = join(hooksPath, 'pre-commit');
+  const previousPath = join(
+    hooksPath,
+    'pre-commit.engineering-memory.previous',
+  );
+  const verifyPath = join(hooksPath, 'engineering-memory-verify');
+  if (mode === 'verify-only') {
+    if (await exists(verifyPath)) {
+      if (
+        !(await isManaged(verifyPath)) ||
+        !(await matchesState(verifyPath, state))
+      ) {
+        throw new Error(
+          `Refusing to overwrite an unmanaged or modified verify command: ${verifyPath}`,
+        );
+      }
+    }
+    return {
+      action: 'verify-only',
+      mode,
+      apiUrl,
+      verifyPath,
+      content: hookContent({ nodePath, gateEntry, apiUrl }),
+    };
+  }
+  const currentExists = await exists(preCommitPath);
+  const currentManaged = currentExists && (await isManaged(preCommitPath));
+  if (currentManaged && !(await matchesState(preCommitPath, state))) {
+    throw new Error(
+      `Refusing to overwrite an unmanaged or modified pre-commit hook: ${preCommitPath}`,
+    );
+  }
+  if (currentExists && !currentManaged) {
+    if (await exists(previousPath)) {
+      throw new Error(
+        `Cannot chain the existing pre-commit hook because the preserved hook path already exists: ${previousPath}`,
+      );
+    }
+    return {
+      action: 'chain-existing',
+      mode,
+      apiUrl,
+      preCommitPath,
+      previousPath,
+      content: hookContent({
+        nodePath,
+        gateEntry,
+        apiUrl,
+        previousPath,
+      }),
+    };
+  }
+  return {
+    action: 'chain',
+    mode,
+    apiUrl,
+    preCommitPath,
+    previousPath: (await exists(previousPath)) ? previousPath : null,
+    content: hookContent({
+      nodePath,
+      gateEntry,
+      apiUrl,
+      previousPath: (await exists(previousPath)) ? previousPath : null,
+    }),
+  };
+}
+
+export async function applyGitHook(plan, transaction) {
+  if (plan.action === 'skip') return { mode: plan.mode };
+  if (plan.action === 'verify-only') {
+    await replaceFile(plan.verifyPath, plan.content, transaction, 0o755);
+    return {
+      mode: plan.mode,
+      verifyPath: plan.verifyPath,
+      apiUrl: plan.apiUrl,
+      contentHash: hash(plan.content),
+    };
+  }
+  if (plan.action === 'chain-existing') {
+    await rename(plan.preCommitPath, plan.previousPath);
+    transaction.add(async () => {
+      if (await exists(plan.preCommitPath)) return;
+      await rename(plan.previousPath, plan.preCommitPath);
+    });
+  }
+  await replaceFile(plan.preCommitPath, plan.content, transaction, 0o755);
+  return {
+    mode: plan.mode,
+    hookPath: plan.preCommitPath,
+    chainedHookPath: plan.previousPath ?? undefined,
+    apiUrl: plan.apiUrl,
+    contentHash: hash(plan.content),
+  };
+}
+
+async function isManaged(path) {
+  return (await readFile(path, 'utf8'))
+    .split(/\r?\n/)
+    .some((line) => line === MANAGED_MARKER);
+}
+
+async function matchesState(path, state) {
+  if (!state || state.mode === 'cancel') return false;
+  const expectedPath = state.hookPath ?? state.verifyPath;
+  if (expectedPath !== path || typeof state.contentHash !== 'string')
+    return false;
+  return hash(await readFile(path, 'utf8')) === state.contentHash;
+}
+
+async function resolveRepositoryHooks(repoRoot, commandRunner) {
+  const [gitDirectory, commonDirectory, effectiveHooks, configuredHooks] =
+    await Promise.all([
+      runGitPathQuery(repoRoot, commandRunner, '--git-dir'),
+      runGitPathQuery(repoRoot, commandRunner, '--git-common-dir'),
+      runGitPathQuery(repoRoot, commandRunner, '--git-path', 'hooks'),
+      commandRunner('git', [
+        '-C',
+        repoRoot,
+        'config',
+        '--show-origin',
+        '--get',
+        'core.hooksPath',
+      ]),
+    ]);
+  if (configuredHooks.code !== 0 && configuredHooks.code !== 1) {
+    throw new Error(
+      `Could not inspect core.hooksPath for ${repoRoot}. ${commandFailure('git', configuredHooks)}`,
+    );
+  }
+  if (configuredHooks.code === 0 && configuredHooks.stdout.trim()) {
+    throw new Error(
+      `Refusing to install while core.hooksPath is configured. A global, system, or shared hooks setting could make unrelated repositories execute this gate: ${configuredHooks.stdout.trim()}`,
+    );
+  }
+  const gitDir = resolveGitPath(repoRoot, gitDirectory, '--git-dir');
+  const commonDir = resolveGitPath(
+    repoRoot,
+    commonDirectory,
+    '--git-common-dir',
+  );
+  const hooksPath = resolveGitPath(
+    repoRoot,
+    effectiveHooks,
+    '--git-path hooks',
+  );
+  assertSupportedGitDirectoryLayout(gitDir, commonDir);
+  const repositoryHooksPath = join(commonDir, 'hooks');
+  if (!samePath(hooksPath, repositoryHooksPath)) {
+    throw new Error(
+      `Refusing to install into a shared, global, or custom Git hooks path: ${hooksPath}. Expected the repository-owned common hooks directory ${repositoryHooksPath}.`,
+    );
+  }
+  if (await exists(hooksPath)) {
+    const hooksStatus = await lstat(hooksPath);
+    if (hooksStatus.isSymbolicLink() || !hooksStatus.isDirectory()) {
+      throw new Error(
+        `Refusing to install into a Git hooks path that is not a repository-owned directory: ${hooksPath}`,
+      );
+    }
+  }
+  return { gitDir, commonDir, hooksPath };
+}
+
+async function runGitPathQuery(repoRoot, commandRunner, ...arguments_) {
+  return commandRunner('git', [
+    '-C',
+    repoRoot,
+    'rev-parse',
+    '--path-format=absolute',
+    ...arguments_,
+  ]);
+}
+
+function resolveGitPath(repoRoot, result, query) {
+  if (result.code !== 0) {
+    throw new Error(
+      `Could not resolve Git ${query} for ${repoRoot}. ${commandFailure('git', result)}`,
+    );
+  }
+  const rawPath = result.stdout.trim();
+  if (!rawPath) throw new Error(`Git returned an empty ${query} path`);
+  return isAbsolute(rawPath) ? resolve(rawPath) : resolve(repoRoot, rawPath);
+}
+
+function assertSupportedGitDirectoryLayout(gitDir, commonDir) {
+  if (samePath(gitDir, commonDir)) return;
+  const worktreesDirectory = join(commonDir, 'worktrees');
+  const relativeGitDir = relative(worktreesDirectory, gitDir);
+  if (
+    relativeGitDir === '' ||
+    relativeGitDir === '..' ||
+    relativeGitDir.startsWith(`..\\`) ||
+    relativeGitDir.startsWith('../') ||
+    isAbsolute(relativeGitDir)
+  ) {
+    throw new Error(
+      `Refusing an unsupported Git directory layout: ${gitDir} is not the common directory ${commonDir} or one of its linked worktrees`,
+    );
+  }
+}
+
+function samePath(left, right) {
+  const normalize = (value) => {
+    const normalized = resolve(value).replaceAll('\\', '/').replace(/\/+$/, '');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+  };
+  return normalize(left) === normalize(right);
+}
+
+function hookContent({ nodePath, gateEntry, apiUrl, previousPath }) {
+  const lines = ['#!/bin/sh', MANAGED_MARKER];
+  if (previousPath) {
+    lines.push(
+      `if [ -x ${shellQuote(previousPath)} ]; then`,
+      `  ${shellQuote(previousPath)} "$@"`,
+      '  status=$?',
+      '  if [ "$status" -ne 0 ]; then exit "$status"; fi',
+      'fi',
+    );
+  }
+  lines.push(
+    `export ENGINEERING_MEMORY_API_URL=${shellQuote(apiUrl)}`,
+    'repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || {',
+    "  echo 'Engineering Memory: could not resolve the current repository root.' >&2",
+    '  exit 1',
+    '}',
+    'if [ -z "$repo_root" ]; then',
+    "  echo 'Engineering Memory: Git returned an empty repository root.' >&2",
+    '  exit 1',
+    'fi',
+    `exec ${shellQuote(nodePath)} ${shellQuote(gateEntry)} "$repo_root"`,
+    '',
+  );
+  return lines.join('\n');
+}
+
+function shellQuote(value) {
+  const normalized = value.replaceAll('\\', '/');
+  return `'${normalized.replaceAll("'", `'"'"'`)}'`;
+}
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export const gitHookModes = Object.freeze([...modes]);