engineering-memory 0.1.0

package/bin/engineering-memory.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  exists,
+  readJson,
+  resolveProductionPackagePaths,
+} from '../install/files.mjs';
+import { runInstaller } from '../install/cli.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+
+const usage = `Usage:
+  engineering-memory install
+
+Installs the skill and the local bridge, and points them at the Engineering
+Memory backend this package was published for. Nothing else is needed: you sign
+in the first time an agent uses it, and your organization and project come from
+your account.
+
+Options:
+  --clients codex,claude          which agent CLIs to install for
+  --api-url <https-url>           a different backend, for a self-hosted install
+  --repo <repository-root>        install the Git verification gate in this repository
+  --hook-mode chain|verify-only|cancel
+  --help
+
+Choose the hook mode through the Codex or Claude native questionnaire before
+passing a repository. The installer never opens a questionnaire or an
+authentication web page.`;
+
+// The published package cannot carry node_modules, because npm excludes it from
+// every tarball. The bridge runtime is therefore assembled here from the
+// dependencies npm installed for this package, into the exact layout the
+// installer verifies against the bridge lockfile.
+async function stageBridgeRuntime() {
+  const source = join(packageRoot, 'runtime');
+  const packageJson = await readJson(join(source, 'package.json'));
+  const packageLock = await readJson(join(source, 'package-lock.json'));
+  if (!packageJson || !packageLock) {
+    throw new Error(`Bridge runtime metadata is missing in ${source}`);
+  }
+  const staged = await mkdtemp(join(tmpdir(), 'engineering-memory-runtime-'));
+  await cp(join(source, 'dist'), join(staged, 'dist'), { recursive: true });
+  await cp(join(source, 'package.json'), join(staged, 'package.json'));
+  await cp(
+    join(source, 'package-lock.json'),
+    join(staged, 'package-lock.json'),
+  );
+  for (const entry of resolveProductionPackagePaths(packageJson, packageLock)) {
+    const name = entry.path.slice('node_modules/'.length);
+    let installed;
+    try {
+      installed = dirname(require.resolve(`${name}/package.json`));
+    } catch {
+      if (entry.optional) continue;
+      throw new Error(
+        `Bridge dependency ${name} is not installed. Reinstall this package so npm resolves its dependencies.`,
+      );
+    }
+    const destination = join(staged, ...entry.path.split('/'));
+    await mkdir(dirname(destination), { recursive: true });
+    await cp(installed, destination, { recursive: true });
+  }
+  return staged;
+}
+
+// The backend this package was published for. An installation only names one
+// when it points at a different, self-hosted backend.
+async function publishedApiUrl() {
+  const manifest = await readJson(join(packageRoot, 'package.json'));
+  const apiUrl = manifest?.engineeringMemory?.apiUrl;
+  if (typeof apiUrl !== 'string' || apiUrl.length === 0) {
+    throw new Error(
+      'This package was built without a backend address. Pass --api-url.',
+    );
+  }
+  return apiUrl;
+}
+
+async function main(argumentList) {
+  const [command, ...rest] = argumentList;
+  if (!command || command === '--help' || command === 'help') {
+    process.stdout.write(`${usage}\n`);
+    return;
+  }
+  if (command !== 'install') {
+    throw new Error(`Unknown command: ${command}`);
+  }
+  const skillSource = join(packageRoot, 'skill');
+  if (!(await exists(join(skillSource, 'SKILL.md')))) {
+    throw new Error(`Skill source is missing in ${skillSource}`);
+  }
+  const staged = await stageBridgeRuntime();
+  try {
+    await runInstaller([
+      ...rest,
+      ...(rest.includes('--api-url')
+        ? []
+        : ['--api-url', await publishedApiUrl()]),
+      '--skill-source',
+      skillSource,
+      '--bridge-runtime-source',
+      staged,
+    ]);
+  } finally {
+    await rm(staged, { recursive: true, force: true });
+  }
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+});

package/dispatcher/managed-section.mjs

@@ -0,0 +1,59 @@
+const START = '## Engineering Memory Dispatcher';
+const END = 'Engineering Memory managed section end.';
+
+export function upsertManagedSection(
+  existing,
+  body,
+  lineEnding = detectLineEnding(existing),
+) {
+  const section = [START, body.trim(), END].join(lineEnding);
+  const startIndexes = findLineIndexes(existing, START);
+  const endIndexes = findLineIndexes(existing, END);
+  if (startIndexes.length !== endIndexes.length || startIndexes.length > 1) {
+    throw new Error('Engineering Memory dispatcher markers are malformed');
+  }
+  if (startIndexes.length === 0) {
+    if (existing.length === 0) return `${section}${lineEnding}`;
+    const separator = existing.endsWith('\n')
+      ? lineEnding
+      : `${lineEnding}${lineEnding}`;
+    return `${existing}${separator}${section}${lineEnding}`;
+  }
+  const start = startIndexes[0];
+  const endLineStart = endIndexes[0];
+  if (endLineStart < start) {
+    throw new Error('Engineering Memory dispatcher markers are malformed');
+  }
+  const end = lineEnd(existing, endLineStart);
+  const suffix = existing.slice(end);
+  return `${existing.slice(0, start)}${section}${lineEnding}${suffix}`;
+}
+
+export function hasManagedSection(value) {
+  return (
+    findLineIndexes(value, START).length === 1 &&
+    findLineIndexes(value, END).length === 1
+  );
+}
+
+function detectLineEnding(value) {
+  return value.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function findLineIndexes(value, target) {
+  const indexes = [];
+  let offset = 0;
+  for (const line of value.split(/(?<=\n)/)) {
+    const normalized = line.replace(/\r?\n$/, '');
+    if (normalized === target) indexes.push(offset);
+    offset += line.length;
+  }
+  return indexes;
+}
+
+function lineEnd(value, start) {
+  const newline = value.indexOf('\n', start);
+  return newline === -1 ? value.length : newline + 1;
+}
+
+export const managedSectionMarkers = Object.freeze({ start: START, end: END });

package/dispatcher/sections.mjs

@@ -0,0 +1,14 @@
+const shared = `This section is managed by the Engineering Memory installer.
+
+For every task, search from the working directory toward the repository root for \`.engineering-memory/project.json\` before planning or editing.
+
+When the marker exists, load the personal \`engineering-memory\` skill and use the \`engineering-memory\` MCP server. Call \`session.bootstrap\` before planning or editing. After compaction, a new chat, interruption, or handoff, call \`session.resume\` before continuing.
+
+Do not edit until the skill lifecycle has completed discovery, its checkpoint, and \`context.prepare_change\`. Do not claim completion until \`task.verify\` succeeds.
+
+When the repository is unbound, use the native questionnaire required by the skill. Do not silently create or bind a project. Do not open a survey web page.`;
+
+export const dispatcherSections = Object.freeze({
+  codex: `${shared}\n\nInvoke the installed skill as \`$engineering-memory\` when an explicit skill invocation is needed.`,
+  claude: `${shared}\n\nInvoke the installed skill as \`/engineering-memory\` when an explicit skill invocation is needed.`,
+});

package/install/api-url.mjs

@@ -0,0 +1,39 @@
+export function normalizeApiUrl(value, options = {}) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error('--api-url is required');
+  }
+  let url;
+  try {
+    url = new URL(value.trim());
+  } catch {
+    throw new Error('--api-url must be an absolute URL');
+  }
+  if (url.username || url.password) {
+    throw new Error('--api-url cannot contain credentials');
+  }
+  if (url.search || url.hash) {
+    throw new Error('--api-url cannot contain a query string or fragment');
+  }
+  const isLocal = isLocalHost(url.hostname);
+  if (isLocal && options.development !== true) {
+    throw new Error('A localhost API URL requires --development');
+  }
+  if (!isLocal && url.protocol !== 'https:') {
+    throw new Error('Production API URL must use HTTPS');
+  }
+  if (isLocal && url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('Development localhost API URL must use HTTP or HTTPS');
+  }
+  return url.href.replace(/\/$/, '');
+}
+
+function isLocalHost(value) {
+  const hostname = value.toLowerCase().replace(/\.$/, '');
+  return (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname.startsWith('127.') ||
+    hostname === '[::1]' ||
+    hostname === '::1'
+  );
+}

package/install/cli.mjs

@@ -0,0 +1,93 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { installEngineeringMemory } from './installer.mjs';
+
+const usage = `Usage:
+  node client/install/cli.mjs [options]
+
+Options:
+  --clients codex,claude
+  --api-url <https-url>
+  --development
+  --repo <repository-root>
+  --hook-mode chain|verify-only|cancel
+  --skill-source <directory>
+  --bridge-runtime-source <directory>
+  --bridge-entry <file>
+  --gate-entry <file>
+  --help
+
+Choose hook mode through the Codex or Claude native questionnaire before running this command. The installer never opens a questionnaire or authentication web page.`;
+
+export function parseInstallerArguments(arguments_) {
+  const result = {};
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (argument === '--help') return { help: true };
+    if (argument === '--development') {
+      result.development = true;
+      continue;
+    }
+    const value = arguments_[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`${argument} requires a value`);
+    }
+    if (argument === '--clients') {
+      result.selectedClients = value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    } else if (argument === '--api-url') {
+      result.apiUrl = value;
+    } else if (argument === '--repo') {
+      result.repoRoot = resolve(value);
+    } else if (argument === '--hook-mode') {
+      result.hookMode = value;
+    } else if (argument === '--skill-source') {
+      result.skillSource = resolve(value);
+    } else if (argument === '--bridge-runtime-source') {
+      result.bridgeRuntimeSource = resolve(value);
+    } else if (argument === '--bridge-entry') {
+      result.bridgeEntry = resolve(value);
+    } else if (argument === '--gate-entry') {
+      result.gateEntry = resolve(value);
+    } else {
+      throw new Error(`Unknown installer argument: ${argument}`);
+    }
+    index += 1;
+  }
+  if (!result.apiUrl) {
+    throw new Error('--api-url is required');
+  }
+  if (result.repoRoot && !result.hookMode) {
+    throw new Error(
+      '--hook-mode is required with --repo after the native hook questionnaire is answered',
+    );
+  }
+  if (!result.repoRoot && result.hookMode && result.hookMode !== 'cancel') {
+    throw new Error('--repo is required when installing a Git hook');
+  }
+  return result;
+}
+
+export async function runInstaller(arguments_ = process.argv.slice(2)) {
+  const options = parseInstallerArguments(arguments_);
+  if (options.help) {
+    process.stdout.write(`${usage}\n`);
+    return;
+  }
+  const result = await installEngineeringMemory(options);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  void runInstaller().catch((error) => {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exitCode = 1;
+  });
+}

package/install/commands.mjs

@@ -0,0 +1,140 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+
+const metaCharacters = /([()\][%!^"`<>&|;, *?])/g;
+const defaultPathExtensions = '.COM;.EXE;.BAT;.CMD';
+const shimExtension = /\.(?:cmd|bat)$/i;
+const pathSeparators = /[/\\]/;
+
+export async function runCommand(command, args, options = {}) {
+  const environment = options.env ?? process.env;
+  const invocation = await planInvocation(command, args, environment, options);
+  return await new Promise((resolve) => {
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: options.cwd,
+      env: environment,
+      shell: false,
+      windowsHide: true,
+      windowsVerbatimArguments: invocation.verbatim,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (value) => {
+      stdout += value;
+    });
+    child.stderr?.on('data', (value) => {
+      stderr += value;
+    });
+    child.on('error', (error) => {
+      resolve({ code: null, stdout, stderr, error });
+    });
+    child.on('close', (code) => {
+      resolve({ code, stdout, stderr, error: null });
+    });
+  });
+}
+
+export async function planInvocation(
+  command,
+  args,
+  environment = process.env,
+  options = {},
+) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== 'win32') {
+    return { command, args, verbatim: false };
+  }
+  const resolveExecutable =
+    options.resolveExecutable ?? resolveWindowsExecutable;
+  const executable = await resolveExecutable(command, environment);
+  if (!executable) {
+    return { command, args, verbatim: false };
+  }
+  if (!shimExtension.test(executable)) {
+    return { command: executable, args, verbatim: false };
+  }
+  const comSpec = environment.ComSpec ?? environment.COMSPEC ?? 'cmd.exe';
+  const line = [escapeCommand(executable), ...args.map(escapeArgument)].join(
+    ' ',
+  );
+  return {
+    command: comSpec,
+    args: ['/d', '/s', '/c', `"${line}"`],
+    verbatim: true,
+  };
+}
+
+export async function resolveWindowsExecutable(command, environment) {
+  const extensions = (environment.PATHEXT ?? defaultPathExtensions)
+    .split(';')
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const named = command.toLowerCase();
+  const carriesExtension = extensions.some((extension) =>
+    named.endsWith(extension.toLowerCase()),
+  );
+  if (pathSeparators.test(command)) {
+    return await firstExistingFile(command, extensions, carriesExtension);
+  }
+  const searchPath = environment.Path ?? environment.PATH ?? '';
+  for (const directory of searchPath.split(delimiter).filter(Boolean)) {
+    const candidate = await firstExistingFile(
+      join(unquote(directory), command),
+      extensions,
+      carriesExtension,
+    );
+    if (candidate) return candidate;
+  }
+  return null;
+}
+
+async function firstExistingFile(base, extensions, carriesExtension) {
+  if (carriesExtension) {
+    return (await isReadableFile(base)) ? base : null;
+  }
+  for (const extension of extensions) {
+    const candidate = `${base}${extension}`;
+    if (await isReadableFile(candidate)) return candidate;
+  }
+  return (await isReadableFile(base)) ? base : null;
+}
+
+async function isReadableFile(candidate) {
+  try {
+    await access(candidate, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function unquote(value) {
+  return value.startsWith('"') && value.endsWith('"')
+    ? value.slice(1, -1)
+    : value;
+}
+
+function escapeCommand(value) {
+  return String(value).replace(metaCharacters, '^$1');
+}
+
+function escapeArgument(value) {
+  const escaped = String(value)
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\*)$/, '$1$1');
+  return `"${escaped}"`
+    .replace(metaCharacters, '^$1')
+    .replace(metaCharacters, '^$1');
+}
+
+export function commandFailure(command, result) {
+  const detail =
+    result.error?.message || result.stderr.trim() || result.stdout.trim();
+  return detail
+    ? `${command}: ${detail}`
+    : `${command} exited with code ${result.code}`;
+}