@enki-dev-expert/global-engineering-standards 0.0.0-stage → 0.1.1

package/src/cli.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { type Command, run } from './installer.js';
+import { type Agent, defaults } from './layout.js';
+
+const help = `Global Engineering Standards\n\nUsage: engineering-standards <command> [options]\n\nCommands: init, init-project, update, uninstall, doctor, rollback\nOptions: --global | --project, --claude, --codex, --dry-run, --help\n\nDefault: current project, both agents. init-project implies --project.\nUpdate uses the content bundled with the CLI version you are running; it does not download.\nUninstall and rollback apply to the entire selected scope.\nExisting user instructions and unrelated skills are preserved.\n`;
+export function main(args: string[]): void {
+  if (!args.length || args.includes('--help')) {
+    process.stdout.write(help);
+    return;
+  }
+  const command = args[0] as Command;
+  if (!['init', 'init-project', 'update', 'uninstall', 'doctor', 'rollback'].includes(command))
+    throw new Error(`Unknown command: ${command}`);
+  const flags = args.slice(1);
+  for (const flag of flags)
+    if (!['--global', '--project', '--claude', '--codex', '--dry-run'].includes(flag))
+      throw new Error(`Unknown option: ${flag}`);
+  if (new Set(flags).size !== flags.length) throw new Error('Repeated option');
+  if (
+    (flags.includes('--global') && flags.includes('--project')) ||
+    (command === 'init-project' && flags.includes('--global'))
+  )
+    throw new Error('Conflicting installation scopes');
+  if (
+    ['uninstall', 'rollback', 'doctor'].includes(command) &&
+    (flags.includes('--claude') || flags.includes('--codex'))
+  )
+    throw new Error(`${command} applies to the whole scope; omit agent filters.`);
+  const selected = (['claude', 'codex'] as Agent[]).filter((x) => flags.includes(`--${x}`));
+  const result = run(command, {
+    ...defaults(),
+    scope: flags.includes('--global') ? 'global' : 'project',
+    agents: selected.length ? selected : command === 'update' ? [] : ['claude', 'codex'],
+    dryRun: flags.includes('--dry-run'),
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(
+    `engineering-standards: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+}

package/src/content.ts

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const digest = (value: string | Buffer) => createHash('sha256').update(value).digest('hex');
+export const skills = [
+  'engineering-architecture-review',
+  'engineering-cost-estimate',
+  'engineering-database-review',
+  'engineering-privacy-check',
+  'engineering-safe-implementation',
+  'engineering-security-standards-check',
+] as const;
+export const documents = [
+  'ai-and-llm',
+  'architecture',
+  'cost-engineering',
+  'data',
+  'governance',
+  'mobile-and-web',
+  'observability',
+  'platforms-and-applications',
+  'privacy',
+  'quality-and-testing',
+  'scalability',
+  'security',
+];
+export const templates = ['ADR', 'AUDIT_REPORT', 'EXCEPTIONS', 'PROJECT_AGENTS'];
+export const contentFiles = [
+  'AGENTS.md',
+  ...documents.map((x) => `docs/${x}.md`),
+  ...templates.map((x) => `templates/${x}.md`),
+  ...skills.map((x) => `skills/${x}/SKILL.md`),
+];
+
+/** Validate the complete payload before planning any destination writes. */
+export function readContent(root = packageRoot): Map<string, string> {
+  const baseline = JSON.parse(
+    readFileSync(path.join(root, 'scripts/content-baseline.json'), 'utf8'),
+  ) as Record<string, string>;
+  const result = new Map<string, string>();
+  for (const name of contentFiles) {
+    const data = readFileSync(path.join(root, name));
+    if (digest(data) !== baseline[name]) throw new Error(`Content baseline mismatch: ${name}`);
+    const value = new TextDecoder('utf-8', { fatal: true }).decode(data);
+    for (const match of value.matchAll(/(?:docs|templates)\/[A-Za-z0-9_-]+\.md/g)) {
+      if (!contentFiles.includes(match[0]))
+        throw new Error(`Broken reference in ${name}: ${match[0]}`);
+    }
+    result.set(name, value);
+  }
+  for (const skill of skills) {
+    const value = result.get(`skills/${skill}/SKILL.md`) ?? '';
+    if (
+      !value.startsWith(`---\nname: ${skill}\ndescription: `) ||
+      !/\n---\n/.test(value.slice(4))
+    ) {
+      throw new Error(`Invalid skill metadata: ${skill}`);
+    }
+    const description = value.split('\n')[2]?.slice('description: '.length) ?? '';
+    if (!description.trim() || description.length > 1024)
+      throw new Error(`Invalid description: ${skill}`);
+  }
+  if (
+    readdirSync(path.join(root, 'docs')).filter((x) => x.endsWith('.md')).length !== 12 ||
+    readdirSync(path.join(root, 'skills')).length !== 6
+  )
+    throw new Error('Unexpected content inventory');
+  return result;
+}
+
+/** Only installation references change; the canonical policy remains byte-for-byte intact. */
+export function render(value: string, reference: string): string {
+  return value
+    .replaceAll('~/engineering-standards/', () => `${reference}/`)
+    .replace(
+      /(?<![\w/])((?:docs|templates)\/[A-Za-z0-9_-]+\.md)/g,
+      (_match, relative: string) => `${reference}/${relative}`,
+    );
+}

package/src/filesystem.ts

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+export interface Snapshot {
+  data: string;
+  mode: number;
+}
+export const equal = (a: Snapshot | null, b: Snapshot | null) =>
+  a?.data === b?.data && a?.mode === b?.mode;
+
+/** Refuse links and special files at every existing component, including dangling links. */
+export function assertSafe(file: string): void {
+  const absolute = path.resolve(file);
+  const parsed = path.parse(absolute);
+  let cursor = parsed.root;
+  const parts = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+  for (let index = 0; index < parts.length; index++) {
+    cursor = path.join(cursor, parts[index] ?? '');
+    let stat: ReturnType<typeof lstatSync>;
+    try {
+      stat = lstatSync(cursor);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) throw new Error(`Refusing symbolic link: ${cursor}`);
+    if (index < parts.length - 1 && !stat.isDirectory())
+      throw new Error(`Not a directory: ${cursor}`);
+    if (index === parts.length - 1 && !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1)) {
+      throw new Error(`Refusing special file or hard link: ${cursor}`);
+    }
+  }
+}
+export function snapshot(file: string): Snapshot | null {
+  assertSafe(file);
+  if (!existsSync(file)) return null;
+  const stat = lstatSync(file);
+  if (!stat.isFile()) throw new Error(`Expected regular file: ${file}`);
+  if (stat.size > 8 * 1024 * 1024) throw new Error(`File exceeds 8 MiB safety limit: ${file}`);
+  return { data: readFileSync(file).toString('base64'), mode: stat.mode & 0o777 };
+}
+export function textOf(value: Snapshot | null): string {
+  return value
+    ? new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(
+        Buffer.from(value.data, 'base64'),
+      )
+    : '';
+}
+export function asSnapshot(value: string, previous: Snapshot | null = null): Snapshot {
+  return {
+    data: Buffer.from(value).toString('base64'),
+    mode: previous?.mode ?? (process.platform === 'win32' ? 0o666 : 0o600),
+  };
+}
+export function ensureDirectory(directory: string): void {
+  assertSafe(directory);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+}
+export function replace(file: string, value: Snapshot | null): void {
+  assertSafe(file);
+  if (value === null) {
+    if (existsSync(file)) unlinkSync(file);
+    return;
+  }
+  ensureDirectory(path.dirname(file));
+  const temporary = path.join(path.dirname(file), `.ges-${randomUUID()}.tmp`);
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, 'wx', value.mode);
+    writeFileSync(fd, Buffer.from(value.data, 'base64'));
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    chmodSync(temporary, value.mode);
+    assertSafe(file);
+    renameSync(temporary, file);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}

package/src/installer.ts

@@ -0,0 +1,280 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { contentFiles, digest, packageRoot, readContent, render, skills } from './content.js';
+import { asSnapshot, assertSafe, equal, snapshot, textOf } from './filesystem.js';
+import { type Agent, type Layout, layout, type Options } from './layout.js';
+import { type Change, commit, locked, pending, rollback } from './transaction.js';
+
+const start = '<!-- global-engineering-standards:start -->';
+const end = '<!-- global-engineering-standards:end -->';
+interface Entry {
+  hash: string;
+  block?: string;
+  created?: boolean;
+}
+interface Manifest {
+  schema: number;
+  version: string;
+  scope: Options['scope'];
+  agents: Agent[];
+  entries: Record<string, Entry>;
+}
+export interface Result {
+  command: string;
+  dryRun: boolean;
+  changes: string[];
+  transaction: string | null;
+  messages: string[];
+}
+
+function loadManifest(context: Layout): Manifest | null {
+  const data = snapshot(context.targets.get('manifest') as string);
+  if (!data) return null;
+  const manifest = JSON.parse(textOf(data)) as Manifest;
+  if (
+    manifest.schema !== 1 ||
+    manifest.scope !== context.options.scope ||
+    typeof manifest.version !== 'string' ||
+    !manifest.entries ||
+    !Array.isArray(manifest.agents) ||
+    !manifest.agents.length ||
+    manifest.agents.some((x) => x !== 'claude' && x !== 'codex')
+  )
+    throw new Error('Invalid manifest');
+  for (const [key, entry] of Object.entries(manifest.entries)) {
+    if (!context.targets.has(key) || key === 'manifest' || !/^[a-f0-9]{64}$/.test(entry.hash))
+      throw new Error(`Invalid manifest entry: ${key}`);
+    if (key.endsWith('-instructions')) {
+      if (
+        typeof entry.block !== 'string' ||
+        !entry.block.startsWith(`\n\n${start}\n`) ||
+        !entry.block.endsWith(`${end}\n`) ||
+        digest(entry.block) !== entry.hash ||
+        typeof entry.created !== 'boolean'
+      ) {
+        throw new Error(`Invalid instruction ownership: ${key}`);
+      }
+    } else if (entry.block !== undefined) throw new Error(`Invalid file ownership: ${key}`);
+  }
+  for (const name of contentFiles)
+    if (!manifest.entries[`framework/${name}`]) throw new Error(`Incomplete manifest: ${name}`);
+  for (const agent of manifest.agents) {
+    if (!manifest.entries[`${agent}-instructions`])
+      throw new Error(`Incomplete manifest: ${agent}`);
+    for (const skill of skills)
+      if (!manifest.entries[`${agent}-skill/${skill}`])
+        throw new Error(`Incomplete manifest: ${skill}`);
+  }
+  return manifest;
+}
+function verify(context: Layout, manifest: Manifest): void {
+  for (const [key, entry] of Object.entries(manifest.entries)) {
+    const value = snapshot(context.targets.get(key) as string);
+    if (!value) throw new Error(`Missing installed file: ${key}`);
+    const text = textOf(value);
+    if (entry.block) {
+      if (
+        text.split(entry.block).length !== 2 ||
+        text.split(start).length !== 2 ||
+        text.split(end).length !== 2
+      ) {
+        throw new Error(`Managed instruction block changed: ${key}`);
+      }
+    } else if (digest(Buffer.from(value.data, 'base64')) !== entry.hash)
+      throw new Error(`Installed file changed: ${key}`);
+  }
+}
+function checkOverrides(context: Layout, agents: Agent[]): void {
+  if (!agents.includes('codex')) return;
+  const instruction = context.targets.get('codex-instructions') as string;
+  const override = snapshot(path.join(path.dirname(instruction), 'AGENTS.override.md'));
+  if (textOf(override).trim())
+    throw new Error(
+      'AGENTS.override.md shadows AGENTS.md; resolve this instruction conflict first.',
+    );
+}
+function reference(context: Layout, target: string): string {
+  return (
+    (context.options.scope === 'global'
+      ? context.framework
+      : path.relative(path.dirname(target), context.framework)
+    )
+      .split(path.sep)
+      .join('/') || '.'
+  );
+}
+function block(context: Layout, target: string, policy: string): string {
+  const root = reference(context, target);
+  return (
+    `\n\n${start}\n# Installed Global Engineering Standards\n\n` +
+    `Framework root: ${JSON.stringify(root)}. Resolve relative framework paths against the directory containing THIS file, never the current working directory.\n\n` +
+    `${render(policy, root).trim()}\n\n${end}\n`
+  );
+}
+function planInstall(context: Layout, previous: Manifest | null, source: string): Change[] {
+  const content = readContent(source);
+  const agents = [
+    ...new Set([...(previous?.agents ?? []), ...context.options.agents]),
+  ].sort() as Agent[];
+  checkOverrides(context, agents);
+  const desired = new Map<string, string>();
+  for (const [name, value] of content) {
+    const target = context.targets.get(`framework/${name}`) as string;
+    const root = reference(context, target);
+    desired.set(
+      `framework/${name}`,
+      name.endsWith('SKILL.md') ? renderSkill(value, root) : render(value, root),
+    );
+  }
+  for (const agent of agents) {
+    const key = `${agent}-instructions`;
+    desired.set(
+      key,
+      block(context, context.targets.get(key) as string, content.get('AGENTS.md') as string),
+    );
+    for (const skill of skills) {
+      const key = `${agent}-skill/${skill}`;
+      const target = context.targets.get(key) as string;
+      const directory = path.dirname(target);
+      assertSafe(directory);
+      if (!previous?.entries[key] && existsSync(directory) && readdirSync(directory).length)
+        throw new Error(`Existing skill directory preserved: ${directory}`);
+      desired.set(
+        key,
+        renderSkill(content.get(`skills/${skill}/SKILL.md`) as string, reference(context, target)),
+      );
+    }
+  }
+  const changes: Change[] = [];
+  const entries: Record<string, Entry> = {};
+  for (const [key, value] of desired) {
+    const before = snapshot(context.targets.get(key) as string);
+    const old = previous?.entries[key];
+    let next = value;
+    if (key.endsWith('-instructions')) {
+      const original = textOf(before);
+      if (!old && (original.includes(start) || original.includes(end)))
+        throw new Error(`Unowned managed block: ${key}`);
+      next = old?.block ? original.replace(old.block, () => value) : original + value;
+      entries[key] = {
+        hash: digest(value),
+        block: value,
+        created: old?.created ?? before === null,
+      };
+      if (key === 'codex-instructions' && Buffer.byteLength(next) > 32768)
+        throw new Error(
+          'Codex instruction file exceeds the default 32 KiB limit; reduce existing instructions manually.',
+        );
+    } else {
+      if (before && !old) throw new Error(`Existing file preserved: ${key}`);
+      entries[key] = { hash: digest(value) };
+    }
+    const after = asSnapshot(next, before);
+    if (!equal(before, after)) changes.push({ key, before, after });
+  }
+  const version = (
+    JSON.parse(readFileSync(path.join(source, 'package.json'), 'utf8')) as { version: string }
+  ).version;
+  const manifest: Manifest = { schema: 1, version, scope: context.options.scope, agents, entries };
+  const before = snapshot(context.targets.get('manifest') as string);
+  const after = asSnapshot(`${JSON.stringify(manifest, null, 2)}\n`, before);
+  if (!equal(before, after)) changes.push({ key: 'manifest', before, after });
+  return changes;
+}
+export function renderSkill(value: string, root: string): string {
+  const delimiter = value.indexOf('\n---\n', 4) + 5;
+  return (
+    value.slice(0, delimiter) +
+    `\nInstallation path resolution: resolve all relative framework paths in this skill against the directory containing this SKILL.md, never the current working directory. Framework root: ${JSON.stringify(root)}.\n` +
+    render(value.slice(delimiter), root)
+  );
+}
+function planUninstall(context: Layout, manifest: Manifest): Change[] {
+  const changes: Change[] = [];
+  for (const [key, entry] of Object.entries(manifest.entries)) {
+    const before = snapshot(context.targets.get(key) as string);
+    let after = null;
+    if (entry.block) {
+      const remaining = textOf(before).replace(entry.block, '');
+      after = remaining === '' && entry.created ? null : asSnapshot(remaining, before);
+    }
+    changes.push({ key, before, after });
+  }
+  changes.push({
+    key: 'manifest',
+    before: snapshot(context.targets.get('manifest') as string),
+    after: null,
+  });
+  return changes;
+}
+export type Command = 'init' | 'init-project' | 'update' | 'uninstall' | 'doctor' | 'rollback';
+export function run(
+  command: Command,
+  options: Options,
+  source = packageRoot,
+  failAfter?: number,
+): Result {
+  const context = layout(options);
+  assertSafe(context.state);
+  // Fail safely before even creating a lock or state directory.
+  if (command !== 'rollback' && pending(context))
+    throw new Error('Interrupted transaction requires rollback.');
+  const initial = command === 'rollback' ? null : loadManifest(context);
+  if (command === 'doctor') {
+    readContent(source);
+    if (!initial) throw new Error('No installation manifest found for this scope.');
+    if (existsSync(path.join(context.state, 'operation.lock')))
+      throw new Error('Installation lock exists; check for an active or interrupted process.');
+    if (pending(context)) throw new Error('Interrupted transaction requires rollback.');
+    verify(context, initial);
+    checkOverrides(context, initial.agents);
+    const messages = [
+      'Manifest, content hashes, instruction blocks and six skill locations per installed agent verified.',
+      'Agent runtime discovery and semantic compliance require an isolated agent session.',
+    ];
+    return { command, dryRun: options.dryRun, changes: [], transaction: null, messages };
+  }
+  const work = (): Result => {
+    if (command === 'rollback') {
+      const result = rollback(context);
+      return {
+        command,
+        dryRun: options.dryRun,
+        changes: [`${result.changes} files`],
+        transaction: result.id,
+        messages: ['Backups retained.'],
+      };
+    }
+    if (pending(context)) throw new Error('Interrupted transaction requires rollback.');
+    const previous = loadManifest(context);
+    if (previous) verify(context, previous);
+    if (command === 'update' && !previous)
+      throw new Error('No installation to update. Run init first.');
+    const changes =
+      command === 'uninstall'
+        ? previous
+          ? planUninstall(context, previous)
+          : []
+        : planInstall(context, previous, source);
+    const transaction = options.dryRun ? null : commit(context, changes, failAfter);
+    return {
+      command,
+      dryRun: options.dryRun,
+      changes: changes.map((x) => x.key),
+      transaction,
+      messages:
+        command === 'uninstall'
+          ? ['Only owned, unchanged content removed. Backups and empty directories retained.']
+          : ['Restart your agent and verify instruction and skill discovery.'],
+    };
+  };
+  if (options.dryRun) return work();
+  // Plan first so ordinary conflicts never write even a lock or a backup.
+  if (command !== 'rollback') {
+    if (initial) verify(context, initial);
+    if (command === 'update' && !initial) throw new Error('No installation to update.');
+    if (command !== 'uninstall') planInstall(context, initial, source);
+  }
+  if (command === 'uninstall' && !initial) return work();
+  return locked(context, work);
+}

package/src/layout.ts

@@ -0,0 +1,70 @@
+import os from 'node:os';
+import path from 'node:path';
+import { contentFiles, skills } from './content.js';
+
+export type Agent = 'claude' | 'codex';
+export interface Options {
+  scope: 'global' | 'project';
+  agents: Agent[];
+  home: string;
+  project: string;
+  codexHome?: string;
+  claudeHome?: string;
+  dryRun: boolean;
+}
+export interface Layout {
+  state: string;
+  framework: string;
+  targets: Map<string, string>;
+  options: Options;
+}
+export function layout(options: Options, paths = path): Layout {
+  const base = paths.resolve(options.scope === 'global' ? options.home : options.project);
+  if (options.scope === 'project' && base === paths.resolve(options.home)) {
+    throw new Error(
+      'Project installation in the home directory is ambiguous; choose a project directory.',
+    );
+  }
+  const state = paths.join(base, '.engineering-standards');
+  const framework = paths.join(state, 'framework');
+  const targets = new Map(
+    contentFiles.map((name) => [`framework/${name}`, paths.join(framework, ...name.split('/'))]),
+  );
+  const claude =
+    options.scope === 'global'
+      ? paths.resolve(options.claudeHome ?? paths.join(base, '.claude'))
+      : paths.join(base, '.claude');
+  const codex =
+    options.scope === 'global'
+      ? paths.resolve(options.codexHome ?? paths.join(base, '.codex'))
+      : base;
+  targets.set(
+    'claude-instructions',
+    paths.join(options.scope === 'global' ? claude : base, 'CLAUDE.md'),
+  );
+  targets.set('codex-instructions', paths.join(codex, 'AGENTS.md'));
+  for (const skill of skills) {
+    targets.set(`claude-skill/${skill}`, paths.join(claude, 'skills', skill, 'SKILL.md'));
+    targets.set(`codex-skill/${skill}`, paths.join(base, '.agents', 'skills', skill, 'SKILL.md'));
+  }
+  targets.set('manifest', paths.join(state, 'manifest.json'));
+  const values = [...targets.values()].map((x) => x.toLowerCase());
+  if (
+    values.some((x) =>
+      [...x].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127),
+    )
+  )
+    throw new Error('Control characters in destination paths are unsupported');
+  if (new Set(values).size !== values.length) throw new Error('Overlapping destination paths');
+  return { state, framework, targets, options };
+}
+export function defaults(): Omit<Options, 'scope' | 'agents' | 'dryRun'> {
+  const options: Omit<Options, 'scope' | 'agents' | 'dryRun'> = {
+    home: os.homedir(),
+    project: process.cwd(),
+  };
+  if (process.env.CODEX_HOME) options.codexHome = path.resolve(process.env.CODEX_HOME);
+  if (process.env.CLAUDE_CONFIG_DIR)
+    options.claudeHome = path.resolve(process.env.CLAUDE_CONFIG_DIR);
+  return options;
+}