@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/skill-update.js

@@ -0,0 +1,244 @@
+import path from "node:path";
+import { inspectProjectSkillUpdate, updateProjectSkillTransaction, validateProjectSkillInstallationPreview, } from "./project-installation.js";
+import { parseProjectManifest, ProjectManifestStore, } from "./project-manifest.js";
+import { executeSourceInstallationMethod, parseSourceInstallationMethod, resolveSourceInstallationMethodCwd, } from "./sources.js";
+import { previewUserMethod, } from "./user-method.js";
+import { freezeSnapshot, immutableUpdateSnapshot, } from "./update-batch.js";
+const immutableSnapshots = new WeakMap();
+/** Builds a safe update preview without changing files, state, or running methods. */
+export async function previewSkillUpdate(item, options) {
+    if (item.status !== "updateable") {
+        throw new Error(`Skill ${JSON.stringify(item.id)} is not updateable`);
+    }
+    if (!item.source || !item.currentSnapshot) {
+        throw new Error(`Skill ${JSON.stringify(item.id)} has no immutable Source snapshot`);
+    }
+    if (!item.selection.installation) {
+        throw new Error(`Skill ${JSON.stringify(item.id)} has no tracked installation`);
+    }
+    const selection = immutableSelection(item.selection);
+    const snapshot = immutableUpdateSnapshot(item) ?? freezeSnapshot(item.currentSnapshot);
+    await validateProjectSkillInstallationPreview({
+        selection,
+        source: item.source,
+        previewTree: snapshot.files,
+        portableV1: true,
+    }, options.sourceAccess);
+    const installationOptions = projectInstallationOptions(options);
+    const inspection = await inspectProjectSkillUpdate(selection, installationOptions);
+    const target = path.resolve(options.projectRoot, ...selection.installation.path.split("/"));
+    const method = await resolveUpdateMethod(selection, item.source, snapshot, options);
+    const methodPreview = method === undefined
+        ? undefined
+        : previewUserMethod({
+            method,
+            projectRoot: options.projectRoot,
+            target,
+            declaredChanges: [
+                `replace ${snapshot.files.length} managed files at ${target}`,
+                `persist resolved version and content baseline for ${options.scope} scope`,
+            ],
+        });
+    const plan = Object.freeze({
+        item,
+        selection,
+        source: item.source,
+        snapshot,
+        target,
+        overwriteRequired: inspection.requiresOverwriteConfirmation,
+        ...(inspection.nonCanonicalPath === undefined ? {} : { nonCanonicalPath: inspection.nonCanonicalPath }),
+        ...(method === undefined ? {} : { method }),
+        ...(methodPreview === undefined ? {} : { methodPreview }),
+    });
+    // Typed arrays cannot be frozen safely in JavaScript. Keep a private copy so
+    // callback code cannot mutate the bytes that will actually be installed.
+    immutableSnapshots.set(plan, freezeSnapshot(snapshot));
+    return plan;
+}
+/** Applies one update and persists its new evidence through the selected scope seam. */
+export async function applySkillUpdate(item, options) {
+    const plan = await previewSkillUpdate(item, options);
+    const confirmation = options.confirm ? await options.confirm(plan) : options.confirmation ?? {};
+    assertUpdateConfirmed(item, plan, confirmation);
+    if (plan.method !== undefined) {
+        // Validate the real path before staging or replacing the managed tree. The
+        // injected executor is subject to the same boundary even when it is not
+        // the default process runner.
+        await resolveSourceInstallationMethodCwd(plan.method, options.projectRoot);
+    }
+    const persistedState = await preparePersistedSelection(item.selection, options);
+    const transaction = await updateProjectSkillTransaction({
+        selection: plan.selection,
+        source: plan.source,
+        previewTree: (immutableSnapshots.get(plan) ?? freezeSnapshot(plan.snapshot)).files,
+        resolvedVersion: plan.snapshot.resolvedVersion ?? plan.selection.installation?.resolvedVersion,
+        confirmOverwrite: confirmation.overwriteModifiedInstallation === true,
+    }, projectInstallationOptions(options, confirmation.nonCanonicalPath));
+    try {
+        if (plan.method !== undefined) {
+            const context = { source: plan.source, skillPath: plan.selection.path, projectRoot: options.projectRoot };
+            if (options.executeMethod)
+                await options.executeMethod(plan.method, context);
+            else if (options.sourceOperations?.executeInstallationMethod) {
+                await options.sourceOperations.executeInstallationMethod(plan.method, context);
+            }
+            else
+                await executeSourceInstallationMethod(plan.method, context);
+        }
+        const updatedSelection = selectionWithInstallation(plan.selection, transaction.result, options.projectRoot);
+        await persistedState.apply(updatedSelection);
+        await transaction.commit();
+        return Object.freeze({ item, plan, installation: transaction.result });
+    }
+    catch (error) {
+        return rollBackUpdate(error, transaction, persistedState);
+    }
+}
+function assertUpdateConfirmed(item, plan, confirmation) {
+    if (plan.overwriteRequired && confirmation.overwriteModifiedInstallation !== true) {
+        throw new Error(`Skill ${JSON.stringify(item.id)} requires explicit overwrite confirmation; no path was changed`);
+    }
+    if (plan.nonCanonicalPath !== undefined && confirmation.nonCanonicalPath !== plan.nonCanonicalPath) {
+        throw new Error(`Skill ${JSON.stringify(item.id)} is installed at the non-canonical location ${JSON.stringify(plan.nonCanonicalPath)}; explicit confirmation of that exact path is required and no path was changed`);
+    }
+    if (plan.method !== undefined && confirmation.externalMethod !== true) {
+        throw new Error(`Skill ${JSON.stringify(item.id)} has an external method; explicit method confirmation is required and no command was run`);
+    }
+}
+async function rollBackUpdate(error, transaction, persistedState) {
+    const rollbackErrors = [];
+    for (const [label, rollback] of [
+        ["filesystem", () => transaction.rollback()],
+        ["persisted-state", () => persistedState.rollback()],
+    ]) {
+        try {
+            await rollback();
+        }
+        catch (rollbackError) {
+            rollbackErrors.push(`${label} rollback failed: ${errorMessage(rollbackError)}`);
+        }
+    }
+    if (rollbackErrors.length > 0) {
+        throw new Error(`${errorMessage(error)}; ${rollbackErrors.join("; ")}`);
+    }
+    throw error;
+}
+/** Applies selected entries independently and returns a complete per-skill summary. */
+export async function applyUpdateBatch(selected, options) {
+    const items = "updateable" in selected ? selected.updateable : selected;
+    const results = [];
+    for (const item of items) {
+        try {
+            const result = await applySkillUpdate(item, options);
+            results.push(Object.freeze({ id: item.id, selection: item.selection, status: "updated", result }));
+        }
+        catch (error) {
+            results.push(Object.freeze({
+                id: item.id,
+                selection: item.selection,
+                status: "failed",
+                error: errorMessage(error),
+            }));
+        }
+    }
+    const frozenResults = Object.freeze(results);
+    return Object.freeze({
+        results: frozenResults,
+        updated: Object.freeze(results.filter((result) => result.status === "updated")),
+        failed: Object.freeze(results.filter((result) => result.status === "failed")),
+    });
+}
+/** Alias for embedders that prefer an imperative per-Skill operation name. */
+export const updateSkill = applySkillUpdate;
+function projectInstallationOptions(options, confirmedNonCanonicalPath) {
+    return {
+        projectRoot: options.projectRoot,
+        sourceAccess: options.sourceAccess,
+        installationTrust: options.scope === "user-global" ? "user-global-state" : "project-manifest",
+        ...(options.trackedInstallationPaths === undefined ? {} : { otherInstallationPaths: options.trackedInstallationPaths }),
+        ...(confirmedNonCanonicalPath === undefined ? {} : { confirmedNonCanonicalPath }),
+        ...(options.installationFileSystem === undefined ? {} : { fileSystem: options.installationFileSystem }),
+    };
+}
+async function resolveUpdateMethod(selection, source, snapshot, options) {
+    const configured = selection.methods?.update;
+    if (configured !== undefined)
+        return parseSourceInstallationMethod(configured);
+    const operations = options.sourceOperations;
+    if (!operations?.readInstallationMethod || !source)
+        return undefined;
+    const metadata = await operations.readInstallationMethod(source, selection.path, snapshot.files);
+    return metadata === undefined ? undefined : parseSourceInstallationMethod(metadata);
+}
+async function preparePersistedSelection(originalSelection, options) {
+    const identity = JSON.stringify([originalSelection.source, originalSelection.path]);
+    if (options.scope === "project") {
+        const store = options.projectManifestStore ?? new ProjectManifestStore(path.join(options.projectRoot, "agent-depot.json"));
+        const manifest = await store.load();
+        if (!manifest.skills.some((selection) => JSON.stringify([selection.source, selection.path]) === identity)) {
+            throw new Error(`Project manifest does not contain Skill ${JSON.stringify(originalSelection.path)}`);
+        }
+        let applied = false;
+        return {
+            apply: async (updatedSelection) => {
+                applied = true;
+                const next = parseProjectManifest({
+                    version: 1,
+                    skills: manifest.skills.map((selection) => JSON.stringify([selection.source, selection.path]) === identity ? updatedSelection : selection),
+                });
+                await store.save(next);
+            },
+            rollback: async () => {
+                if (applied)
+                    await store.save(manifest);
+            },
+        };
+    }
+    const operations = options.sourceOperations;
+    if (!operations?.updateUserGlobalInstallation) {
+        throw new Error("Configured Source operations cannot persist user-global Skill updates");
+    }
+    const installations = await options.sourceOperations?.listUserGlobalInstallations?.();
+    const previous = installations?.find((selection) => JSON.stringify([selection.source, selection.path]) === identity) ?? originalSelection;
+    let applied = false;
+    return {
+        apply: async (updatedSelection) => {
+            applied = true;
+            await operations.updateUserGlobalInstallation(updatedSelection);
+        },
+        rollback: async () => {
+            if (applied)
+                await operations.updateUserGlobalInstallation(previous);
+        },
+    };
+}
+export function selectionWithInstallation(selection, result, projectRoot) {
+    return parseProjectManifest({
+        version: 1,
+        skills: [{
+                ...selection,
+                installation: {
+                    path: relativeProjectPath(projectRoot, result.canonicalPath),
+                    adopted: result.adopted,
+                    ...(result.resolvedVersion === undefined ? {} : { resolvedVersion: result.resolvedVersion }),
+                    baseline: result.baseline,
+                },
+            }],
+    }).skills[0];
+}
+export function relativeProjectPath(projectRoot, candidate) {
+    const relative = path.relative(path.resolve(projectRoot), path.resolve(candidate));
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`Installed Skill location escapes the scope root: ${candidate}`);
+    }
+    return relative.split(path.sep).join("/");
+}
+function immutableSelection(selection) {
+    const parsed = parseProjectManifest({ version: 1, skills: [selection] }).skills[0];
+    if (!parsed)
+        throw new Error("Skill update selection is missing");
+    return parsed;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/source-state.js

@@ -0,0 +1,240 @@
+import { mkdir, readFile, rmdir, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import path from "node:path";
+import { writeFileAtomically } from "./atomic-file.js";
+import { canonicalizeGitSourceUrl, sourceIdForUrl } from "./git-source.js";
+import { parseProjectManifest } from "./project-manifest.js";
+const EMPTY_STATE = Object.freeze({
+    version: 1,
+    gitSources: Object.freeze([]),
+    userGlobalInstallations: Object.freeze([]),
+});
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export class SourceStateError extends Error {
+    constructor(statePath, reason) {
+        super(`Source state at ${JSON.stringify(statePath)} is invalid: ${reason}. The file was not modified; inspect or repair it before retrying.`);
+        this.name = "SourceStateError";
+    }
+}
+export class SourceStateLockError extends Error {
+    constructor(statePath) {
+        super(`Source state at ${JSON.stringify(statePath)} is busy; no changes were made. Retry after the other process finishes.`);
+        this.name = "SourceStateLockError";
+    }
+}
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_RETRY_MS = 10;
+function parseGitSources(items, statePath) {
+    const gitSources = [];
+    const ids = new Set();
+    for (const [index, item] of items.entries()) {
+        const source = parseGitSource(item, index, statePath);
+        if (ids.has(source.id)) {
+            throw new SourceStateError(statePath, `gitSources[${index}] duplicates another Source`);
+        }
+        ids.add(source.id);
+        gitSources.push(source);
+    }
+    return gitSources;
+}
+function parseGitSource(item, index, statePath) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new SourceStateError(statePath, `gitSources[${index}] must be an object`);
+    }
+    const source = item;
+    const sourceKeys = Object.keys(source);
+    if (sourceKeys.some((key) => key !== "id" && key !== "kind" && key !== "url")) {
+        throw new SourceStateError(statePath, `gitSources[${index}] contains unsupported fields`);
+    }
+    if (source.kind !== "git" || !isNonEmptyString(source.id) || !isNonEmptyString(source.url)) {
+        throw new SourceStateError(statePath, `gitSources[${index}] is not a valid Git Source`);
+    }
+    let url;
+    try {
+        url = canonicalizeGitSourceUrl(source.url);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "the URL is invalid";
+        throw new SourceStateError(statePath, `gitSources[${index}] has an invalid URL (${reason})`);
+    }
+    const id = sourceIdForUrl(url);
+    if (source.id !== id) {
+        throw new SourceStateError(statePath, `gitSources[${index}] has an invalid identity`);
+    }
+    return Object.freeze({ id, kind: "git", url });
+}
+function parseUserGlobalInstallations(items, statePath) {
+    const userGlobalInstallations = [];
+    const installationIdentities = new Set();
+    for (const [index, item] of items.entries()) {
+        try {
+            const parsed = parseUserGlobalInstallation(item, statePath);
+            const identity = JSON.stringify([parsed.source, parsed.path]);
+            if (installationIdentities.has(identity)) {
+                throw new Error("the installation duplicates another user-global Skill");
+            }
+            installationIdentities.add(identity);
+            userGlobalInstallations.push(parsed);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : "the installation record is invalid";
+            throw new SourceStateError(statePath, `userGlobalInstallations[${index}] is invalid (${reason})`);
+        }
+    }
+    return userGlobalInstallations;
+}
+function parseUserGlobalInstallation(item, statePath) {
+    const parsed = parseProjectManifest({ version: 1, skills: [item] }, statePath).skills[0];
+    if (!parsed) {
+        throw new Error("the installation record is missing");
+    }
+    if (parsed.installation === undefined) {
+        throw new Error("the installation record must include an installation location");
+    }
+    return parsed;
+}
+function parseState(value, statePath) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new SourceStateError(statePath, "the root value must be an object");
+    }
+    const candidate = value;
+    const keys = Object.keys(candidate);
+    if (keys.some((key) => key !== "version" && key !== "gitSources" && key !== "userGlobalInstallations")) {
+        throw new SourceStateError(statePath, "the state contains unsupported fields");
+    }
+    if (candidate.version !== 1) {
+        throw new SourceStateError(statePath, "the state version is unsupported");
+    }
+    if (!Array.isArray(candidate.gitSources)) {
+        throw new SourceStateError(statePath, "gitSources must be an array");
+    }
+    if (candidate.userGlobalInstallations !== undefined && !Array.isArray(candidate.userGlobalInstallations)) {
+        throw new SourceStateError(statePath, "userGlobalInstallations must be an array");
+    }
+    const gitSources = parseGitSources(candidate.gitSources, statePath);
+    const userGlobalInstallations = parseUserGlobalInstallations(candidate.userGlobalInstallations ?? [], statePath);
+    return Object.freeze({
+        version: 1,
+        gitSources: Object.freeze(gitSources),
+        userGlobalInstallations: Object.freeze(userGlobalInstallations),
+    });
+}
+export function defaultSourceStatePath(environment = process.env, platform = process.platform, homeDirectory = homedir()) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    if (platform === "win32") {
+        const appData = environment.APPDATA || environment.LOCALAPPDATA;
+        return pathApi.join(appData || pathApi.join(homeDirectory, "AppData", "Roaming"), "Agent Depot", "sources.json");
+    }
+    const stateHome = environment.XDG_STATE_HOME;
+    return pathApi.join(stateHome && pathApi.isAbsolute(stateHome) ? stateHome : pathApi.join(homeDirectory, ".local", "state"), "agent-depot", "sources.json");
+}
+export class SourceStateStore {
+    path;
+    constructor(statePath = defaultSourceStatePath()) {
+        this.path = statePath;
+    }
+    async load() {
+        const release = await this.acquireLock();
+        try {
+            return await this.loadUnlocked();
+        }
+        finally {
+            await release();
+        }
+    }
+    async update(mutate) {
+        const release = await this.acquireLock();
+        try {
+            const state = await this.loadUnlocked();
+            const update = await mutate(state);
+            await this.saveUnlocked(update.state);
+            return update.result;
+        }
+        finally {
+            await release();
+        }
+    }
+    async save(state) {
+        const release = await this.acquireLock();
+        try {
+            await this.saveUnlocked(state);
+        }
+        finally {
+            await release();
+        }
+    }
+    /** Removes the persisted catalog/configuration file without touching caches. */
+    async remove() {
+        const release = await this.acquireLock();
+        try {
+            await unlink(this.path).catch((error) => {
+                if (!isMissingFile(error))
+                    throw error;
+            });
+        }
+        finally {
+            await release();
+        }
+    }
+    async loadUnlocked() {
+        let contents;
+        try {
+            contents = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (isMissingFile(error)) {
+                return EMPTY_STATE;
+            }
+            throw error;
+        }
+        let value;
+        try {
+            value = JSON.parse(contents);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : "the JSON could not be parsed";
+            throw new SourceStateError(this.path, `malformed JSON (${reason})`);
+        }
+        return parseState(value, this.path);
+    }
+    async saveUnlocked(state) {
+        const normalized = parseState(state, this.path);
+        await mkdir(path.dirname(this.path), { recursive: true });
+        const contents = `${JSON.stringify(normalized, null, 2)}\n`;
+        await writeFileAtomically(this.path, contents, { allowLockedReplaceFallback: true });
+    }
+    async acquireLock() {
+        const lockPath = `${this.path}.lock`;
+        await mkdir(path.dirname(this.path), { recursive: true });
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
+        while (true) {
+            try {
+                await mkdir(lockPath);
+                return async () => {
+                    await rmdir(lockPath);
+                };
+            }
+            catch (error) {
+                if (!isAlreadyExists(error)) {
+                    throw error;
+                }
+                if (Date.now() >= deadline) {
+                    throw new SourceStateLockError(this.path);
+                }
+                await delay(LOCK_RETRY_MS);
+            }
+        }
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function isMissingFile(error) {
+    return errorCode(error) === "ENOENT";
+}
+function isAlreadyExists(error) {
+    return errorCode(error) === "EEXIST";
+}