@rmyndharis/aimhooman 0.1.0

package/src/atomic-write.mjs

@@ -0,0 +1,285 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import {
+    closeSync,
+    existsSync,
+    fsyncSync,
+    mkdirSync,
+    openSync,
+    readFileSync,
+    readdirSync,
+    renameSync,
+    rmSync,
+    statSync,
+    unlinkSync,
+    writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+export function atomicWrite(file, data, options = {}) {
+    const directory = dirname(file);
+    const temporary = join(directory, `.${basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    const mode = options.mode ?? existingMode(file) ?? 0o600;
+    const operations = {
+        open: openSync,
+        write: writeFileSync,
+        sync: fsyncSync,
+        close: closeSync,
+        rename: renameSync,
+        remove: rmSync,
+        openDirectory: openSync,
+        syncDirectory: fsyncSync,
+        closeDirectory: closeSync,
+        ...options.operations,
+    };
+    let descriptor;
+    try {
+        descriptor = operations.open(temporary, 'wx', mode);
+        operations.write(descriptor, data);
+        operations.sync(descriptor);
+        operations.close(descriptor);
+        descriptor = undefined;
+        operations.rename(temporary, file);
+        try {
+            syncDirectory(directory, operations);
+        } catch (error) {
+            throw new Error(
+                `replaced "${file}" but could not sync its directory; durability is uncertain: ${error.message}`,
+                { cause: error },
+            );
+        }
+    } catch (error) {
+        if (descriptor !== undefined) {
+            try { operations.close(descriptor); } catch { /* keep the write error */ }
+        }
+        try { operations.remove(temporary, { force: true }); } catch { /* keep the write error */ }
+        throw error;
+    }
+}
+
+function existingMode(file) {
+    try {
+        return statSync(file).mode & 0o777;
+    } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        throw error;
+    }
+}
+
+function syncDirectory(directory, operations) {
+    let descriptor;
+    let failure = null;
+    try {
+        descriptor = operations.openDirectory(directory, 'r');
+        operations.syncDirectory(descriptor);
+    } catch (error) {
+        failure = error;
+    }
+    let closeFailure = null;
+    if (descriptor !== undefined) {
+        try { operations.closeDirectory(descriptor); }
+        catch (error) { closeFailure = error; }
+    }
+    if (failure && !['EINVAL', 'ENOTSUP', 'EISDIR', 'EBADF', 'EPERM'].includes(failure.code)) {
+        throw failure;
+    }
+    if (closeFailure) throw closeFailure;
+}
+
+const LOCK_WAIT_BUFFER = new Int32Array(new SharedArrayBuffer(4));
+
+function waitForLock(milliseconds) {
+    if (milliseconds > 0) Atomics.wait(LOCK_WAIT_BUFFER, 0, 0, milliseconds);
+}
+
+function processIdentity(pid) {
+    try {
+        if (process.platform === 'linux') {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+            const afterName = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            const startTicks = afterName[19];
+            return startTicks ? `linux:${startTicks}` : null;
+        }
+        if (process.platform === 'win32') {
+            // Node has no direct Windows process-start identity API. Starting
+            // PowerShell for every lock contender can take longer than the lock
+            // retry window under load. Keep the PID-only fallback: a dead owner
+            // is removable, while a reused live PID conservatively retains the
+            // stale candidate instead of risking two writers in one lock.
+            return null;
+        }
+        if (process.platform !== 'win32') {
+            const started = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            return started ? `ps:${started}` : null;
+        }
+    } catch {
+        // A missing process or an unavailable platform probe is handled by the
+        // kill(0) check below. Unknown identity fails safe as an active owner.
+    }
+    return null;
+}
+
+function lockOwnerIsActive(owner) {
+    if (!Number.isSafeInteger(owner?.pid) || owner.pid <= 0 || typeof owner.token !== 'string') {
+        return false;
+    }
+    try {
+        process.kill(owner.pid, 0);
+    } catch (error) {
+        return error?.code !== 'ESRCH';
+    }
+    if (typeof owner.processIdentity === 'string') {
+        const activeIdentity = processIdentity(owner.pid);
+        // If the platform cannot prove identity, retain the lock. A mismatch is
+        // proof that the PID was reused after the recorded holder exited.
+        if (activeIdentity && activeIdentity !== owner.processIdentity) return false;
+    }
+    return true;
+}
+
+const LOCK_CANDIDATE = /^([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.json$/i;
+
+function readCandidate(path, token) {
+    let candidate;
+    try {
+        candidate = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        throw new Error(`malformed state lock candidate "${path}"`, { cause: error });
+    }
+    const valid = candidate
+        && candidate.version === 1
+        && candidate.token === token
+        && Number.isSafeInteger(candidate.pid)
+        && candidate.pid > 0
+        && (candidate.processIdentity === null || typeof candidate.processIdentity === 'string')
+        && typeof candidate.choosing === 'boolean'
+        && (candidate.choosing
+            ? candidate.ticket === null
+            : Number.isSafeInteger(candidate.ticket) && candidate.ticket > 0);
+    if (!valid) throw new Error(`malformed state lock candidate "${path}"`);
+    return { ...candidate, path };
+}
+
+function removeDeadCandidate(candidate, staleMs) {
+    let age;
+    try {
+        age = Date.now() - statSync(candidate.path).mtimeMs;
+    } catch (error) {
+        if (error?.code === 'ENOENT') return true;
+        throw error;
+    }
+    if (age < staleMs || lockOwnerIsActive(candidate)) return false;
+    // Candidate names are random UUIDs and are never reused. Once its exact
+    // process identity is dead, no conforming writer can replace this path, so
+    // deleting it has none of the check-then-unlink race of a shared lockfile.
+    try {
+        unlinkSync(candidate.path);
+    } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+    }
+    return true;
+}
+
+function queueCandidates(queueDir, staleMs) {
+    const candidates = [];
+    for (const entry of readdirSync(queueDir, { withFileTypes: true })) {
+        const match = entry.isFile() && LOCK_CANDIDATE.exec(entry.name);
+        if (!match) continue;
+        const candidate = readCandidate(join(queueDir, entry.name), match[1]);
+        if (!candidate || removeDeadCandidate(candidate, staleMs)) continue;
+        candidates.push(candidate);
+    }
+    return candidates;
+}
+
+function precedes(left, right) {
+    return left.ticket < right.ticket
+        || (left.ticket === right.ticket && left.token.localeCompare(right.token) < 0);
+}
+
+function publishCandidate(path, candidate, operations) {
+    atomicWrite(path, `${JSON.stringify(candidate)}\n`, { operations });
+}
+
+// withLock uses a Lamport bakery queue. Each contender owns one never-reused
+// UUID path, so stale cleanup and release only unlink that contender's path;
+// neither operation can remove a replacement lock at a shared pathname.
+export function withLock(lockPath, fn, options = {}) {
+    const retries = options.retries ?? 50;
+    const staleMs = options.staleMs ?? 60000;
+    const retryDelayMs = options.retryDelayMs ?? 10;
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const queueDir = `${lockPath}.queue`;
+    mkdirSync(queueDir, { recursive: true });
+    const token = randomUUID();
+    const candidatePath = join(queueDir, `${token}.json`);
+    const candidate = {
+        version: 1,
+        pid: process.pid,
+        token,
+        processIdentity: processIdentity(process.pid),
+        choosing: true,
+        ticket: null,
+    };
+    let held = false;
+    let published = false;
+    let primaryError = null;
+    try {
+        // Own the UUID pathname before publication begins. If the rename lands
+        // but its directory fsync fails, finally still removes the candidate;
+        // unlinking ENOENT is harmless when publication failed earlier.
+        published = true;
+        publishCandidate(candidatePath, candidate, options.candidateOperations);
+        const observed = queueCandidates(queueDir, staleMs);
+        candidate.ticket = observed.reduce((maximum, peer) => (
+            peer.ticket === null ? maximum : Math.max(maximum, peer.ticket)
+        ), 0) + 1;
+        candidate.choosing = false;
+        publishCandidate(candidatePath, candidate, options.candidateOperations);
+
+        for (let attempt = 0; attempt < retries; attempt += 1) {
+            // A file at the pre-queue lock path may belong to a concurrently
+            // running older aimhooman version. It cannot be removed safely, so
+            // an upgrade waits/fails closed until that legacy holder releases.
+            const legacyHolder = existsSync(lockPath);
+            const peers = queueCandidates(queueDir, staleMs);
+            const own = peers.find((peer) => peer.token === token);
+            if (!own) throw new Error(`state lock candidate "${candidatePath}" disappeared`);
+            const blocked = legacyHolder || peers.some((peer) => (
+                peer.token !== token && (peer.choosing || precedes(peer, own))
+            ));
+            if (!blocked) {
+                held = true;
+                break;
+            }
+            if (attempt + 1 < retries) waitForLock(retryDelayMs);
+        }
+        if (!held) {
+            throw new Error(`cannot acquire state lock "${lockPath}" after ${retries} attempts`);
+        }
+        return fn();
+    } catch (error) {
+        primaryError = error;
+        throw error;
+    } finally {
+        if (published) {
+            try { (options.unlinkCandidate || unlinkSync)(candidatePath); }
+            catch (error) {
+                if (error?.code !== 'ENOENT') {
+                    if (primaryError) {
+                        throw new AggregateError(
+                            [primaryError, error],
+                            `${primaryError.message}; also failed to release state lock: ${error.message}`,
+                            { cause: primaryError },
+                        );
+                    }
+                    throw error;
+                }
+            }
+        }
+    }
+}

package/src/codex-manifest.mjs

@@ -0,0 +1,65 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+const CODEX_PLUGIN_FIELDS = new Set([
+    'name', 'version', 'description', 'author', 'homepage', 'repository', 'license',
+    'keywords', 'skills', 'mcpServers', 'apps', 'hooks', 'interface',
+]);
+
+export function validateCodexManifest(manifest, pluginRoot) {
+    if (!plainObject(manifest)) throw new Error('Codex plugin manifest must be an object');
+    for (const field of Object.keys(manifest)) {
+        if (!CODEX_PLUGIN_FIELDS.has(field)) throw new Error(`unsupported Codex plugin field: ${field}`);
+    }
+    for (const field of ['name', 'version', 'description']) requireString(manifest[field], `plugin.${field}`);
+    if (manifest.author !== undefined) {
+        if (typeof manifest.author === 'string') requireString(manifest.author, 'plugin.author');
+        else requireString(manifest.author?.name, 'plugin.author.name');
+    }
+    for (const field of ['skills', 'apps', 'mcpServers']) {
+        if (manifest[field] !== undefined) validatePathValue(manifest[field], field, pluginRoot);
+    }
+    if (manifest.hooks !== undefined) validateHooks(manifest.hooks, pluginRoot);
+    return manifest;
+}
+
+function validateHooks(value, pluginRoot) {
+    if (typeof value === 'string') {
+        validatePath(value, 'hooks', pluginRoot);
+        return;
+    }
+    if (plainObject(value)) return;
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error('plugin.hooks must be a path, inline object, or non-empty array');
+    }
+    const strings = value.every((entry) => typeof entry === 'string');
+    const objects = value.every(plainObject);
+    if (!strings && !objects) throw new Error('plugin.hooks array must contain only paths or only inline objects');
+    if (strings) for (const path of value) validatePath(path, 'hooks', pluginRoot);
+}
+
+function validatePathValue(value, field, pluginRoot) {
+    if (typeof value === 'string') return validatePath(value, field, pluginRoot);
+    throw new Error(`plugin.${field} must be a relative path`);
+}
+
+function validatePath(path, field, pluginRoot) {
+    requireString(path, `plugin.${field}`);
+    if (!path.startsWith('./') || isAbsolute(path)) {
+        throw new Error(`plugin.${field} path must start with ./: ${path}`);
+    }
+    const target = resolve(pluginRoot, path);
+    const outside = relative(pluginRoot, target);
+    if (outside === '..' || outside.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(outside)) {
+        throw new Error(`plugin.${field} path escapes the plugin root: ${path}`);
+    }
+    if (!existsSync(target)) throw new Error(`plugin.${field} path does not exist: ${path}`);
+}
+
+function plainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireString(value, field) {
+    if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} must be a non-empty string`);
+}

package/src/exclude.mjs

@@ -0,0 +1,125 @@
+import { lstatSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadRules } from './rules.mjs';
+import { atomicWrite, withLock } from './atomic-write.mjs';
+
+const BEGIN = '# >>> aimhooman managed excludes (do not edit by hand)';
+const END = '# <<< aimhooman managed excludes';
+
+// Local AI residue kept out of `git status`. Deriving this list from the rule
+// catalog prevents the prevention layer from drifting behind enforcement. We
+// intentionally exclude only unambiguous tooling state/settings: secret and
+// review-required rules must remain visible to users.
+const AUTO_EXCLUDE_CATEGORIES = new Set(['ephemeral-state', 'local-settings']);
+
+export function patternsForRules(rules) {
+    const patterns = new Set();
+    for (const rule of rules || []) {
+        if (rule.kind !== 'path' || !AUTO_EXCLUDE_CATEGORIES.has(rule.category)) continue;
+        if (rule.match?.except?.length) continue;
+        const actions = rule.actions || {};
+        if (['clean', 'strict', 'compliance'].some((p) => actions[p] !== 'block')) continue;
+        for (const pattern of rule.match?.paths || []) {
+            // .gitignore-style files are line based. Never let a local rule
+            // turn one catalog value into extra unmanaged exclude lines.
+            if (!/[\r\n]/.test(pattern)) patterns.add(pattern);
+        }
+    }
+    return [...patterns].sort();
+}
+
+// Default exclude patterns derived from the built-in catalog — a convenience
+// for tests/inspection. Lazy + memoized so importing this module never triggers
+// a rule-pack load (production callers derive patterns from their own engine
+// rules via patternsForRules). Eager loading here would also make every command
+// fail-closed on a corrupt rule pack, even commands that never exclude.
+let cachedDefaultPatterns;
+export function defaultPatterns() {
+    if (!cachedDefaultPatterns) cachedDefaultPatterns = patternsForRules(loadRules());
+    return cachedDefaultPatterns;
+}
+
+// applyExclude writes or refreshes the managed block. Idempotent.
+export function applyExclude(file, patterns) {
+    validatePatterns(patterns);
+    return withLock(`${file}.aimhooman.lock`, () => {
+        mkdirSync(dirname(file), { recursive: true });
+        const existing = readExclude(file, '');
+        let body = stripBlock(existing);
+        if (body && !body.endsWith('\n')) body += '\n';
+        const block = BEGIN + '\n' + patterns.join('\n') + '\n' + END + '\n';
+        atomicWrite(file, body + block);
+    });
+}
+
+// removeExclude strips the managed block, keeping other excludes.
+export function removeExclude(file) {
+    return withLock(`${file}.aimhooman.lock`, () => {
+        const existing = readExclude(file, null);
+        if (existing === null) return;
+        atomicWrite(file, stripBlock(existing));
+    });
+}
+
+export function inspectExclude(file, patterns) {
+    const existing = readExclude(file, null);
+    if (existing === null) {
+        return { installed: false, current: false, missing: [...patterns] };
+    }
+    const range = managedRange(existing);
+    if (!range) return { installed: false, current: false, missing: [...patterns] };
+    const { start, end } = range;
+    const actual = new Set(existing.slice(start + BEGIN.length, end).split('\n').map((s) => s.trim()).filter(Boolean));
+    const missing = patterns.filter((pattern) => !actual.has(pattern));
+    return { installed: true, current: missing.length === 0 && actual.size === patterns.length, missing };
+}
+
+function stripBlock(s) {
+    const range = managedRange(s);
+    if (!range) return s;
+    const { start, end } = range;
+    let before = s.slice(0, start).replace(/\n+$/, '');
+    if (before) before += '\n';
+    const rest = s.slice(end + END.length).replace(/^\n/, '');
+    return before + rest;
+}
+
+function readExclude(file, missing) {
+    try {
+        const stat = lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`exclude path "${file}" must be a regular file`);
+        }
+        return readFileSync(file, 'utf8');
+    } catch (error) {
+        if (error?.code === 'ENOENT') return missing;
+        throw error;
+    }
+}
+
+function managedRange(value) {
+    const start = value.indexOf(BEGIN);
+    const firstEnd = value.indexOf(END);
+    if (start < 0 && firstEnd < 0) return null;
+    if (start < 0 || firstEnd < start + BEGIN.length) {
+        throw new Error('managed exclude markers are malformed; repair the file by hand');
+    }
+    const nestedStart = value.indexOf(BEGIN, start + BEGIN.length);
+    const nextEnd = value.indexOf(END, firstEnd + END.length);
+    if (nestedStart >= 0 || nextEnd >= 0) {
+        throw new Error('managed exclude markers appear more than once; repair the file by hand');
+    }
+    return { start, end: firstEnd };
+}
+
+function validatePatterns(patterns) {
+    if (!Array.isArray(patterns) || patterns.some((pattern) => (
+        typeof pattern !== 'string'
+        || pattern.length === 0
+        || /[\r\n]/.test(pattern)
+        || pattern === BEGIN
+        || pattern === END
+    ))) {
+        throw new TypeError('exclude patterns must be non-empty single-line strings');
+    }
+}

package/src/git-environment.mjs

@@ -0,0 +1,5 @@
+// Git replacement refs are local, mutable aliases. Policy and audit reads must
+// address the repository's real object graph instead of a rewritten view.
+export function gitEnvironment(environment = process.env) {
+    return { ...environment, GIT_NO_REPLACE_OBJECTS: '1' };
+}

package/src/git-path.mjs

@@ -0,0 +1,5 @@
+export function normalizeGitPath(value) {
+    let path = String(value || '');
+    if (process.platform === 'win32') path = path.replace(/\\/g, '/');
+    return path.replace(/^(?:\.\/)+/, '');
+}