@kylecheng3146/agent-ops 0.0.1

package/dist/runtime/src/fs/hash.js

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export async function hashFile(path) {
+    try {
+        return sha256(await readFile(path));
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}

package/dist/runtime/src/fs/managed-block.js

@@ -0,0 +1,90 @@
+import { AgentOpsError } from "./paths.js";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function assertBlockId(id) {
+    if (!/^[a-z][a-z0-9-]{0,127}$/.test(id)) {
+        throw new AgentOpsError("INVALID_BLOCK_ID", `Invalid block ID: ${id}`);
+    }
+}
+function assertExactMarkerSyntax(source) {
+    const validMarker = /^<!-- agent-ops:(?:start [a-z][a-z0-9-]{0,127} v[1-9][0-9]*|end [a-z][a-z0-9-]{0,127}) -->$/;
+    for (const line of source.split(/\r?\n/)) {
+        if (/<!--\s*agent-ops:/.test(line) && !validMarker.test(line)) {
+            throw new AgentOpsError("MALFORMED_MANAGED_BLOCK", "Managed block markers must use the exact agent-ops marker syntax.");
+        }
+    }
+}
+export function managedBlockMarkers(id, version) {
+    assertBlockId(id);
+    if (!Number.isSafeInteger(version) || version < 1) {
+        throw new AgentOpsError("INVALID_BLOCK_VERSION", `Invalid block version: ${version}`);
+    }
+    return {
+        start: `<!-- agent-ops:start ${id} v${version} -->`,
+        end: `<!-- agent-ops:end ${id} -->`
+    };
+}
+function locateMarkers(source, id, version) {
+    assertBlockId(id);
+    assertExactMarkerSyntax(source);
+    const escapedId = escapeRegExp(id);
+    const startMatches = [
+        ...source.matchAll(new RegExp(`<!-- agent-ops:start ${escapedId} v[0-9]+ -->`, "g"))
+    ];
+    const end = `<!-- agent-ops:end ${id} -->`;
+    const endMatches = [...source.matchAll(new RegExp(escapeRegExp(end), "g"))];
+    if (startMatches.length === 0 && endMatches.length === 0) {
+        return null;
+    }
+    const expectedStart = version === undefined ? startMatches[0]?.[0] : managedBlockMarkers(id, version).start;
+    const start = startMatches[0]?.[0];
+    const startIndex = startMatches[0]?.index;
+    const endIndex = endMatches[0]?.index;
+    if (startMatches.length !== 1 ||
+        endMatches.length !== 1 ||
+        start === undefined ||
+        expectedStart === undefined ||
+        start !== expectedStart ||
+        startIndex === undefined ||
+        endIndex === undefined ||
+        startIndex >= endIndex) {
+        throw new AgentOpsError("MALFORMED_MANAGED_BLOCK", `Managed block markers are missing, duplicated, reversed, or version-mismatched: ${id}`);
+    }
+    return { start, end, startIndex, endIndex };
+}
+function renderBlock(options) {
+    if (/<!--\s*agent-ops:/.test(options.content)) {
+        throw new AgentOpsError("AMBIGUOUS_MANAGED_CONTENT", "Managed content must not contain agent-ops marker boundaries.");
+    }
+    const { start, end } = managedBlockMarkers(options.id, options.version);
+    const content = options.content.replace(/\r\n/g, "\n").replace(/\n+$/g, "");
+    return `${start}\n${content}\n${end}`;
+}
+export function applyManagedBlock(source, options) {
+    const block = renderBlock(options);
+    const located = locateMarkers(source, options.id, options.version);
+    if (located === null) {
+        if (source.length === 0) {
+            return `${block}\n`;
+        }
+        return `${source.replace(/\n*$/, "\n\n")}${block}\n`;
+    }
+    return `${source.slice(0, located.startIndex)}${block}${source.slice(located.endIndex + located.end.length)}`;
+}
+export function removeManagedBlock(source, id) {
+    const located = locateMarkers(source, id);
+    if (located === null) {
+        return source;
+    }
+    let before = source.slice(0, located.startIndex);
+    let after = source.slice(located.endIndex + located.end.length);
+    if (before.length === 0 && after === "\n") {
+        return "";
+    }
+    if (before.endsWith("\n\n") && after.startsWith("\n")) {
+        before = before.slice(0, -1);
+        after = after.slice(1);
+    }
+    return `${before}${after}`;
+}

package/dist/runtime/src/fs/manifest.js

@@ -0,0 +1,24 @@
+import { validateManifest } from "../schema/validate.js";
+import { AgentOpsError } from "./paths.js";
+export const PROJECT_MANIFEST_PATH = ".agent-ops/manifest.json";
+export function parseInstallManifest(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch (error) {
+        throw new AgentOpsError("MANIFEST_INVALID_JSON", "The installation manifest is not valid JSON.", { cause: error });
+    }
+    const result = validateManifest(value);
+    if (!result.ok) {
+        throw new AgentOpsError("MANIFEST_INVALID", `${result.errors[0]?.path ?? "$"}: ${result.errors[0]?.message ?? "Invalid installation manifest."}`);
+    }
+    return result.value;
+}
+export function formatInstallManifest(manifest) {
+    const result = validateManifest(manifest);
+    if (!result.ok) {
+        throw new AgentOpsError("MANIFEST_INVALID", `${result.errors[0]?.path ?? "$"}: ${result.errors[0]?.message ?? "Invalid installation manifest."}`);
+    }
+    return `${JSON.stringify(result.value, null, 2)}\n`;
+}

package/dist/runtime/src/fs/mutation-worker.js

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rmdir, rm, stat, unlink } from "node:fs/promises";
+import { sha256 } from "./hash.js";
+class MutationWorkerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function parseRequest(value) {
+    if (value === undefined) {
+        throw new MutationWorkerError("MUTATION_FAILED", "Missing request.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    }
+    catch (error) {
+        throw new MutationWorkerError("MUTATION_FAILED", `Invalid request: ${String(error)}`);
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("action" in parsed) ||
+        !["mkdir", "remove", "rmdir", "write"].includes(String(parsed.action)) ||
+        !("targetName" in parsed) ||
+        typeof parsed.targetName !== "string" ||
+        parsed.targetName.length === 0 ||
+        parsed.targetName === "." ||
+        parsed.targetName === ".." ||
+        parsed.targetName.includes("/") ||
+        parsed.targetName.includes("\\") ||
+        parsed.targetName.includes("\0") ||
+        !("expectedHash" in parsed) ||
+        (parsed.expectedHash !== null &&
+            (typeof parsed.expectedHash !== "string" ||
+                !/^[a-f0-9]{64}$/.test(parsed.expectedHash))) ||
+        !("expectedParentPath" in parsed) ||
+        typeof parsed.expectedParentPath !== "string" ||
+        !("parentDevice" in parsed) ||
+        typeof parsed.parentDevice !== "string" ||
+        !("parentInode" in parsed) ||
+        typeof parsed.parentInode !== "string" ||
+        ((parsed.action === "write" || parsed.action === "mkdir") &&
+            (!("mode" in parsed) ||
+                !Number.isInteger(parsed.mode) ||
+                parsed.mode < 0 ||
+                parsed.mode > 0o777))) {
+        throw new MutationWorkerError("MUTATION_FAILED", "Invalid request.");
+    }
+    return parsed;
+}
+function normalizedPath(path) {
+    return process.platform === "win32" ? path.toLowerCase() : path;
+}
+async function assertAnchoredParent(request) {
+    const [canonicalPath, status] = await Promise.all([
+        realpath("."),
+        stat(".", { bigint: true })
+    ]);
+    if (!status.isDirectory() ||
+        normalizedPath(canonicalPath) !==
+            normalizedPath(request.expectedParentPath) ||
+        status.dev.toString() !== request.parentDevice ||
+        status.ino.toString() !== request.parentInode) {
+        throw new MutationWorkerError("PRECONDITION_CHANGED", "The destination directory changed before mutation.");
+    }
+}
+async function currentHash(targetName) {
+    try {
+        const status = await lstat(targetName);
+        if (!status.isFile() || status.isSymbolicLink()) {
+            throw new MutationWorkerError("PRECONDITION_CHANGED", "The managed target is no longer a regular file.");
+        }
+        return sha256(await readFile(targetName));
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+async function assertTarget(request) {
+    if ((await currentHash(request.targetName)) !== request.expectedHash) {
+        throw new MutationWorkerError("PRECONDITION_CHANGED", "The managed target changed before mutation.");
+    }
+}
+async function readStandardInput() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+async function syncCurrentDirectory() {
+    try {
+        const directory = await open(".", "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            ["EACCES", "EISDIR", "EINVAL", "ENOTSUP", "EPERM"].includes(String(error.code))) {
+            return;
+        }
+        throw error;
+    }
+}
+async function writeTarget(request) {
+    const mode = request.mode;
+    if (mode === undefined) {
+        throw new MutationWorkerError("MUTATION_FAILED", "Missing write mode.");
+    }
+    const temporaryName = `.${request.targetName}.agent-ops-tmp-${randomUUID()}`;
+    let handle;
+    try {
+        const content = await readStandardInput();
+        handle = await open(temporaryName, "wx", 0o600);
+        await handle.writeFile(content);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await chmod(temporaryName, mode);
+        await assertAnchoredParent(request);
+        await assertTarget(request);
+        await rename(temporaryName, request.targetName);
+        await syncCurrentDirectory();
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(temporaryName, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function run() {
+    const request = parseRequest(process.argv[2]);
+    await assertAnchoredParent(request);
+    if (request.action === "write") {
+        await assertTarget(request);
+        await writeTarget(request);
+    }
+    else if (request.action === "remove") {
+        await assertTarget(request);
+        await unlink(request.targetName);
+        await syncCurrentDirectory();
+    }
+    else if (request.action === "mkdir") {
+        await assertTarget(request);
+        const mode = request.mode;
+        if (mode === undefined) {
+            throw new MutationWorkerError("MUTATION_FAILED", "Missing directory mode.");
+        }
+        await mkdir(request.targetName, { mode });
+        await chmod(request.targetName, mode);
+        await syncCurrentDirectory();
+    }
+    else {
+        const status = await lstat(request.targetName);
+        if (!status.isDirectory() || status.isSymbolicLink()) {
+            throw new MutationWorkerError("PRECONDITION_CHANGED", "The cleanup target is no longer a directory.");
+        }
+        await rmdir(request.targetName);
+        await syncCurrentDirectory();
+    }
+}
+run().catch((error) => {
+    const code = error instanceof MutationWorkerError
+        ? error.code
+        : "MUTATION_FAILED";
+    process.stderr.write(`${code}\n`);
+    process.exitCode = code === "PRECONDITION_CHANGED" ? 10 : 1;
+});

package/dist/runtime/src/fs/paths.js

@@ -0,0 +1,96 @@
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep, win32 } from "node:path";
+const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
+export class AgentOpsError extends Error {
+    code;
+    cause;
+    recoveryPaths;
+    constructor(code, message, options) {
+        super(message);
+        this.name = "AgentOpsError";
+        this.code = code;
+        this.cause = options?.cause;
+        this.recoveryPaths = options?.recoveryPaths;
+    }
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function assertPortableRelativePath(path) {
+    if (path.length === 0 ||
+        path.includes("\0") ||
+        path.includes("\\") ||
+        isAbsolute(path) ||
+        /^[A-Za-z]:/.test(path)) {
+        throw new AgentOpsError("PATH_OUTSIDE_ROOT", `Path must be portable and relative: ${path}`);
+    }
+    const segments = path.split("/");
+    if (segments.some((segment) => segment.length === 0 ||
+        segment === "." ||
+        segment === ".." ||
+        segment.endsWith(".") ||
+        WINDOWS_RESERVED_SEGMENT.test(segment) ||
+        !/^[A-Za-z0-9._-]+$/.test(segment))) {
+        throw new AgentOpsError("PATH_OUTSIDE_ROOT", `Path contains an unsafe segment: ${path}`);
+    }
+    return segments;
+}
+function assertContained(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    if (fromRoot === "" ||
+        fromRoot === ".." ||
+        fromRoot.startsWith(`..${sep}`) ||
+        isAbsolute(fromRoot)) {
+        throw new AgentOpsError("PATH_OUTSIDE_ROOT", `Resolved path escapes the managed root: ${candidate}`);
+    }
+}
+export function sameResolvedPath(left, right, platform = process.platform) {
+    if (platform !== "win32") {
+        return left === right;
+    }
+    return (win32.normalize(left).toLowerCase() ===
+        win32.normalize(right).toLowerCase());
+}
+export async function resolveContainedPath(root, path) {
+    const segments = assertPortableRelativePath(path);
+    const canonicalRoot = await realpath(resolve(root));
+    let current = canonicalRoot;
+    for (let index = 0; index < segments.length; index += 1) {
+        const candidate = join(current, segments[index]);
+        let status;
+        try {
+            status = await lstat(candidate);
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                throw error;
+            }
+            const unresolved = join(current, ...segments.slice(index));
+            assertContained(canonicalRoot, unresolved);
+            return unresolved;
+        }
+        if (status.isSymbolicLink()) {
+            try {
+                const linked = await realpath(candidate);
+                assertContained(canonicalRoot, linked);
+                current = linked;
+            }
+            catch (error) {
+                if (error instanceof AgentOpsError) {
+                    throw error;
+                }
+                throw new AgentOpsError("PATH_OUTSIDE_ROOT", `Symlink target cannot be resolved safely: ${path}`, { cause: error });
+            }
+        }
+        else {
+            const canonical = await realpath(candidate);
+            assertContained(canonicalRoot, canonical);
+            current = canonical;
+        }
+    }
+    assertContained(canonicalRoot, current);
+    return current;
+}