@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/app-recipes.js

@@ -0,0 +1,116 @@
+import { parsePortableInstallationMethod, PROJECT_HOSTS, } from "./project-manifest.js";
+export const APP_GITHUB_PATTERN = "^[\\w-][\\w.-]*/[\\w-][\\w.-]*$";
+export const APP_NPM_PATTERN = "^(?:@[a-z0-9~-][a-z0-9._~-]*/)?[a-z0-9~-][a-z0-9._~-]*$";
+export const APP_SKILL_PATTERN = "^(?!\\*+$)(?!\\s*$)[^/\\\\\\u0000]+$";
+function object(value, keys, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${field}: expected an object`);
+    }
+    const record = value;
+    const unsupported = Object.keys(record).find((key) => !keys.includes(key));
+    if (unsupported !== undefined)
+        throw new Error(`${field}.${unsupported}: unsupported recipe field`);
+    return record;
+}
+function text(value, field) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${field}: expected non-empty text`);
+    return value;
+}
+function argv(value, field) {
+    return parsePortableInstallationMethod({ kind: "command", argv: value }, { label: `${field}:` }).argv;
+}
+function step(value, field) {
+    const item = object(value, ["argv", "manual"], field);
+    if (item.argv === undefined && item.manual === undefined) {
+        throw new Error(`${field}: step needs argv or manual`);
+    }
+    return {
+        ...(item.argv === undefined ? {} : { argv: argv(item.argv, `${field}.argv`) }),
+        ...(item.manual === undefined ? {} : { manual: text(item.manual, `${field}.manual`) }),
+    };
+}
+function version(value, field) {
+    const item = object(value, ["argv", "pattern"], field);
+    const pattern = text(item.pattern, `${field}.pattern`);
+    try {
+        new RegExp(pattern);
+    }
+    catch (error) {
+        throw new Error(`${field}.pattern: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Count captures while ignoring escapes, character classes and non-capturing/lookaround groups.
+    let captures = 0;
+    let inClass = false;
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (pattern[i] === "[")
+            inClass = true;
+        if (pattern[i] === "]")
+            inClass = false;
+        const namedCapture = /^\?<[^=!]/u.test(pattern.slice(i + 1));
+        if (!inClass && pattern[i] === "(" && (pattern[i + 1] !== "?" || namedCapture))
+            captures++;
+    }
+    if (captures !== 1)
+        throw new Error(`${field}.pattern: expected exactly one capture group`);
+    return { argv: argv(item.argv, `${field}.argv`), pattern };
+}
+function hosts(value, field) {
+    return Object.fromEntries(Object.entries(object(value, PROJECT_HOSTS, field)).map(([host, item]) => [host, step(item, `${field}.${host}`)]));
+}
+function latest(value) {
+    const item = object(value, ["github", "npm", "argv", "pattern"], "latest");
+    if (Object.keys(item).length === 1 && item.github !== undefined) {
+        const github = text(item.github, "latest.github");
+        if (!new RegExp(APP_GITHUB_PATTERN).test(github))
+            throw new Error("latest.github: expected owner/repo");
+        return { github };
+    }
+    if (Object.keys(item).length === 1 && item.npm !== undefined) {
+        const npm = text(item.npm, "latest.npm");
+        if (npm.length > 214 || !new RegExp(APP_NPM_PATTERN).test(npm) || ["node_modules", "favicon.ico"].includes(npm)) {
+            throw new Error("latest.npm: expected a valid npm package name");
+        }
+        return { npm };
+    }
+    return version(item, "latest");
+}
+export function parseAppRecipe(value) {
+    const item = object(value, [
+        "name", "platform", "homepage", "install", "update", "uninstall", "version",
+        "latest", "setup", "teardown", "skills",
+    ], "recipe");
+    if (item.platform !== undefined && (typeof item.platform !== "string" || !["linux", "windows", "darwin"].includes(item.platform))) {
+        throw new Error("platform: unsupported platform");
+    }
+    let skills;
+    if (item.skills !== undefined) {
+        if (!Array.isArray(item.skills))
+            throw new Error("skills: expected a list");
+        skills = [];
+        for (const [index, skill] of item.skills.entries()) {
+            const pattern = text(skill, `skills[${index}]`);
+            if (!new RegExp(APP_SKILL_PATTERN, "u").test(pattern)) {
+                throw new Error(`skills[${index}]: expected a non-empty name pattern without path separators or NUL, and not only stars`);
+            }
+            skills.push(pattern);
+        }
+    }
+    return {
+        name: text(item.name, "name"),
+        install: step(item.install, "install"),
+        update: step(item.update, "update"),
+        uninstall: step(item.uninstall, "uninstall"),
+        version: version(item.version, "version"),
+        ...(item.platform === undefined ? {} : { platform: item.platform }),
+        ...(item.homepage === undefined ? {} : { homepage: text(item.homepage, "homepage") }),
+        ...(item.latest === undefined ? {} : { latest: latest(item.latest) }),
+        ...(item.setup === undefined ? {} : { setup: hosts(item.setup, "setup") }),
+        ...(item.teardown === undefined ? {} : { teardown: hosts(item.teardown, "teardown") }),
+        ...(skills === undefined ? {} : { skills }),
+    };
+}

package/dist/src/app-schema.js

@@ -0,0 +1,45 @@
+import { APP_GITHUB_PATTERN, APP_NPM_PATTERN, APP_SKILL_PATTERN } from "./app-recipes.js";
+import { PROJECT_HOSTS } from "./project-manifest.js";
+const argv = {
+    type: "array", minItems: 1, items: { type: "string", minLength: 1 },
+    description: "Bare no-shell executable and arguments; user-method safety rules also apply.",
+};
+const text = { type: "string", minLength: 1 };
+const step = {
+    type: "object", additionalProperties: false,
+    properties: { argv, manual: text },
+    anyOf: [{ required: ["argv"] }, { required: ["manual"] }],
+};
+const version = {
+    type: "object", additionalProperties: false, required: ["argv", "pattern"],
+    properties: {
+        argv, pattern: { ...text, description: "Valid JavaScript regex with exactly one capture group." },
+    },
+};
+const hosts = {
+    type: "object", additionalProperties: false,
+    properties: Object.fromEntries(PROJECT_HOSTS.map((host) => [host, step])),
+};
+export const APP_RECIPE_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "Agent Depot App recipe", type: "object", additionalProperties: false,
+    required: ["name", "install", "update", "uninstall", "version"],
+    properties: {
+        name: text, platform: { enum: ["linux", "windows", "darwin"] }, homepage: text,
+        install: step, update: step, uninstall: step, version,
+        latest: {
+            oneOf: [
+                version,
+                {
+                    type: "object", additionalProperties: false, required: ["github"],
+                    properties: { github: { ...text, pattern: APP_GITHUB_PATTERN } },
+                },
+                {
+                    type: "object", additionalProperties: false, required: ["npm"],
+                    properties: { npm: { ...text, pattern: APP_NPM_PATTERN, maxLength: 214, not: { enum: ["node_modules", "favicon.ico"] } } },
+                },
+            ],
+        },
+        setup: hosts, teardown: hosts, skills: { type: "array", items: { ...text, pattern: APP_SKILL_PATTERN } },
+    },
+};

package/dist/src/app-version.js

@@ -0,0 +1,46 @@
+/** Strict SemVer ordering; unlike Skill's permissive comparator, opaque inputs stay distinguishable. */
+export function compareAppVersions(left, right) {
+    const parse = (value) => {
+        const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/u.exec(normalizeAppVersion(value));
+        if (!match)
+            return undefined;
+        const pre = match[4]?.split(".") ?? [];
+        if (pre.some(part => /^\d+$/u.test(part) && /^0\d/u.test(part)))
+            return undefined;
+        return { core: match.slice(1, 4).map(part => BigInt(part)), pre };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (!a || !b)
+        return undefined;
+    for (let index = 0; index < 3; index++) {
+        if (a.core[index] !== b.core[index])
+            return a.core[index] < b.core[index] ? -1 : 1;
+    }
+    if (!a.pre.length || !b.pre.length)
+        return Math.sign(b.pre.length - a.pre.length);
+    for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index++) {
+        const x = a.pre[index];
+        const y = b.pre[index];
+        if (x === y)
+            continue;
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const numericX = /^\d+$/u.test(x);
+        const numericY = /^\d+$/u.test(y);
+        if (numericX && numericY)
+            return BigInt(x) < BigInt(y) ? -1 : 1;
+        if (numericX !== numericY)
+            return numericX ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+export function normalizeAppVersion(version) {
+    return version.replace(/^v(?=\d)/u, "");
+}
+export function sameAppVersion(left, right) {
+    return compareAppVersions(left, right) === 0 || normalizeAppVersion(left) === normalizeAppVersion(right);
+}

package/dist/src/atomic-file.js

@@ -0,0 +1,26 @@
+import { randomUUID } from "node:crypto";
+import { rename, unlink, writeFile } from "node:fs/promises";
+/** Write a unique temporary sibling, then publish it with rename. */
+export async function writeFileAtomically(file, contents, options = {}) {
+    const temporaryPath = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx", mode: options.mode });
+        try {
+            await rename(temporaryPath, file);
+        }
+        catch (error) {
+            const code = error.code;
+            if (!options.allowLockedReplaceFallback || !["EEXIST", "EPERM", "ENOTEMPTY"].includes(code ?? "")) {
+                throw error;
+            }
+            // Source state holds its read-modify-write lock while using this Windows fallback.
+            await writeFile(file, contents, "utf8");
+        }
+    }
+    finally {
+        await unlink(temporaryPath).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+    }
+}