@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/update-batch.js

@@ -0,0 +1,376 @@
+import { builtinPinMismatch, parseProjectManifest, } from "./project-manifest.js";
+import { resolveProjectSource, } from "./sources.js";
+import { skillTreeBaseline, } from "./skill-discovery.js";
+const immutableAssessmentSnapshots = new WeakMap();
+export class UpdateBatchSelectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UpdateBatchSelectionError";
+    }
+}
+/**
+ * Assesses every installed selection against a separately captured current
+ * Source snapshot. A missing or untrusted version is never promoted to an
+ * updateable result.
+ */
+export async function assessUpdateBatch(value, options) {
+    const rawSelections = Array.isArray(value)
+        ? value
+        : parseProjectManifest(value).skills;
+    const resolveSource = options.resolveSource ?? resolveProjectSource;
+    const items = await Promise.all(rawSelections.map(async (rawSelection, index) => {
+        const parsed = parseRuntimeSelection(rawSelection);
+        if (!parsed.selection) {
+            return malformedSelectionAssessment(rawSelection, index, parsed.reason);
+        }
+        return assessSelection(parsed.selection, index, resolveSource, options.sourceAccess);
+    }));
+    const frozenItems = Object.freeze(items);
+    return Object.freeze({
+        items: frozenItems,
+        updateable: Object.freeze(items.filter((item) => item.status === "updateable")),
+        current: Object.freeze(items.filter((item) => item.status === "current")),
+        unknown: Object.freeze(items.filter((item) => item.status === "unknown")),
+    });
+}
+/** Selects all updateable entries or validates an explicit updateable subset. */
+export function selectUpdateBatch(assessment, request) {
+    let ids;
+    if (request === "all") {
+        return assessment.updateable;
+    }
+    if (Array.isArray(request)) {
+        ids = request;
+    }
+    else if (!isModeSelection(request)) {
+        throw new UpdateBatchSelectionError("Update batch selection must specify mode 'all' or a subset of ids");
+    }
+    else {
+        const candidate = request;
+        if (candidate.mode === "all") {
+            return assessment.updateable;
+        }
+        if (candidate.mode === "subset" && Array.isArray(candidate.ids)) {
+            ids = candidate.ids;
+        }
+        else {
+            throw new UpdateBatchSelectionError("Update batch selection must specify mode 'all' or a subset of ids");
+        }
+    }
+    if (ids.length === 0) {
+        throw new UpdateBatchSelectionError("An update subset must contain at least one Skill");
+    }
+    const updateable = new Map(assessment.updateable.map((item) => [item.id, item]));
+    const byIndex = new Map(assessment.updateable.map((item) => [item.index, item]));
+    const selected = [];
+    const seen = new Set();
+    for (const requested of ids) {
+        const item = typeof requested === "number"
+            ? byIndex.get(requested)
+            : updateable.get(requested);
+        if (!item) {
+            const known = assessment.items.find((candidate) => candidate.id === requested || candidate.index === requested);
+            if (known?.status === "unknown") {
+                throw new UpdateBatchSelectionError(`Skill ${JSON.stringify(requested)} has unknown version status and is not updateable`);
+            }
+            if (known?.status === "current") {
+                throw new UpdateBatchSelectionError(`Skill ${JSON.stringify(requested)} has no available update`);
+            }
+            throw new UpdateBatchSelectionError(`Unknown update batch selection ${JSON.stringify(requested)}`);
+        }
+        if (seen.has(item.id)) {
+            throw new UpdateBatchSelectionError(`Update batch selection contains duplicate Skill ${JSON.stringify(requested)}`);
+        }
+        seen.add(item.id);
+        selected.push(item);
+    }
+    return Object.freeze(selected);
+}
+/** Alias that makes the assessment operation discoverable to embedders. */
+export const assessAvailableUpdates = assessUpdateBatch;
+async function assessSelection(selection, index, resolveSource, sourceAccess) {
+    const id = updateBatchItemId(selection);
+    const base = { id, index, selection };
+    if (!selection.installation) {
+        return Object.freeze({
+            ...base,
+            status: "unknown",
+            reason: "The Skill has no installed baseline or resolved version evidence",
+        });
+    }
+    let source;
+    try {
+        source = await resolveSource(selection.source);
+    }
+    catch (error) {
+        return Object.freeze({
+            ...base,
+            status: "unknown",
+            reason: `The current Source could not be resolved: ${errorMessage(error)}`,
+        });
+    }
+    let snapshot;
+    try {
+        snapshot = await readCurrentSnapshot(sourceAccess, source, selection.path);
+        assertValidSnapshot(snapshot);
+        const currentBaseline = skillTreeBaseline(snapshot.files);
+        const currentVersion = trustworthyVersion(source, snapshot.resolvedVersion);
+        const installedVersion = trustworthyVersionForSelection(source, selection.installation.resolvedVersion);
+        const evidence = assessEvidence(selection, installedVersion, currentVersion, currentBaseline);
+        const item = Object.freeze({
+            ...base,
+            source,
+            status: evidence.status,
+            reason: evidence.reason,
+            currentSnapshot: freezeSnapshot(snapshot),
+            currentBaseline,
+            ...(currentVersion === undefined ? {} : { currentVersion }),
+        });
+        // Keep a second private copy because Uint8Array contents remain mutable
+        // even when their containing object is frozen.
+        immutableAssessmentSnapshots.set(item, freezeSnapshot(snapshot));
+        return item;
+    }
+    catch (error) {
+        return Object.freeze({
+            ...base,
+            source,
+            status: "unknown",
+            reason: `The current Source snapshot could not be assessed: ${errorMessage(error)}`,
+        });
+    }
+}
+function isModeSelection(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function readCurrentSnapshot(sourceAccess, source, skillPath) {
+    if (sourceAccess.readSkillTreeSnapshot) {
+        return sourceAccess.readSkillTreeSnapshot(source, skillPath);
+    }
+    if (sourceAccess.readSkillTree) {
+        return { files: await sourceAccess.readSkillTree(source, skillPath) };
+    }
+    throw new Error("the configured Source access does not provide a Skill tree snapshot reader");
+}
+function assessEvidence(selection, installedVersion, currentVersion, currentBaseline) {
+    if (currentVersion === undefined) {
+        return {
+            status: "unknown",
+            reason: "The current Source snapshot has no trustworthy resolved version evidence",
+        };
+    }
+    if (installedVersion === undefined) {
+        return {
+            status: "unknown",
+            reason: "The installed Skill has no trustworthy resolved version evidence",
+        };
+    }
+    const pinMismatch = builtinPinMismatch(selection, currentVersion.kind === "builtin-package" ? currentVersion.version : undefined);
+    if (pinMismatch !== undefined) {
+        return { status: "unknown", reason: `${pinMismatch.charAt(0).toUpperCase()}${pinMismatch.slice(1)}` };
+    }
+    if (selection.version.policy === "fixed") {
+        const currentTarget = versionValue(currentVersion);
+        if (currentTarget !== selection.version.version) {
+            return {
+                status: "unknown",
+                reason: `The current Source resolved to ${JSON.stringify(currentTarget)}, not the fixed target ${JSON.stringify(selection.version.version)}`,
+            };
+        }
+        if (versionValue(installedVersion) !== selection.version.version) {
+            return {
+                status: "updateable",
+                reason: "The installed Skill is behind its fixed version target",
+            };
+        }
+    }
+    else if (installedVersion.kind === "builtin-package" && currentVersion.kind === "builtin-package" &&
+        compareSemver(installedVersion.version, currentVersion.version) > 0) {
+        return {
+            status: "unknown",
+            reason: `Installed by a newer Agent Depot (${installedVersion.version}); running ${currentVersion.version} — update Agent Depot`,
+        };
+    }
+    else if (!sameVersion(installedVersion, currentVersion)) {
+        return {
+            status: "updateable",
+            reason: "A newer resolved version is available for the latest policy",
+        };
+    }
+    const installedBaseline = selection.installation?.baseline;
+    if (!installedBaseline) {
+        return {
+            status: "unknown",
+            reason: "The installed Skill has no trustworthy content baseline",
+        };
+    }
+    if (installedBaseline.digest !== currentBaseline.digest) {
+        return {
+            status: "updateable",
+            reason: "The current Source snapshot differs from the installed content baseline",
+        };
+    }
+    return {
+        status: "current",
+        reason: selection.version.policy === "fixed"
+            ? "The installed Skill matches its fixed version and content baseline"
+            : "The installed Skill matches the current latest version and content baseline",
+    };
+}
+function parseRuntimeSelection(value) {
+    try {
+        if (!isPlainRecord(value)) {
+            throw new Error("the selection must be an object");
+        }
+        const candidate = value;
+        const source = candidate.source;
+        if (!isPlainRecord(source)) {
+            throw new Error("the selection Source must be an object");
+        }
+        const projectSource = runtimeProjectSource(source);
+        const version = candidate.version;
+        const validationSource = source.kind === "external" && typeof source.url === "string" &&
+            isPlainRecord(version) && version.policy === "fixed" && source.ref === undefined
+            ? { ...projectSource, ref: version.version }
+            : projectSource;
+        const parsed = parseProjectManifest({
+            version: 1,
+            skills: [{ ...candidate, source: validationSource }],
+        }).skills[0];
+        if (!parsed) {
+            return { reason: "the selection is missing" };
+        }
+        return { selection: parsed, reason: "" };
+    }
+    catch (error) {
+        return { reason: errorMessage(error) };
+    }
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function runtimeProjectSource(source) {
+    if (source.kind === "builtin") {
+        return { kind: "builtin", id: source.id };
+    }
+    if (source.kind !== "external") {
+        return source;
+    }
+    return {
+        kind: "external",
+        ...(typeof source.url === "string" ? { url: source.url } : {}),
+        ...(typeof source.path === "string" ? { path: source.path } : {}),
+        ...(source.ref === undefined ? {} : { ref: source.ref }),
+    };
+}
+function malformedSelectionAssessment(value, index, reason) {
+    return Object.freeze({
+        id: runtimeSelectionId(value, index),
+        index,
+        selection: value,
+        status: "unknown",
+        reason: `The Skill selection is malformed: ${reason}`,
+    });
+}
+function runtimeSelectionId(value, index) {
+    if (value !== null && typeof value === "object") {
+        try {
+            const candidate = value;
+            return JSON.stringify([candidate.source, candidate.path]);
+        }
+        catch {
+            // Fall through to an index-based identity for cyclic or otherwise unserializable input.
+        }
+    }
+    return `malformed:${index}`;
+}
+function assertValidSnapshot(value) {
+    if (value === null || typeof value !== "object" || !Array.isArray(value.files)) {
+        throw new Error("the Source snapshot must contain a files array");
+    }
+    for (const file of value.files) {
+        if (file === null || typeof file !== "object") {
+            throw new Error("the Source snapshot contains a malformed Skill tree file");
+        }
+        const candidate = file;
+        if (typeof candidate.path !== "string" || !(candidate.content instanceof Uint8Array) || typeof candidate.executable !== "boolean") {
+            throw new Error("the Source snapshot contains a malformed Skill tree file");
+        }
+    }
+}
+function trustworthyVersion(source, version) {
+    if (!version)
+        return undefined;
+    if (source.kind === "builtin" && version.kind === "builtin-package" && version.version.length > 0)
+        return version;
+    if (source.kind === "git" && version.kind === "git-commit" && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(version.commit))
+        return version;
+    return undefined;
+}
+function trustworthyVersionForSelection(source, version) {
+    return trustworthyVersion(source, version);
+}
+function versionValue(version) {
+    return version.kind === "builtin-package" ? version.version : version.commit;
+}
+/** Compares two semver strings (prerelease aware); an unparsable input compares as 0 so it never blocks an update. */
+function compareSemver(left, right) {
+    const a = parseSemver(left);
+    const b = parseSemver(right);
+    if (a === undefined || b === undefined)
+        return 0;
+    for (let index = 0; index < 3; index += 1) {
+        const difference = a.core[index] - b.core[index];
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    if (a.pre.length === 0 || b.pre.length === 0)
+        return Math.sign(b.pre.length - a.pre.length);
+    for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+        const x = a.pre[index];
+        const y = b.pre[index];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/u.test(x);
+        const yNumeric = /^\d+$/u.test(y);
+        if (xNumeric && yNumeric)
+            return Math.sign(Number(x) - Number(y));
+        if (xNumeric !== yNumeric)
+            return xNumeric ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+function parseSemver(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value);
+    if (!match)
+        return undefined;
+    return { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] === undefined ? [] : match[4].split(".") };
+}
+function sameVersion(left, right) {
+    return left.kind === right.kind && versionValue(left) === versionValue(right);
+}
+export function updateBatchItemId(selection) {
+    return JSON.stringify([selection.source, selection.path]);
+}
+export function immutableUpdateSnapshot(item) {
+    const snapshot = immutableAssessmentSnapshots.get(item);
+    return snapshot === undefined ? undefined : freezeSnapshot(snapshot);
+}
+export function freezeSnapshot(snapshot) {
+    return Object.freeze({
+        files: Object.freeze(snapshot.files.map((file) => Object.freeze({
+            path: file.path,
+            content: Uint8Array.from(file.content),
+            executable: file.executable,
+        }))),
+        ...(snapshot.resolvedVersion === undefined ? {} : { resolvedVersion: Object.freeze({ ...snapshot.resolvedVersion }) }),
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/update-flow.js

@@ -0,0 +1,135 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { defaultProjectManifestPath, ProjectManifestStore, } from "./project-manifest.js";
+import { defaultProjectSkillTreeAccess } from "./skill-install.js";
+import { applyUpdateBatch, previewSkillUpdate, relativeProjectPath, } from "./skill-update.js";
+import { resolveProjectSource } from "./sources.js";
+import { assessUpdateBatch, } from "./update-batch.js";
+/** Where the scope's installations live: its root and, for the project scope, its manifest store. */
+function scopeLocation(input) {
+    if (input.scope === "user-global")
+        return { projectRoot: path.resolve(input.homeDirectory ?? homedir()) };
+    const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+    return {
+        projectRoot,
+        manifestStore: input.projectManifestStore ?? new ProjectManifestStore(defaultProjectManifestPath(projectRoot)),
+    };
+}
+/** The scope's installations, read without assessing them. */
+export async function readScopeInstallations(input) {
+    const { manifestStore } = scopeLocation(input);
+    return manifestStore ? (await manifestStore.load()).skills : requireUserGlobalInstallations(input.operations);
+}
+/** Loads the scope's installations and assesses them like `update check`. Changes nothing. */
+export async function loadUpdates(input) {
+    const { scope, operations } = input;
+    const sourceAccess = input.sourceAccess ?? defaultProjectSkillTreeAccess();
+    const { projectRoot, manifestStore } = scopeLocation(input);
+    const installed = await readScopeInstallations(input);
+    const resolveSource = operations.resolveProjectSource
+        ? (source) => operations.resolveProjectSource(source)
+        : resolveProjectSource;
+    const assessment = await assessUpdateBatch(installed, { sourceAccess, resolveSource });
+    const context = {
+        projectRoot,
+        scope,
+        sourceAccess,
+        sourceOperations: operations,
+        trackedInstallationPaths: installed.flatMap((selection) => selection.installation === undefined ? [] : [selection.installation.path]),
+        ...(manifestStore === undefined ? {} : { projectManifestStore: manifestStore }),
+        ...(input.installationFileSystem === undefined ? {} : { installationFileSystem: input.installationFileSystem }),
+    };
+    return { assessment, installed, context };
+}
+async function requireUserGlobalInstallations(operations) {
+    if (!operations.listUserGlobalInstallations) {
+        throw new Error("Configured Source operations cannot inspect user-global Skill updates");
+    }
+    return operations.listUserGlobalInstallations();
+}
+/** Previews every selected candidate independently; a failing preview never hides the others. */
+export async function previewUpdateCandidates(selected, context) {
+    const plans = [];
+    const failures = [];
+    const nonCanonicalPaths = [];
+    for (const item of selected) {
+        try {
+            const plan = await previewSkillUpdate(item, context);
+            if (plan.nonCanonicalPath !== undefined)
+                nonCanonicalPaths.push(relativeProjectPath(context.projectRoot, plan.nonCanonicalPath));
+            plans.push(plan);
+        }
+        catch (error) {
+            failures.push({ item, message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { plans, failures, nonCanonicalPaths };
+}
+/** The preview `update apply` prints for one candidate. */
+export function describeUpdatePreview(plan, scope, projectRoot, wording = "flags") {
+    const lines = [
+        `Preview: update Skill ${JSON.stringify(plan.selection.path)} from ${plan.source.id} (scope: ${scope})`,
+        `  target: ${plan.target}`,
+    ];
+    if (plan.nonCanonicalPath !== undefined) {
+        const relative = relativeProjectPath(projectRoot, plan.nonCanonicalPath);
+        lines.push(wording === "flags"
+            ? `  WARNING: non-canonical location ${JSON.stringify(relative)} (outside .agents/skills and .claude/skills); --yes together with --confirm-path ${relative} explicitly confirms replacing this exact path`
+            : `  WARNING: non-canonical location ${JSON.stringify(relative)} (outside .agents/skills and .claude/skills); a separate confirmation of this exact path is required to replace it`);
+    }
+    lines.push(`  proposed changes: replace ${plan.snapshot.files.length} managed files and persist the new version/content baseline`);
+    if (plan.overwriteRequired) {
+        lines.push(wording === "flags"
+            ? "  WARNING: the installed Skill has local modifications; --yes explicitly confirms replacing them"
+            : "  WARNING: the installed Skill has local modifications; confirming replaces them");
+    }
+    if (plan.methodPreview) {
+        lines.push(`  external command: argv=${JSON.stringify(plan.methodPreview.argv)}`, `  external cwd: ${JSON.stringify(plan.methodPreview.cwd)}`, `  external target: ${JSON.stringify(plan.methodPreview.target)}`, "  declared changes:", ...plan.methodPreview.declaredChanges.map((change) => `    ${change}`), `  WARNING: ${plan.methodPreview.warning}`);
+    }
+    return lines;
+}
+/**
+ * `--yes` alone never confirms a repository-controlled non-canonical location:
+ * every pending path needs its own exact confirmation, and a value that matches
+ * no pending path is an error rather than silently ignored. Returns the problem, if any.
+ */
+export function findPathConfirmationProblem(pending, confirmedPaths) {
+    const unmatched = confirmedPaths.filter((value) => !pending.includes(value));
+    if (unmatched.length > 0) {
+        const shown = pending.length === 0 ? "none" : pending.map((value) => JSON.stringify(value)).join(", ");
+        return `--confirm-path ${unmatched.map((value) => JSON.stringify(value)).join(", ")} does not match any pending non-canonical location (pending: ${shown}); no path was changed`;
+    }
+    const missing = pending.filter((value) => !confirmedPaths.includes(value));
+    if (missing.length > 0) {
+        const flags = missing.map((value) => `--confirm-path ${value}`).join(" ");
+        return `Non-canonical location ${missing.map((value) => JSON.stringify(value)).join(", ")} needs explicit path confirmation; --yes alone is not enough. Rerun with ${flags}; no path was changed`;
+    }
+    return undefined;
+}
+/**
+ * Applies the selected updates after the caller collected the confirmation.
+ * Overwriting modified installations and running external methods are confirmed
+ * by that same confirmation; a non-canonical path only when its exact relative
+ * path is listed.
+ */
+export function applyConfirmedUpdates(selected, context, confirmedPaths, 
+/** Ids of the items whose preview showed the overwrite of local modifications; when given, any other item that turns out modified fails instead of being overwritten. */
+previewedOverwrites) {
+    return applyUpdateBatch(selected, {
+        ...context,
+        // The callback is invoked independently for every candidate. In particular,
+        // a modified installation is never overwritten unless the caller confirmed.
+        confirm: async (plan) => {
+            if (previewedOverwrites !== undefined && plan.overwriteRequired && !previewedOverwrites.has(plan.item.id)) {
+                throw new Error(`Skill ${JSON.stringify(plan.item.id)} was modified after the preview, so the overwrite was never shown or confirmed; nothing was changed`);
+            }
+            return {
+                overwriteModifiedInstallation: true,
+                externalMethod: true,
+                ...(plan.nonCanonicalPath !== undefined && confirmedPaths.includes(relativeProjectPath(context.projectRoot, plan.nonCanonicalPath))
+                    ? { nonCanonicalPath: plan.nonCanonicalPath }
+                    : {}),
+            };
+        },
+    });
+}

package/dist/src/usage-error.js

@@ -0,0 +1,7 @@
+/** Raised for invalid CLI usage; the message is printed verbatim. */
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}