@aopslabs/aops 0.3.31 → 0.3.33

package/dist/lib/simple-agent-assets.js

@@ -0,0 +1,447 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { compareCanonicalText } from '@aopslabs/artifact-trust-contracts';
+const RELEASE_INDEX = 'release.json';
+const MAX_ARCHIVE_BYTES = 16 * 1024 * 1024;
+const MAX_UNPACKED_BYTES = 64 * 1024 * 1024;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_FILES = 512;
+const VERSION_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
+const SKILL_PATTERN = /^(?:aops(?:-[a-z0-9]+)*|feature-retirement-flow)$/;
+const PRIVATE_SKILL_NAME_PATTERN = /^aops-(?:private|release)-/;
+const PRIVATE_ASSET_MARKER = /must never enter public AOPS agent assets/iu;
+export const AOPS_ASSETS_REPOSITORY = 'eeemzs/aops';
+export const SIMPLE_AGENT_ASSETS_RUNTIME_IDS = ['codex', 'claude'];
+function fail(message) {
+    throw new Error(`aops_assets_${message}`);
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return fail(`invalid_json:${path.basename(file)}`);
+    }
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('invalid_record');
+    return value;
+}
+function validateVersion(value) {
+    if (typeof value !== 'string' || !VERSION_PATTERN.test(value))
+        fail('invalid_version');
+    return value;
+}
+function validateArchiveName(value) {
+    if (typeof value !== 'string' || value !== path.basename(value) || !value.endsWith('.json.gz')) {
+        fail('invalid_archive_name');
+    }
+    return value;
+}
+function validateSha256(value) {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value))
+        fail('invalid_archive_sha256');
+    return value;
+}
+export function readSimpleAgentAssetsReleaseIndex(releaseRoot) {
+    const normalizedRoot = path.resolve(releaseRoot);
+    const rootStat = lstatSync(normalizedRoot);
+    const indexPath = path.join(normalizedRoot, RELEASE_INDEX);
+    const indexStat = lstatSync(indexPath);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || !indexStat.isFile() || indexStat.isSymbolicLink()) {
+        fail('invalid_release_root');
+    }
+    const record = asRecord(readJson(indexPath));
+    if (record.schemaVersion !== 2)
+        fail('unsupported_release_index');
+    return Object.freeze({
+        schemaVersion: 2,
+        version: validateVersion(record.version),
+        archive: validateArchiveName(record.archive),
+        sha256: validateSha256(record.sha256),
+    });
+}
+function validateAssetPath(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\\') || path.posix.isAbsolute(value)) {
+        fail('unsafe_asset_path');
+    }
+    const segments = value.split('/');
+    if (segments.some((segment) => !segment || segment === '.' || segment === '..'))
+        fail('unsafe_asset_path');
+    if (segments[0] === 'skills') {
+        if (segments.length < 3 || !SKILL_PATTERN.test(segments[1]) || PRIVATE_SKILL_NAME_PATTERN.test(segments[1])) {
+            fail('private_or_invalid_skill');
+        }
+    }
+    else if (segments[0] === 'docs') {
+        if (segments.length !== 3 || segments[1] !== 'user-guides' || !/^[a-z0-9]+(?:-[a-z0-9]+)*-user-guide\.md$/u.test(segments[2])) {
+            fail('invalid_user_guide_path');
+        }
+    }
+    else if (segments[0] === 'disciplines') {
+        if (segments.length !== 3 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(segments[1]) || segments[2] !== 'SKILL.md') {
+            fail('invalid_discipline_path');
+        }
+    }
+    else if (segments[0] === 'roles') {
+        if (segments.length !== 3 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(segments[1]) || segments[2] !== 'ROLE.md') {
+            fail('invalid_role_path');
+        }
+    }
+    else {
+        fail('invalid_asset_kind');
+    }
+    return value;
+}
+function decodeArchive(bytes, expectedVersion) {
+    let inflated;
+    try {
+        inflated = gunzipSync(bytes, { maxOutputLength: MAX_UNPACKED_BYTES });
+    }
+    catch {
+        return fail('invalid_archive');
+    }
+    let archiveValue;
+    try {
+        archiveValue = JSON.parse(inflated.toString('utf8'));
+    }
+    catch {
+        return fail('invalid_archive_json');
+    }
+    const archive = asRecord(archiveValue);
+    if (archive.schemaVersion !== 2 || validateVersion(archive.version) !== expectedVersion || !Array.isArray(archive.files)) {
+        fail('invalid_archive_contract');
+    }
+    if (archive.files.length === 0 || archive.files.length > MAX_FILES)
+        fail('invalid_archive_file_count');
+    const exactPaths = new Set();
+    const foldedPaths = new Set();
+    const files = archive.files.map((candidate) => {
+        const row = asRecord(candidate);
+        const assetPath = validateAssetPath(row.path);
+        const folded = assetPath.toLowerCase();
+        if (exactPaths.has(assetPath) || foldedPaths.has(folded))
+            fail('duplicate_asset_path');
+        exactPaths.add(assetPath);
+        foldedPaths.add(folded);
+        if (typeof row.content !== 'string')
+            fail('invalid_asset_content');
+        const fileBytes = Buffer.from(row.content, 'base64');
+        if (fileBytes.toString('base64') !== row.content)
+            fail('invalid_asset_content');
+        if (fileBytes.byteLength > MAX_FILE_BYTES)
+            fail('asset_too_large');
+        return Object.freeze({ path: assetPath, bytes: fileBytes });
+    });
+    const ordered = files.sort((left, right) => compareCanonicalText(left.path, right.path));
+    for (const file of ordered) {
+        if (file.path.startsWith('skills/') && file.path.endsWith('/SKILL.md') && PRIVATE_ASSET_MARKER.test(file.bytes.toString('utf8'))) {
+            fail('private_or_invalid_skill');
+        }
+    }
+    return Object.freeze(ordered);
+}
+export function loadSimpleAgentAssetsRelease(releaseRoot) {
+    const normalizedRoot = path.resolve(releaseRoot);
+    const index = readSimpleAgentAssetsReleaseIndex(normalizedRoot);
+    const archivePath = path.join(normalizedRoot, index.archive);
+    const archiveStat = lstatSync(archivePath);
+    if (!archiveStat.isFile() || archiveStat.isSymbolicLink() || archiveStat.size > MAX_ARCHIVE_BYTES) {
+        fail('invalid_archive_file');
+    }
+    const archiveBytes = readFileSync(archivePath);
+    if (sha256(archiveBytes) !== index.sha256)
+        fail('archive_digest_mismatch');
+    const files = decodeArchive(archiveBytes, index.version);
+    const skillNames = Object.freeze([...new Set(files
+            .filter((file) => file.path.startsWith('skills/'))
+            .map((file) => file.path.split('/')[1]))].sort(compareCanonicalText));
+    const userGuidePaths = Object.freeze(files
+        .filter((file) => file.path.startsWith('docs/user-guides/'))
+        .map((file) => file.path)
+        .sort(compareCanonicalText));
+    const disciplineNames = Object.freeze([...new Set(files
+            .filter((file) => file.path.startsWith('disciplines/'))
+            .map((file) => file.path.split('/')[1]))].sort(compareCanonicalText));
+    const roleNames = Object.freeze([...new Set(files
+            .filter((file) => file.path.startsWith('roles/'))
+            .map((file) => file.path.split('/')[1]))].sort(compareCanonicalText));
+    for (const skill of skillNames) {
+        if (!files.some((file) => file.path === `skills/${skill}/SKILL.md`))
+            fail(`skill_entry_missing:${skill}`);
+    }
+    for (const discipline of disciplineNames) {
+        if (!files.some((file) => file.path === `disciplines/${discipline}/SKILL.md`))
+            fail(`discipline_entry_missing:${discipline}`);
+    }
+    for (const role of roleNames) {
+        if (!files.some((file) => file.path === `roles/${role}/ROLE.md`))
+            fail(`role_entry_missing:${role}`);
+    }
+    if (skillNames.length === 0 || userGuidePaths.length === 0)
+        fail('incomplete_public_asset_set');
+    return Object.freeze({ releaseRoot: normalizedRoot, index, archivePath, files, skillNames, userGuidePaths, disciplineNames, roleNames });
+}
+export function resolveSimpleAgentAssetsRoots(options = {}) {
+    const env = options.env ?? process.env;
+    const home = path.resolve(options.homeDir ?? os.homedir());
+    const aopsDataRoot = path.resolve(options.dataRoot ?? env.AOPS_DATA_ROOT ?? path.join(home, '.aops'));
+    return Object.freeze({
+        storeRoot: path.join(aopsDataRoot, 'assets'),
+        runtimeHomes: Object.freeze({
+            codex: path.resolve(options.codexHome ?? env.CODEX_HOME ?? path.join(home, '.codex')),
+            claude: path.resolve(options.claudeHome ?? env.CLAUDE_HOME ?? path.join(home, '.claude')),
+        }),
+    });
+}
+export function resolveSimpleAgentAssetsTargets(target) {
+    if (target === undefined || target === 'all')
+        return SIMPLE_AGENT_ASSETS_RUNTIME_IDS;
+    const values = Array.isArray(target) ? target : [target];
+    const selected = new Set(values);
+    if ([...selected].some((value) => !SIMPLE_AGENT_ASSETS_RUNTIME_IDS.includes(value))) {
+        fail('invalid_target');
+    }
+    return Object.freeze(SIMPLE_AGENT_ASSETS_RUNTIME_IDS.filter((runtime) => selected.has(runtime)));
+}
+function statePath(roots) {
+    return path.join(roots.storeRoot, 'state.json');
+}
+export function readSimpleAgentAssetsState(roots) {
+    const file = statePath(roots);
+    if (!existsSync(file))
+        return Object.freeze({ schemaVersion: 1, current: null, previous: null, updatedAt: null });
+    const record = asRecord(readJson(file));
+    if (record.schemaVersion !== 1)
+        fail('unsupported_state');
+    const current = record.current === null ? null : validateVersion(record.current);
+    const previous = record.previous === null ? null : validateVersion(record.previous);
+    const updatedAt = record.updatedAt === null || typeof record.updatedAt === 'string' ? record.updatedAt : fail('invalid_state');
+    return Object.freeze({ schemaVersion: 1, current, previous, updatedAt });
+}
+function writeState(roots, state) {
+    mkdirSync(roots.storeRoot, { recursive: true });
+    const temporary = `${statePath(roots)}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temporary, statePath(roots));
+}
+function storedReleaseRoot(roots, version) {
+    return path.join(roots.storeRoot, 'releases', validateVersion(version));
+}
+function legacyStoreRoot(roots) {
+    return path.join(path.dirname(roots.storeRoot), 'agent-assets');
+}
+function validateLegacyStore(roots) {
+    const legacyRoot = legacyStoreRoot(roots);
+    if (!existsSync(legacyRoot))
+        return null;
+    const stat = lstatSync(legacyRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        fail('unsafe_legacy_store');
+    return legacyRoot;
+}
+function writeExtractedFiles(root, release) {
+    for (const file of release.files) {
+        const destination = path.join(root, 'files', ...file.path.split('/'));
+        mkdirSync(path.dirname(destination), { recursive: true });
+        writeFileSync(destination, file.bytes, { mode: 0o644 });
+    }
+}
+function storeRelease(roots, release) {
+    const releasesRoot = path.join(roots.storeRoot, 'releases');
+    mkdirSync(releasesRoot, { recursive: true });
+    const destination = storedReleaseRoot(roots, release.index.version);
+    if (existsSync(destination)) {
+        const existing = loadSimpleAgentAssetsRelease(destination);
+        if (existing.index.sha256 !== release.index.sha256)
+            fail('version_archive_conflict');
+        return destination;
+    }
+    const temporary = mkdtempSync(path.join(releasesRoot, '.stage-'));
+    try {
+        cpSync(path.join(release.releaseRoot, RELEASE_INDEX), path.join(temporary, RELEASE_INDEX));
+        cpSync(release.archivePath, path.join(temporary, release.index.archive));
+        writeExtractedFiles(temporary, release);
+        renameSync(temporary, destination);
+        return destination;
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+}
+function backupName() {
+    return `${new Date().toISOString().replaceAll(':', '-').replaceAll('.', '-')}-${randomUUID().slice(0, 8)}`;
+}
+function installFiles(storedRoot, release, managedSkillNames, roots, targets, commit) {
+    const backupRoot = path.join(roots.storeRoot, 'backups', backupName());
+    const changed = [];
+    const stages = new Set();
+    mkdirSync(backupRoot, { recursive: true });
+    try {
+        for (const runtime of targets) {
+            const skillsRoot = path.join(roots.runtimeHomes[runtime], 'skills');
+            for (const skill of managedSkillNames) {
+                const destination = path.join(skillsRoot, skill);
+                if (!existsSync(destination))
+                    continue;
+                const destinationStat = lstatSync(destination);
+                if (!destinationStat.isDirectory() || destinationStat.isSymbolicLink()) {
+                    fail(`unsafe_existing_skill:${runtime}:${skill}`);
+                }
+            }
+        }
+        for (const runtime of targets) {
+            const skillsRoot = path.join(roots.runtimeHomes[runtime], 'skills');
+            mkdirSync(skillsRoot, { recursive: true });
+            for (const skill of managedSkillNames) {
+                const destination = path.join(skillsRoot, skill);
+                const backup = path.join(backupRoot, runtime, skill);
+                const existed = existsSync(destination);
+                if (existed) {
+                    mkdirSync(path.dirname(backup), { recursive: true });
+                    cpSync(destination, backup, { recursive: true });
+                }
+                changed.push({ destination, backup, existed });
+                rmSync(destination, { recursive: true, force: true });
+                if (release.skillNames.includes(skill)) {
+                    const source = path.join(storedRoot, 'files', 'skills', skill);
+                    const stage = path.join(skillsRoot, `.aops-assets-${skill}-${randomUUID()}`);
+                    stages.add(stage);
+                    cpSync(source, stage, { recursive: true });
+                    renameSync(stage, destination);
+                    stages.delete(stage);
+                }
+            }
+        }
+        writeFileSync(path.join(backupRoot, 'backup.json'), `${JSON.stringify({
+            schemaVersion: 1,
+            version: release.index.version,
+            targets,
+            skills: release.skillNames,
+            cleanedSkills: managedSkillNames,
+        }, null, 2)}\n`, { mode: 0o600 });
+        commit(backupRoot);
+        return backupRoot;
+    }
+    catch (error) {
+        for (const stage of stages)
+            rmSync(stage, { recursive: true, force: true });
+        for (const item of changed.reverse()) {
+            rmSync(item.destination, { recursive: true, force: true });
+            if (item.existed)
+                cpSync(item.backup, item.destination, { recursive: true });
+        }
+        throw error;
+    }
+}
+export function installSimpleAgentAssets(options) {
+    const roots = options.roots ?? resolveSimpleAgentAssetsRoots();
+    const targets = resolveSimpleAgentAssetsTargets(options.target);
+    const release = loadSimpleAgentAssetsRelease(options.releaseRoot);
+    const legacyRoot = validateLegacyStore(roots);
+    const before = readSimpleAgentAssetsState(roots);
+    const previousRelease = before.current
+        ? loadSimpleAgentAssetsRelease(storedReleaseRoot(roots, before.current))
+        : null;
+    const managedSkillNames = Object.freeze([...new Set([
+            ...(previousRelease?.skillNames ?? []),
+            ...release.skillNames,
+        ])].sort(compareCanonicalText));
+    const storedRoot = storeRelease(roots, release);
+    const sameVersion = before.current === release.index.version;
+    const next = Object.freeze({
+        schemaVersion: 1,
+        current: release.index.version,
+        previous: sameVersion ? before.previous : before.current,
+        updatedAt: new Date().toISOString(),
+    });
+    const backupRoot = installFiles(storedRoot, release, managedSkillNames, roots, targets, () => writeState(roots, next));
+    if (legacyRoot)
+        rmSync(legacyRoot, { recursive: true });
+    const assetsRoot = path.join(storedRoot, 'files');
+    return Object.freeze({
+        version: release.index.version,
+        previousVersion: next.previous,
+        targets,
+        skillCount: release.skillNames.length,
+        userGuideCount: release.userGuidePaths.length,
+        disciplineCount: release.disciplineNames.length,
+        roleCount: release.roleNames.length,
+        fileCount: release.files.length,
+        assetsRoot,
+        userGuidesRoot: path.join(assetsRoot, 'docs', 'user-guides'),
+        disciplinesRoot: path.join(assetsRoot, 'disciplines'),
+        rolesRoot: path.join(assetsRoot, 'roles'),
+        backupRoot,
+        repaired: sameVersion,
+        legacyStoreRemoved: legacyRoot !== null,
+    });
+}
+export function rollbackSimpleAgentAssets(options = {}) {
+    const roots = options.roots ?? resolveSimpleAgentAssetsRoots();
+    const state = readSimpleAgentAssetsState(roots);
+    if (!state.previous)
+        fail('previous_release_missing');
+    return installSimpleAgentAssets({
+        releaseRoot: storedReleaseRoot(roots, state.previous),
+        roots,
+        target: options.target,
+    });
+}
+export async function downloadSimpleAgentAssetsRelease(options = {}) {
+    const fetcher = options.fetcher ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const selector = options.tag
+        ? `tags/${encodeURIComponent(validateVersion(options.tag))}`
+        : 'latest';
+    const response = await fetcher(`https://api.github.com/repos/${AOPS_ASSETS_REPOSITORY}/releases/${selector}`, {
+        headers: { accept: 'application/vnd.github+json', 'user-agent': 'aops-cli' },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok)
+        fail(`github_release_unavailable:${response.status}`);
+    const release = asRecord(await response.json());
+    if (!Array.isArray(release.assets))
+        fail('github_release_assets_missing');
+    const assets = new Map(release.assets.map((candidate) => {
+        const row = asRecord(candidate);
+        return [row.name, row.browser_download_url];
+    }));
+    const indexUrl = assets.get(RELEASE_INDEX);
+    if (typeof indexUrl !== 'string')
+        fail('github_release_index_missing');
+    const temporary = mkdtempSync(path.join(os.tmpdir(), 'aops-assets-download-'));
+    try {
+        const indexResponse = await fetcher(indexUrl, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!indexResponse.ok)
+            fail(`github_release_index_download_failed:${indexResponse.status}`);
+        writeFileSync(path.join(temporary, RELEASE_INDEX), Buffer.from(await indexResponse.arrayBuffer()));
+        const index = readSimpleAgentAssetsReleaseIndex(temporary);
+        const archiveUrl = assets.get(index.archive);
+        if (typeof archiveUrl !== 'string')
+            fail('github_release_archive_missing');
+        const archiveResponse = await fetcher(archiveUrl, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!archiveResponse.ok)
+            fail(`github_release_archive_download_failed:${archiveResponse.status}`);
+        writeFileSync(path.join(temporary, index.archive), Buffer.from(await archiveResponse.arrayBuffer()));
+        loadSimpleAgentAssetsRelease(temporary);
+        return temporary;
+    }
+    catch (error) {
+        rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+}
+export function removeDownloadedSimpleAgentAssetsRelease(releaseRoot) {
+    const normalized = path.resolve(releaseRoot);
+    if (path.basename(normalized).startsWith('aops-assets-download-') && path.dirname(normalized) === os.tmpdir()) {
+        rmSync(normalized, { recursive: true, force: true });
+    }
+}