akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/execution/executable-identity.js

@@ -1,105 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { isRecord } from "../core/common.js";
-import { UsageError } from "../core/errors.js";
-export function freezeExecutableIdentity(requested, options = {}) {
-    const absolutePath = resolveExecutable(requested, options.cwd ?? process.cwd(), options.path ?? process.env.PATH ?? "");
-    let realPath;
-    let stat;
-    let bytes;
-    try {
-        fs.accessSync(absolutePath, fs.constants.X_OK);
-        realPath = fs.realpathSync(absolutePath);
-        stat = fs.lstatSync(realPath, { bigint: true });
-        if (!stat.isFile() || stat.isSymbolicLink())
-            throw new Error("not a regular executable file");
-        bytes = fs.readFileSync(realPath);
-    }
-    catch {
-        throw new UsageError(`Executable ${JSON.stringify(requested)} could not be frozen.`, "INVALID_FLAG_VALUE");
-    }
-    return Object.freeze({
-        requested,
-        absolutePath,
-        realPath,
-        device: stat.dev.toString(),
-        inode: stat.ino.toString(),
-        size: bytes.byteLength,
-        sha256: createHash("sha256").update(bytes).digest("hex"),
-    });
-}
-export function decodeFrozenExecutableIdentity(value, label = "executable") {
-    if (!isRecord(value))
-        throw invalid(label);
-    const allowed = new Set(["requested", "absolutePath", "realPath", "device", "inode", "size", "sha256"]);
-    for (const key of Object.keys(value))
-        if (!allowed.has(key))
-            throw invalid(label);
-    if (typeof value.requested !== "string" ||
-        typeof value.absolutePath !== "string" ||
-        !path.isAbsolute(value.absolutePath) ||
-        typeof value.realPath !== "string" ||
-        !path.isAbsolute(value.realPath) ||
-        typeof value.device !== "string" ||
-        typeof value.inode !== "string" ||
-        !Number.isSafeInteger(value.size) ||
-        value.size < 0 ||
-        typeof value.sha256 !== "string" ||
-        !/^[0-9a-f]{64}$/.test(value.sha256)) {
-        throw invalid(label);
-    }
-    const decoded = Object.freeze({
-        requested: value.requested,
-        absolutePath: value.absolutePath,
-        realPath: value.realPath,
-        device: value.device,
-        inode: value.inode,
-        size: value.size,
-        sha256: value.sha256,
-    });
-    assertFrozenExecutableIdentity(decoded, label);
-    return decoded;
-}
-export function assertFrozenExecutableIdentity(identity, label = "executable") {
-    let actual;
-    try {
-        actual = freezeExecutableIdentity(identity.absolutePath, { cwd: path.dirname(identity.absolutePath) });
-    }
-    catch {
-        throw changed(label);
-    }
-    for (const key of ["absolutePath", "realPath", "device", "inode", "size", "sha256"]) {
-        if (actual[key] !== identity[key])
-            throw changed(label);
-    }
-}
-function resolveExecutable(requested, cwd, pathValue) {
-    if (requested.includes("/") || requested.includes("\\"))
-        return path.resolve(cwd, requested);
-    const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
-    for (const directory of pathValue.split(path.delimiter)) {
-        if (!directory)
-            continue;
-        for (const extension of extensions) {
-            const candidate = path.resolve(directory, `${requested}${extension}`);
-            try {
-                fs.accessSync(candidate, fs.constants.X_OK);
-                return candidate;
-            }
-            catch {
-                // Continue through the frozen search path.
-            }
-        }
-    }
-    throw new UsageError(`Executable ${JSON.stringify(requested)} was not found.`, "INVALID_FLAG_VALUE");
-}
-function invalid(label) {
-    return new UsageError(`Frozen ${label} identity is invalid.`, "INVALID_FLAG_VALUE");
-}
-function changed(label) {
-    return new UsageError(`Frozen ${label} changed after publication.`, "RESOURCE_ALREADY_EXISTS");
-}

package/dist/execution/guarded-source.js

@@ -1,427 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { parseFrontmatter } from "../core/asset/frontmatter.js";
-import { compareCodePoints, toPosix } from "../core/common.js";
-import { UsageError } from "../core/errors.js";
-import { createExecutionSourceIdentity } from "./source.js";
-function errorMessage(cause) {
-    return cause instanceof Error ? cause.message : String(cause);
-}
-function physicalIdentity(realPath, stat) {
-    return stat.ino === 0n ? `path:${realPath}` : `inode:${stat.dev}:${stat.ino}`;
-}
-function statVersion(stat) {
-    return `${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
-}
-function sameBigIntStat(left, right) {
-    return (left.dev === right.dev &&
-        left.ino === right.ino &&
-        left.mode === right.mode &&
-        left.size === right.size &&
-        left.mtimeNs === right.mtimeNs &&
-        left.ctimeNs === right.ctimeNs);
-}
-function containedRelative(root, candidate, allowRoot) {
-    const relative = path.relative(root, candidate);
-    if ((!allowRoot && relative === "") || relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new UsageError(`${candidate} resolves outside its guarded containment root.`, "PATH_ESCAPE_VIOLATION");
-    }
-    return relative;
-}
-function requireContainmentRoot(containmentRootInput) {
-    const containmentRoot = path.resolve(containmentRootInput);
-    const containmentRealPath = fs.realpathSync(containmentRoot);
-    const containmentStat = fs.statSync(containmentRealPath, { bigint: true });
-    if (!containmentStat.isDirectory()) {
-        throw new UsageError(`${containmentRootInput} is not a guarded source directory.`, "INVALID_FLAG_VALUE");
-    }
-    return { containmentRoot, containmentRealPath, containmentStat };
-}
-function numberStat(stat) {
-    return new Proxy(stat, {
-        get(target, property, receiver) {
-            const value = Reflect.get(target, property, receiver);
-            return typeof value === "bigint" ? Number(value) : value;
-        },
-    });
-}
-function decodeUtf8(bytes, sourcePath) {
-    try {
-        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
-    }
-    catch {
-        throw new UsageError(`${sourcePath} contains invalid UTF-8 bytes.`, "INVALID_FLAG_VALUE");
-    }
-}
-function freezeSource(source) {
-    const identity = source.identity ? createExecutionSourceIdentity(source.identity) : undefined;
-    return Object.freeze({ ...source, ...(identity ? { identity } : {}) });
-}
-function captureRecord(sourcePathInput, containmentRootInput, options = {}) {
-    const sourcePath = path.resolve(sourcePathInput);
-    const { containmentRoot, containmentRealPath, containmentStat } = requireContainmentRoot(containmentRootInput);
-    const lexicalRelative = containedRelative(containmentRoot, sourcePath, false);
-    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-    let descriptor;
-    try {
-        descriptor = fs.openSync(sourcePath, fs.constants.O_RDONLY | noFollow);
-        const before = fs.fstatSync(descriptor, { bigint: true });
-        if (!before.isFile()) {
-            throw new UsageError(`${sourcePath} is not a regular guarded source file.`, "INVALID_FLAG_VALUE");
-        }
-        const bytes = fs.readFileSync(descriptor);
-        const after = fs.fstatSync(descriptor, { bigint: true });
-        if (!sameBigIntStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
-            throw new UsageError(`${sourcePath} changed while its guarded bytes were read.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        const pathnameStat = fs.lstatSync(sourcePath, { bigint: true });
-        if (pathnameStat.isSymbolicLink()) {
-            throw new UsageError(`${sourcePath} is a symbolic source; guarded reads require a regular no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        if (!pathnameStat.isFile() || pathnameStat.dev !== before.dev || pathnameStat.ino !== before.ino) {
-            throw new UsageError(`${sourcePath} changed physical identity during its guarded read.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        const realPath = fs.realpathSync(sourcePath);
-        containedRelative(containmentRealPath, realPath, false);
-        const content = decodeUtf8(bytes, sourcePath);
-        const sha256 = createHash("sha256").update(bytes).digest("hex");
-        if (options.identity && options.identity.hash !== sha256) {
-            throw new UsageError(`${sourcePath} adapter identity hash does not match its guarded bytes.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        if (options.identity && options.identity.file !== toPosix(lexicalRelative)) {
-            throw new UsageError(`${sourcePath} adapter identity file does not match its guarded relative path.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        return {
-            source: freezeSource({
-                sourcePath,
-                relativePath: toPosix(lexicalRelative),
-                realPath,
-                containmentRoot,
-                containmentRealPath,
-                containmentPhysicalIdentity: physicalIdentity(containmentRealPath, containmentStat),
-                physicalIdentity: physicalIdentity(realPath, before),
-                size: bytes.byteLength,
-                mtimeNs: String(before.mtimeNs),
-                ctimeNs: String(before.ctimeNs),
-                sha256,
-                bytesBase64: bytes.toString("base64"),
-                content,
-                authored: options.authored ?? false,
-                ...(options.identity ? { identity: options.identity } : {}),
-            }),
-            stat: numberStat(before),
-        };
-    }
-    catch (cause) {
-        if (cause instanceof UsageError)
-            throw cause;
-        const code = cause.code;
-        if (code === "ELOOP") {
-            let linked;
-            try {
-                linked = fs.realpathSync(sourcePath);
-            }
-            catch {
-                // The no-follow failure itself is sufficient when the link is broken.
-            }
-            if (linked) {
-                const relative = path.relative(containmentRealPath, linked);
-                if (relative.startsWith("..") || path.isAbsolute(relative)) {
-                    throw new UsageError(`${sourcePath} resolves outside its containment root through a symbolic source.`, "PATH_ESCAPE_VIOLATION");
-                }
-            }
-            throw new UsageError(`${sourcePath} is a symbolic source; guarded reads require a regular no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        throw new UsageError(`${sourcePath} could not be guarded as a contained regular source: ${errorMessage(cause)}`, code === "ENOENT" ? "RESOURCE_ALREADY_EXISTS" : "PATH_ESCAPE_VIOLATION");
-    }
-    finally {
-        if (descriptor !== undefined)
-            fs.closeSync(descriptor);
-    }
-}
-export function captureGuardedExecutionSource(sourcePath, containmentRoot, options = {}) {
-    return captureRecord(sourcePath, containmentRoot, options).source;
-}
-export function captureGuardedDirectoryManifest(directoryPathInput, containmentRootInput) {
-    const directoryPath = path.resolve(directoryPathInput);
-    const { containmentRoot, containmentRealPath, containmentStat } = requireContainmentRoot(containmentRootInput);
-    const lexicalRelative = containedRelative(containmentRoot, directoryPath, true);
-    try {
-        const before = fs.lstatSync(directoryPath, { bigint: true });
-        if (before.isSymbolicLink()) {
-            throw new UsageError(`${directoryPath} is a symbolic directory with ambiguous guarded identity.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        if (!before.isDirectory()) {
-            throw new UsageError(`${directoryPath} is not a guarded directory.`, "INVALID_FLAG_VALUE");
-        }
-        const realPath = fs.realpathSync(directoryPath);
-        containedRelative(containmentRealPath, realPath, true);
-        const entries = fs
-            .readdirSync(directoryPath, { withFileTypes: true })
-            .sort((left, right) => compareCodePoints(left.name, right.name))
-            .map((entry) => {
-            const entryPath = path.join(directoryPath, entry.name);
-            const entryStat = fs.lstatSync(entryPath, { bigint: true });
-            if (entry.isSymbolicLink() || entryStat.isSymbolicLink()) {
-                let linked;
-                try {
-                    linked = fs.realpathSync(entryPath);
-                }
-                catch {
-                    // Broken symbolic entries still have ambiguous ownership.
-                }
-                if (linked) {
-                    const relative = path.relative(containmentRealPath, linked);
-                    if (relative.startsWith("..") || path.isAbsolute(relative)) {
-                        throw new UsageError(`${entryPath} resolves outside the bundle root through a symbolic source.`, "PATH_ESCAPE_VIOLATION");
-                    }
-                }
-                throw new UsageError(`${entryPath} is a symbolic source with a physical source identity collision; guarded reads require one no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
-            }
-            const kind = entry.isDirectory() && entryStat.isDirectory()
-                ? "directory"
-                : entry.isFile() && entryStat.isFile()
-                    ? "file"
-                    : undefined;
-            if (!kind) {
-                throw new UsageError(`${entryPath} is neither a regular file nor directory.`, "INVALID_FLAG_VALUE");
-            }
-            const entryRealPath = fs.realpathSync(entryPath);
-            containedRelative(containmentRealPath, entryRealPath, false);
-            return Object.freeze({
-                name: entry.name,
-                kind,
-                physicalIdentity: physicalIdentity(entryRealPath, entryStat),
-                version: statVersion(entryStat),
-            });
-        });
-        const after = fs.lstatSync(directoryPath, { bigint: true });
-        if (!sameBigIntStat(before, after)) {
-            throw new UsageError(`${directoryPath} changed while its guarded directory manifest was read.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        return Object.freeze({
-            directoryPath,
-            relativePath: lexicalRelative === "" ? "." : toPosix(lexicalRelative),
-            realPath,
-            containmentRoot,
-            containmentRealPath,
-            containmentPhysicalIdentity: physicalIdentity(containmentRealPath, containmentStat),
-            physicalIdentity: physicalIdentity(realPath, before),
-            version: statVersion(before),
-            entries: Object.freeze(entries),
-        });
-    }
-    catch (cause) {
-        if (cause instanceof UsageError)
-            throw cause;
-        throw new UsageError(`${directoryPath} could not be captured as a guarded directory manifest: ${errorMessage(cause)}`, cause.code === "ENOENT" ? "RESOURCE_ALREADY_EXISTS" : "PATH_ESCAPE_VIOLATION");
-    }
-}
-function sameSnapshotValue(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
-}
-function sourceSortKey(source) {
-    const identity = source.identity;
-    return identity
-        ? `${identity.ref}\0${identity.adapter}\0${identity.file}`
-        : `${source.containmentRealPath}\0${source.relativePath}`;
-}
-function directorySortKey(manifest) {
-    return `${manifest.containmentRealPath}\0${manifest.relativePath}`;
-}
-export class GuardedExecutionSourceCollector {
-    #sources = new Map();
-    #directories = new Map();
-    capture(sourcePath, containmentRoot, options = {}) {
-        const key = path.resolve(sourcePath);
-        const existing = this.#sources.get(key);
-        if (existing) {
-            if (options.identity)
-                return this.bindIdentity(sourcePath, containmentRoot, options.identity);
-            return existing.source;
-        }
-        const record = captureRecord(sourcePath, containmentRoot, options);
-        this.#assertNoPhysicalOwnerAlias(record.source);
-        this.#sources.set(key, record);
-        return record.source;
-    }
-    readBytes(sourcePath, containmentRoot, options = {}) {
-        return Buffer.from(this.capture(sourcePath, containmentRoot, options).bytesBase64, "base64");
-    }
-    fileContext(root, file, options = {}) {
-        const source = this.capture(file, root, options);
-        const record = this.#sources.get(path.resolve(file));
-        if (!record)
-            throw new Error("guarded source collector lost a captured file");
-        const relPath = source.relativePath;
-        const ext = path.extname(file).toLowerCase();
-        const fileName = path.basename(file);
-        const parentDirAbs = path.dirname(path.resolve(file));
-        const relDir = path.posix.dirname(relPath);
-        const ancestorDirs = relDir === "." ? [] : relDir.split("/").filter(Boolean);
-        let frontmatter;
-        let parsed = false;
-        return {
-            absPath: path.resolve(file),
-            relPath,
-            ext,
-            fileName,
-            parentDir: path.basename(parentDirAbs),
-            parentDirAbs,
-            ancestorDirs,
-            stashRoot: path.resolve(root),
-            content: () => source.content,
-            frontmatter: () => {
-                if (!parsed) {
-                    const result = parseFrontmatter(source.content);
-                    frontmatter = Object.keys(result.data).length > 0 ? result.data : null;
-                    parsed = true;
-                }
-                return frontmatter ?? null;
-            },
-            stat: () => record.stat,
-        };
-    }
-    bindIdentity(sourcePath, containmentRoot, identityInput) {
-        const key = path.resolve(sourcePath);
-        const existing = this.#sources.get(key) ?? captureRecord(sourcePath, containmentRoot);
-        const identity = createExecutionSourceIdentity(identityInput);
-        if (identity.file !== existing.source.relativePath || identity.hash !== existing.source.sha256) {
-            throw new UsageError(`${sourcePath} adapter identity does not match its guarded file owner or bytes.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        if (existing.source.identity) {
-            if (!sameSnapshotValue(existing.source.identity, identity)) {
-                throw new UsageError(`${sourcePath} already has a different guarded logical owner identity.`, "RESOURCE_ALREADY_EXISTS");
-            }
-            return existing.source;
-        }
-        const source = freezeSource({ ...existing.source, identity });
-        this.#assertNoPhysicalOwnerAlias(source, key);
-        this.#sources.set(key, { ...existing, source });
-        return source;
-    }
-    trackDirectory(directoryPath, containmentRoot) {
-        const manifest = captureGuardedDirectoryManifest(directoryPath, containmentRoot);
-        const key = path.resolve(directoryPath);
-        const existing = this.#directories.get(key);
-        if (existing && !sameSnapshotValue(existing, manifest)) {
-            throw new UsageError(`${directoryPath} changed between guarded directory reads.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        if (!existing)
-            this.#directories.set(key, manifest);
-        return existing ?? manifest;
-    }
-    enumerateTree(directoryPath, containmentRoot) {
-        const files = [];
-        const visit = (directory) => {
-            const manifest = this.trackDirectory(directory, containmentRoot);
-            for (const entry of manifest.entries) {
-                const candidate = path.join(directory, entry.name);
-                if (entry.kind === "directory")
-                    visit(candidate);
-                else
-                    files.push(candidate);
-            }
-        };
-        visit(path.resolve(directoryPath));
-        return Object.freeze(files.sort(compareCodePoints));
-    }
-    snapshot() {
-        return Object.freeze({
-            sources: Object.freeze([...this.#sources.values()]
-                .map((record) => record.source)
-                .sort((left, right) => compareCodePoints(sourceSortKey(left), sourceSortKey(right)))),
-            directoryManifests: Object.freeze([...this.#directories.values()].sort((left, right) => compareCodePoints(directorySortKey(left), directorySortKey(right)))),
-        });
-    }
-    /**
-     * Merge another collector's captured sources and directory manifests into
-     * this one (A-N7, spec docs/plans/specs/p3a-plan-v5-child-freeze.md §4.2
-     * step 6). The recursive child-workflow freeze gives each child its OWN
-     * fresh collector, so a child's plan (and therefore its `planHash`) is a
-     * pure function of its own source, independent of its position in the
-     * parent (A-N7's rejected alternative: sharing the parent's collector,
-     * which would make an identical child hash differently depending on what
-     * the parent had already captured). The parent then absorbs the child's
-     * records so its own final pre-publication CAS ({@link revalidate}) covers
-     * every child file too.
-     *
-     * Re-runs `#assertNoPhysicalOwnerAlias` for each newly-absorbed source
-     * record, so the shared-physical-owner authority holds ACROSS the
-     * composition, not just within one workflow's own freeze. A record whose
-     * key (resolved source path) is already present is required to be
-     * byte-identical to the one already held — two DISJOINT branches
-     * composing the SAME child (a diamond, not a cycle) absorb the same file
-     * twice with identical content and pass silently; two branches that
-     * somehow captured the same path with different content fail closed.
-     */
-    absorb(other) {
-        for (const [key, record] of other.#sources) {
-            const existing = this.#sources.get(key);
-            if (existing) {
-                if (!sameSnapshotValue(existing.source, record.source)) {
-                    throw new UsageError(`${record.source.sourcePath} was captured with conflicting content across a composed workflow freeze.`, "RESOURCE_ALREADY_EXISTS");
-                }
-                continue;
-            }
-            this.#assertNoPhysicalOwnerAlias(record.source);
-            this.#sources.set(key, record);
-        }
-        for (const [key, manifest] of other.#directories) {
-            const existing = this.#directories.get(key);
-            if (existing) {
-                if (!sameSnapshotValue(existing, manifest)) {
-                    throw new UsageError(`${manifest.directoryPath} changed between guarded directory reads across a composed workflow freeze.`, "RESOURCE_ALREADY_EXISTS");
-                }
-                continue;
-            }
-            this.#directories.set(key, manifest);
-        }
-    }
-    revalidate() {
-        for (const record of this.#sources.values()) {
-            let current;
-            try {
-                current = captureRecord(record.source.sourcePath, record.source.containmentRoot, {
-                    authored: record.source.authored,
-                    ...(record.source.identity ? { identity: record.source.identity } : {}),
-                }).source;
-            }
-            catch (cause) {
-                throw new UsageError(`Guarded execution source read set changed before publication: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
-            }
-            if (!sameSnapshotValue(record.source, current)) {
-                throw new UsageError("Guarded execution source read set changed before publication.", "RESOURCE_ALREADY_EXISTS");
-            }
-        }
-        for (const manifest of this.#directories.values()) {
-            let current;
-            try {
-                current = captureGuardedDirectoryManifest(manifest.directoryPath, manifest.containmentRoot);
-            }
-            catch (cause) {
-                throw new UsageError(`Guarded execution source directory manifest changed before publication: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
-            }
-            if (!sameSnapshotValue(manifest, current)) {
-                throw new UsageError("Guarded execution source directory manifest changed before publication.", "RESOURCE_ALREADY_EXISTS");
-            }
-        }
-    }
-    #assertNoPhysicalOwnerAlias(candidate, selfKey) {
-        if (!candidate.identity)
-            return;
-        for (const [key, record] of this.#sources) {
-            if (key === selfKey || !record.source.identity)
-                continue;
-            if (record.source.containmentPhysicalIdentity === candidate.containmentPhysicalIdentity &&
-                record.source.physicalIdentity === candidate.physicalIdentity &&
-                !sameSnapshotValue(record.source.identity, candidate.identity)) {
-                throw new UsageError(`${candidate.sourcePath} aliases the same physical source and root under a different logical owner.`, "RESOURCE_ALREADY_EXISTS");
-            }
-        }
-    }
-}