@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/acp/managedPatches.js

@@ -0,0 +1,228 @@
+/** Automatic adapter patches, owned by Axom, never written into npm's shared cache. */
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { installNpxPackage, npmCacheDir, npmPackageName, npmPackageVersion } from './installProbe.js';
+import { packagePatchMatch, packagePatches } from './patchAssets.js';
+const sha = (content) => createHash('sha256').update(content).digest('hex');
+const pending = new Map();
+const warned = new Set();
+function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(message);
+}
+function inside(root, relative) {
+    const target = path.resolve(root, relative);
+    if (!target.startsWith(path.resolve(root) + path.sep))
+        throw new Error('Axom patch path escapes its package');
+    return target;
+}
+/** A matching version and exact original bytes; already-patched or changed originals are rejected. */
+export async function applyPackagePatches(packageDir, recipes) {
+    const output = {};
+    for (const recipe of recipes) {
+        const metadata = JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
+        if (metadata.name !== recipe.package || !packagePatchMatch(recipe, metadata.version)) {
+            throw new Error(`Axom patch '${recipe.id}' does not support ${metadata.name}@${metadata.version}`);
+        }
+        for (const edit of recipe.edits) {
+            const filename = inside(packageDir, edit.file);
+            const original = await readFile(filename, 'utf8');
+            if (sha(original) !== edit.before_sha256 || !edit.before || original.split(edit.before).length !== 2) {
+                throw new Error(`Axom patch '${recipe.id}': original bytes changed in ${edit.file}`);
+            }
+            const patched = original.replace(edit.before, edit.after);
+            if (sha(patched) !== edit.after_sha256)
+                throw new Error(`Axom patch '${recipe.id}': invalid expected output`);
+            await writeFile(filename, patched, 'utf8');
+            output[edit.file] = sha(patched);
+        }
+    }
+    return output;
+}
+/** Whether every edit of `recipe` finds the bytes it was written against, edits on one file applied in order. */
+async function originalsFit(packageDir, recipe) {
+    const files = new Map();
+    for (const edit of recipe.edits) {
+        let content = files.get(edit.file);
+        if (content === undefined) {
+            try {
+                content = await readFile(inside(packageDir, edit.file), 'utf8');
+            }
+            catch {
+                return false;
+            }
+        }
+        if (sha(content) !== edit.before_sha256 || !edit.before || content.split(edit.before).length !== 2)
+            return false;
+        files.set(edit.file, content.replace(edit.before, edit.after));
+    }
+    return true;
+}
+async function cachedModules(name, version, probe) {
+    const root = path.join(npmCacheDir(probe), '_npx');
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const modules = path.join(root, entry.name, 'node_modules');
+        try {
+            const metadata = JSON.parse(await readFile(inside(modules, name + '/package.json'), 'utf8'));
+            if (metadata.name === name && metadata.version === version)
+                return modules;
+        }
+        catch { /* Interrupted/other version of npm's cache. */ }
+    }
+    return undefined;
+}
+/** Called by Install/Update and every real launch, including adapters installed before this CLI. */
+export async function preparePatchedLaunch(agent, launch, adapterRoot, probe, options = {}) {
+    const distribution = agent.distribution.npx;
+    if (!distribution)
+        return launch;
+    const name = npmPackageName(distribution.package);
+    const version = npmPackageVersion(distribution.package);
+    const candidates = (options.recipes ?? packagePatches).filter((patch) => patch.package === name);
+    const matched = candidates.flatMap((recipe) => {
+        const match = version ? packagePatchMatch(recipe, version) : undefined;
+        return match ? [{ recipe, match }] : [];
+    });
+    if (matched.length && (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name) || !version || !/^[0-9a-z.+-]+$/i.test(version))) {
+        throw new Error('Invalid package identity for Axom adapter patch');
+    }
+    // A range only says a recipe may fit; the pristine package's bytes decide.
+    const fitting = new Set();
+    if (matched.some(({ match }) => match === 'range')) {
+        const modules = await pristineModules();
+        for (const { recipe, match } of matched) {
+            if (match !== 'range')
+                continue;
+            if (await originalsFit(inside(modules, name), recipe))
+                fitting.add(recipe);
+            else
+                warnOnce(`${recipe.id}@${distribution.package}`, `[axom-patch] ${recipe.id} does not fit ${distribution.package}; using the upstream package. Review the patch inventory.`);
+        }
+    }
+    const recipes = matched.filter(({ recipe, match }) => match === 'exact' || fitting.has(recipe)).map(({ recipe }) => recipe);
+    if (!recipes.length) {
+        if (candidates.length && !matched.length) {
+            warnOnce(distribution.package, `[axom-patch] No verified patch for ${distribution.package}; using the upstream package. Review the patch inventory.`);
+        }
+        return launch;
+    }
+    const digest = sha(JSON.stringify(recipes));
+    const target = path.join(adapterRoot, 'patched-npm', sha(name).slice(0, 16), version, digest);
+    const existing = pending.get(target);
+    if (existing) {
+        await existing;
+        return makeLaunch();
+    }
+    const preparation = prepare();
+    pending.set(target, preparation);
+    try {
+        await preparation;
+        return await makeLaunch();
+    }
+    finally {
+        pending.delete(target);
+    }
+    async function prepare() {
+        const packageDir = inside(path.join(target, 'node_modules'), name);
+        const receiptFile = path.join(target, 'axom-patches.json');
+        let receipt;
+        try {
+            receipt = JSON.parse(await readFile(receiptFile, 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (receipt) {
+            if (receipt.digest !== digest)
+                throw new Error('Axom adapter patch receipt does not match this CLI');
+            // Derive expected files from the shipped recipe, never from a writable receipt alone.
+            const expected = Object.fromEntries(recipes.flatMap((recipe) => recipe.edits.map((edit) => [edit.file, edit.after_sha256])));
+            if (JSON.stringify(receipt.files) !== JSON.stringify(expected))
+                throw new Error('Incomplete Axom adapter patch receipt');
+            for (const [file, hash] of Object.entries(expected)) {
+                if (sha(await readFile(inside(packageDir, file))) !== hash)
+                    throw new Error(`Axom patched adapter was modified: ${file}`);
+            }
+        }
+        else {
+            try {
+                await stat(target);
+                throw new Error('Incomplete Axom patched adapter directory; refusing to use it');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            const modules = await pristineModules();
+            await mkdir(path.dirname(target), { recursive: true });
+            const temporary = target + '.staging-' + randomUUID();
+            try {
+                // Dependencies and .bin are part of the adapter environment; clone them as well.
+                await cp(modules, path.join(temporary, 'node_modules'), { recursive: true, dereference: true });
+                const files = await applyPackagePatches(inside(path.join(temporary, 'node_modules'), name), recipes);
+                await writeFile(path.join(temporary, 'axom-patches.json'), JSON.stringify({
+                    digest, package: name, version, patches: recipes.map((recipe) => recipe.id), files,
+                }) + '\n');
+                try {
+                    await rename(temporary, target);
+                }
+                catch (error) {
+                    // A second daemon may have published the same immutable copy while we built ours.
+                    if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
+                        throw error;
+                    return prepare();
+                }
+                console.info(`[axom-patch] Applied ${recipes.map((recipe) => recipe.id).join(', ')} to ${name}@${version}`);
+            }
+            finally {
+                await rm(temporary, { recursive: true, force: true });
+            }
+        }
+    }
+    async function pristineModules() {
+        let modules = await cachedModules(name, version, probe);
+        if (!modules) {
+            const installed = await installNpxPackage(distribution.package, {
+                env: probe, timeoutMs: options.timeoutMs, npxCommand: options.npxCommand,
+            });
+            if (!installed.ok)
+                throw new Error(installed.error);
+            modules = await cachedModules(name, version, probe);
+        }
+        if (!modules)
+            throw new Error(`Installed package ${distribution.package} is absent from npm's cache`);
+        return modules;
+    }
+    async function makeLaunch() {
+        const packageDir = inside(path.join(target, 'node_modules'), name);
+        const metadata = JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
+        if (metadata.name !== name || metadata.version !== version)
+            throw new Error('Patched adapter package identity changed');
+        const selectedBins = [...new Set(recipes.map(recipe => recipe.bin).filter((bin) => bin !== undefined))];
+        if (selectedBins.length > 1)
+            throw new Error('Axom patches disagree about the adapter executable');
+        const binaries = selectedBins.length ? [metadata.bin?.[selectedBins[0]]] :
+            typeof metadata.bin === 'string' ? [metadata.bin] : Object.values(metadata.bin ?? {});
+        if (binaries.length !== 1 || typeof binaries[0] !== 'string')
+            throw new Error('Patched adapter has no unambiguous executable');
+        const entry = inside(packageDir, binaries[0]);
+        if (!(await stat(entry)).isFile())
+            throw new Error('Patched adapter executable is missing');
+        const env = { ...launch.env };
+        env.PATH = path.join(target, 'node_modules', '.bin') + path.delimiter + (env.PATH ?? probe.path ?? process.env.PATH ?? '');
+        return { command: process.execPath, args: [entry, ...(distribution.args ?? [])], env };
+    }
+}

package/dist/workstation/acp/patchAssets.js

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+// Production reads only assets shipped in this CLI. The .ts path is for source-based tests.
+export const patchAssetRoot = new URL(import.meta.url.endsWith('.ts') ? '../../../../axom-patch/cli/' : '../../axom-patch/cli/', import.meta.url);
+const runtime = JSON.parse(readFileSync(new URL('runtime.json', patchAssetRoot), 'utf8'));
+if (runtime.schema_version !== 1)
+    throw new Error('Unsupported bundled Axom patch schema');
+for (const entry of runtime.overrides)
+    validateOverride(entry);
+function validateCondition(id, when, until, whenKey, untilKey) {
+    if (when !== undefined && until !== undefined)
+        throw new Error(`Axom patch ${id}: ${whenKey} and ${untilKey} are exclusive`);
+    if (when !== undefined && (!Array.isArray(when) || when.length === 0 || when.some((version) => !semver.valid(version)))) {
+        throw new Error(`Axom patch ${id}: ${whenKey} must list exact versions`);
+    }
+    if (until !== undefined && !semver.valid(until))
+        throw new Error(`Axom patch ${id}: ${untilKey} is not a version`);
+}
+export function validateOverride(entry) {
+    validateCondition(entry.id, entry.when_registry_version, entry.until_registry_version, 'when_registry_version', 'until_registry_version');
+    const until = entry.until_registry_version;
+    // A pin at or past its own bound would be replaced by the registry the moment it applied.
+    if (until !== undefined && entry.distribution && !(semver.valid(entry.distribution.version) && semver.lt(entry.distribution.version, until))) {
+        throw new Error(`Axom patch ${entry.id}: pinned ${entry.distribution.version} must sort below ${until}`);
+    }
+}
+export function validatePackagePatch(recipe) {
+    validateCondition(recipe.id, recipe.versions, recipe.until_version, 'versions', 'until_version');
+    if (recipe.versions === undefined && recipe.until_version === undefined) {
+        throw new Error(`Axom patch ${recipe.id}: needs versions or until_version`);
+    }
+}
+function inRange(version, when, until) {
+    if (when)
+        return semver.valid(version) !== null && when.some((listed) => semver.eq(listed, version));
+    if (until)
+        return !(semver.valid(version) && semver.gte(version, until));
+    return true;
+}
+export function overrideApplies(entry, registryVersion) {
+    return inRange(registryVersion, entry.when_registry_version, entry.until_registry_version);
+}
+/** Exact versions are a promise that the bytes match; a range only says the recipe may fit. */
+export function packagePatchMatch(recipe, version) {
+    if (recipe.versions)
+        return recipe.versions.includes(version) ? 'exact' : undefined;
+    return inRange(version, undefined, recipe.until_version) ? 'range' : undefined;
+}
+/** The overrides that apply to `agent` at `registryVersion`, merged: the first distribution wins, env merges. */
+export function patchOverridesFor(agent, registryVersion, overrides = runtime.overrides) {
+    const matching = overrides.filter((entry) => entry.agent === agent && overrideApplies(entry, registryVersion));
+    const distribution = matching.find((entry) => entry.distribution)?.distribution;
+    const env = Object.assign({}, ...matching.map((entry) => entry.env ?? {}));
+    return { ...(distribution && { distribution }), ...(Object.keys(env).length && { env }) };
+}
+export const packagePatches = runtime.package_patches.map((file) => {
+    if (!/^[a-z0-9-]+\.json$/.test(file))
+        throw new Error('Invalid bundled Axom patch filename');
+    const recipe = JSON.parse(readFileSync(fileURLToPath(new URL(file, patchAssetRoot)), 'utf8'));
+    validatePackagePatch(recipe);
+    return recipe;
+});