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

package/dist/content.js

@@ -0,0 +1,71 @@
+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) => 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',
+];
+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) {
+    const baseline = JSON.parse(readFileSync(path.join(root, 'scripts/content-baseline.json'), 'utf8'));
+    const result = new Map();
+    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, reference) {
+    return value
+        .replaceAll('~/engineering-standards/', () => `${reference}/`)
+        .replace(/(?<![\w/])((?:docs|templates)\/[A-Za-z0-9_-]+\.md)/g, (_match, relative) => `${reference}/${relative}`);
+}

package/dist/filesystem.js

@@ -0,0 +1,83 @@
+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 const equal = (a, b) => a?.data === b?.data && a?.mode === b?.mode;
+/** Refuse links and special files at every existing component, including dangling links. */
+export function assertSafe(file) {
+    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;
+        try {
+            stat = lstatSync(cursor);
+        }
+        catch (error) {
+            if (error.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) {
+    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) {
+    return value
+        ? new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.from(value.data, 'base64'))
+        : '';
+}
+export function asSnapshot(value, previous = null) {
+    return {
+        data: Buffer.from(value).toString('base64'),
+        mode: previous?.mode ?? (process.platform === 'win32' ? 0o666 : 0o600),
+    };
+}
+export function ensureDirectory(directory) {
+    assertSafe(directory);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+}
+export function replace(file, value) {
+    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;
+    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/dist/installer.js

@@ -0,0 +1,243 @@
+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 { layout } from './layout.js';
+import { commit, locked, pending, rollback } from './transaction.js';
+const start = '<!-- global-engineering-standards:start -->';
+const end = '<!-- global-engineering-standards:end -->';
+function loadManifest(context) {
+    const data = snapshot(context.targets.get('manifest'));
+    if (!data)
+        return null;
+    const manifest = JSON.parse(textOf(data));
+    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, manifest) {
+    for (const [key, entry] of Object.entries(manifest.entries)) {
+        const value = snapshot(context.targets.get(key));
+        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, agents) {
+    if (!agents.includes('codex'))
+        return;
+    const instruction = context.targets.get('codex-instructions');
+    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, target) {
+    return ((context.options.scope === 'global'
+        ? context.framework
+        : path.relative(path.dirname(target), context.framework))
+        .split(path.sep)
+        .join('/') || '.');
+}
+function block(context, target, policy) {
+    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, previous, source) {
+    const content = readContent(source);
+    const agents = [
+        ...new Set([...(previous?.agents ?? []), ...context.options.agents]),
+    ].sort();
+    checkOverrides(context, agents);
+    const desired = new Map();
+    for (const [name, value] of content) {
+        const target = context.targets.get(`framework/${name}`);
+        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), content.get('AGENTS.md')));
+        for (const skill of skills) {
+            const key = `${agent}-skill/${skill}`;
+            const target = context.targets.get(key);
+            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`), reference(context, target)));
+        }
+    }
+    const changes = [];
+    const entries = {};
+    for (const [key, value] of desired) {
+        const before = snapshot(context.targets.get(key));
+        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')).version;
+    const manifest = { schema: 1, version, scope: context.options.scope, agents, entries };
+    const before = snapshot(context.targets.get('manifest'));
+    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, root) {
+    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, manifest) {
+    const changes = [];
+    for (const [key, entry] of Object.entries(manifest.entries)) {
+        const before = snapshot(context.targets.get(key));
+        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')),
+        after: null,
+    });
+    return changes;
+}
+export function run(command, options, source = packageRoot, failAfter) {
+    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 = () => {
+        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/dist/layout.js

@@ -0,0 +1,42 @@
+import os from 'node:os';
+import path from 'node:path';
+import { contentFiles, skills } from './content.js';
+export function layout(options, paths = path) {
+    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() {
+    const options = {
+        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;
+}

package/dist/transaction.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, openSync, readdirSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { asSnapshot, assertSafe, ensureDirectory, equal, replace, snapshot, textOf, } from './filesystem.js';
+const journalDir = (context) => path.join(context.state, 'transactions');
+export function journals(context) {
+    const directory = journalDir(context);
+    assertSafe(directory);
+    return existsSync(directory)
+        ? readdirSync(directory)
+            .filter((x) => /^\d+-[a-f0-9-]+\.json$/.test(x))
+            .sort()
+            .reverse()
+        : [];
+}
+function validateSnapshot(value) {
+    if (value === null)
+        return;
+    if (!value ||
+        typeof value.data !== 'string' ||
+        value.data.length > 12 * 1024 * 1024 ||
+        !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value.data) ||
+        !Number.isInteger(value.mode) ||
+        value.mode < 0 ||
+        value.mode > 0o777)
+        throw new Error('Invalid transaction snapshot');
+}
+function readJournal(context, name) {
+    const value = JSON.parse(textOf(snapshot(path.join(journalDir(context), name))));
+    if (value.schema !== 1 ||
+        name !== `${value.id}.json` ||
+        !['pending', 'committed', 'rolled-back'].includes(value.status) ||
+        !Array.isArray(value.changes) ||
+        value.changes.length > context.targets.size)
+        throw new Error('Invalid transaction journal');
+    const seen = new Set();
+    for (const change of value.changes) {
+        if (!context.targets.has(change.key) || seen.has(change.key))
+            throw new Error('Invalid transaction target');
+        seen.add(change.key);
+        validateSnapshot(change.before);
+        validateSnapshot(change.after);
+    }
+    return value;
+}
+function save(context, journal) {
+    const serialized = `${JSON.stringify(journal, null, 2)}\n`;
+    if (Buffer.byteLength(serialized) > 8 * 1024 * 1024)
+        throw new Error('Transaction backup exceeds the 8 MiB safety limit');
+    replace(path.join(journalDir(context), `${journal.id}.json`), asSnapshot(serialized));
+}
+export function pending(context) {
+    return journals(context).some((name) => readJournal(context, name).status === 'pending');
+}
+export function locked(context, work) {
+    ensureDirectory(context.state);
+    const file = path.join(context.state, 'operation.lock');
+    assertSafe(file);
+    const fd = openSync(file, 'wx', 0o600);
+    try {
+        return work();
+    }
+    finally {
+        closeSync(fd);
+        unlinkSync(file);
+    }
+}
+export function commit(context, changes, failAfter) {
+    if (!changes.length)
+        return null;
+    if (pending(context))
+        throw new Error('An interrupted transaction exists. Run rollback before continuing.');
+    for (const change of changes) {
+        const file = context.targets.get(change.key);
+        if (!file || !equal(snapshot(file), change.before))
+            throw new Error(`Concurrent modification: ${change.key}`);
+    }
+    const journal = {
+        schema: 1,
+        id: `${Date.now()}-${randomUUID()}`,
+        status: 'pending',
+        changes,
+    };
+    ensureDirectory(journalDir(context));
+    save(context, journal);
+    const completed = [];
+    try {
+        for (const change of changes) {
+            const file = context.targets.get(change.key);
+            if (!equal(snapshot(file), change.before))
+                throw new Error(`Concurrent modification: ${change.key}`);
+            replace(file, change.after);
+            completed.push(change);
+            if (completed.length === failAfter)
+                throw new Error('Injected transaction failure');
+        }
+        journal.status = 'committed';
+        save(context, journal);
+        return journal.id;
+    }
+    catch (error) {
+        for (const change of completed.reverse()) {
+            const file = context.targets.get(change.key);
+            if (!equal(snapshot(file), change.after))
+                throw new Error('Rollback conflict; preserve the journal and recover manually.', {
+                    cause: error,
+                });
+            replace(file, change.before);
+        }
+        journal.status = 'rolled-back';
+        save(context, journal);
+        throw error;
+    }
+}
+export function rollback(context) {
+    const journal = journals(context)
+        .map((name) => readJournal(context, name))
+        .find((x) => x.status !== 'rolled-back');
+    if (!journal)
+        throw new Error('No transaction to roll back.');
+    for (const change of journal.changes) {
+        const current = snapshot(context.targets.get(change.key));
+        if (!equal(current, change.after) &&
+            !(journal.status === 'pending' && equal(current, change.before))) {
+            throw new Error(`Rollback would overwrite later edits: ${change.key}`);
+        }
+    }
+    if (!context.options.dryRun) {
+        journal.status = 'pending';
+        save(context, journal);
+        for (const change of [...journal.changes].reverse()) {
+            const file = context.targets.get(change.key);
+            const current = snapshot(file);
+            if (!equal(current, change.after) &&
+                !(journal.status === 'pending' && equal(current, change.before)))
+                throw new Error(`Concurrent modification: ${change.key}`);
+            replace(file, change.before);
+        }
+        journal.status = 'rolled-back';
+        save(context, journal);
+    }
+    return { id: journal.id, changes: journal.changes.length };
+}