@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/sources.js

@@ -0,0 +1,391 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { runProcess } from "./process-runner.js";
+import { canonicalizeGitSourceUrl, GitSourceAccessAdapter, sourceIdForUrl, } from "./git-source.js";
+import { defaultSourceStatePath, SourceStateStore } from "./source-state.js";
+import { createSourceContentAccess, discoverSkillsFromSources, } from "./skill-discovery.js";
+import { AGENT_DEPOT_PACKAGE_VERSION, parsePortableInstallationMethod, } from "./project-manifest.js";
+export const BUILT_IN_SOURCE = Object.freeze({
+    id: "builtin:agent-depot",
+    kind: "builtin",
+    name: "Agent Depot",
+    packageOwned: true,
+});
+export class SourceNotFoundError extends Error {
+    constructor(sourceId) {
+        super(`Source is not registered: ${sourceId}`);
+        this.name = "SourceNotFoundError";
+    }
+}
+export class BuiltInSourceError extends Error {
+    constructor() {
+        super("The package-owned built-in Source cannot be refreshed or changed");
+        this.name = "BuiltInSourceError";
+    }
+}
+export class SourceSelectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SourceSelectionError";
+    }
+}
+export class SourceMetadataError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SourceMetadataError";
+    }
+}
+const SOURCE_METADATA_FILENAMES = Object.freeze([
+    ".agent-depot.json",
+    "agent-depot-method.json",
+    "installation-method.json",
+]);
+const SOURCE_METADATA_MAX_BYTES = 64 * 1024;
+export function createSourceOperations(options = {}) {
+    const stateStore = options.stateStore ?? new SourceStateStore(options.statePath ?? defaultSourceStatePath(process.env, process.platform, options.homeDirectory));
+    const gitAccess = options.gitAccess ?? new GitSourceAccessAdapter();
+    const sourceContentAccess = options.sourceContentAccess ?? createSourceContentAccess({
+        builtInRoot: options.builtInRoot,
+        gitCachePath: options.gitCachePath ?? (gitAccess instanceof GitSourceAccessAdapter ? gitAccess.cachePath : undefined),
+    });
+    return {
+        async addGitSource(url) {
+            const canonicalUrl = canonicalizeGitSourceUrl(url);
+            const id = sourceIdForUrl(canonicalUrl);
+            return stateStore.update((state) => {
+                const existing = state.gitSources.find((source) => source.id === id);
+                if (existing) {
+                    return { state, result: existing };
+                }
+                const source = Object.freeze({ id, kind: "git", url: canonicalUrl });
+                return {
+                    state: {
+                        version: 1,
+                        gitSources: [...state.gitSources, source],
+                        userGlobalInstallations: state.userGlobalInstallations,
+                    },
+                    result: source,
+                };
+            });
+        },
+        async listSources() {
+            const state = await stateStore.load();
+            return Object.freeze([BUILT_IN_SOURCE, ...state.gitSources]);
+        },
+        async refreshSource(sourceId) {
+            if (sourceId === BUILT_IN_SOURCE.id) {
+                throw new BuiltInSourceError();
+            }
+            const state = await stateStore.load();
+            const source = state.gitSources.find((candidate) => candidate.id === sourceId);
+            if (!source) {
+                throw new SourceNotFoundError(sourceId);
+            }
+            await gitAccess.refresh(source);
+            return source;
+        },
+        async removeGitSource(sourceId, installations = []) {
+            if (sourceId === BUILT_IN_SOURCE.id) {
+                throw new BuiltInSourceError();
+            }
+            await stateStore.update((state) => {
+                const source = state.gitSources.find((candidate) => candidate.id === sourceId);
+                if (!source) {
+                    throw new SourceNotFoundError(sourceId);
+                }
+                const requested = new Set(installations.map(userGlobalInstallationIdentity));
+                for (const installation of installations) {
+                    if (sourceIdForUserGlobalInstallation(installation) !== sourceId ||
+                        !state.userGlobalInstallations.some((candidate) => userGlobalInstallationIdentity(candidate) === userGlobalInstallationIdentity(installation))) {
+                        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(installation.path)} is not a dependent installation of Source ${JSON.stringify(sourceId)}`);
+                    }
+                }
+                return {
+                    state: {
+                        version: 1,
+                        gitSources: state.gitSources.filter((candidate) => candidate.id !== sourceId),
+                        userGlobalInstallations: state.userGlobalInstallations.filter((candidate) => !requested.has(userGlobalInstallationIdentity(candidate))),
+                    },
+                    result: undefined,
+                };
+            });
+        },
+        async migrateUserGlobalInstallations(oldSourceId, newSourceId, migrations) {
+            if (oldSourceId === newSourceId) {
+                throw new SourceSelectionError("Source migration requires two different registered Git Sources");
+            }
+            await stateStore.update((state) => {
+                const oldSource = state.gitSources.find((source) => source.id === oldSourceId);
+                const newSource = state.gitSources.find((source) => source.id === newSourceId);
+                if (!oldSource)
+                    throw new SourceNotFoundError(oldSourceId);
+                if (!newSource)
+                    throw new SourceNotFoundError(newSourceId);
+                const sourceIds = (selection) => sourceIdForUserGlobalInstallation(selection);
+                const existingIdentities = new Set(state.userGlobalInstallations.map(userGlobalInstallationIdentity));
+                const selectedIdentities = new Set();
+                const replacementIdentities = new Set();
+                for (const migration of migrations) {
+                    const fromIdentity = userGlobalInstallationIdentity(migration.from);
+                    const toIdentity = userGlobalInstallationIdentity(migration.to);
+                    if (selectedIdentities.has(fromIdentity)) {
+                        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(migration.from.path)} was selected more than once`);
+                    }
+                    selectedIdentities.add(fromIdentity);
+                    if (sourceIds(migration.from) !== oldSourceId || !existingIdentities.has(fromIdentity)) {
+                        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(migration.from.path)} is not a dependent installation of Source ${JSON.stringify(oldSourceId)}`);
+                    }
+                    if (sourceIds(migration.to) !== newSourceId) {
+                        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(migration.to.path)} does not belong to replacement Source ${JSON.stringify(newSourceId)}`);
+                    }
+                    if (replacementIdentities.has(toIdentity)) {
+                        throw new SourceSelectionError(`Replacement identity ${JSON.stringify(migration.to.path)} was selected more than once`);
+                    }
+                    replacementIdentities.add(toIdentity);
+                    const collision = existingIdentities.has(toIdentity) && !selectedIdentities.has(toIdentity);
+                    if (collision) {
+                        throw new SourceSelectionError(`Cannot migrate Skill ${JSON.stringify(migration.from.path)}: replacement identity ${JSON.stringify(migration.to.path)} already exists`);
+                    }
+                }
+                const replacements = new Map(migrations.map((migration) => [userGlobalInstallationIdentity(migration.from), migration.to]));
+                return {
+                    state: {
+                        version: 1,
+                        gitSources: state.gitSources,
+                        userGlobalInstallations: state.userGlobalInstallations.map((installation) => replacements.get(userGlobalInstallationIdentity(installation)) ?? installation),
+                    },
+                    result: undefined,
+                };
+            });
+        },
+        async selectSources(sourceIds) {
+            if (sourceIds.length === 0) {
+                throw new SourceSelectionError("At least one Source must be selected explicitly");
+            }
+            const sources = await this.listSources();
+            const byId = new Map(sources.map((source) => [source.id, source]));
+            const selected = [];
+            const seen = new Set();
+            for (const sourceId of sourceIds) {
+                if (typeof sourceId !== "string" || sourceId.length === 0 || seen.has(sourceId)) {
+                    continue;
+                }
+                const source = byId.get(sourceId);
+                if (!source) {
+                    throw new SourceNotFoundError(sourceId);
+                }
+                seen.add(sourceId);
+                selected.push(source);
+            }
+            if (selected.length === 0) {
+                throw new SourceSelectionError("At least one valid Source must be selected explicitly");
+            }
+            return Object.freeze(selected);
+        },
+        async resolveProjectSource(projectSource) {
+            return resolveProjectSource(projectSource);
+        },
+        async refreshProjectSource(projectSource) {
+            const source = resolveProjectSource(projectSource);
+            if (source.kind === "builtin") {
+                throw new BuiltInSourceError();
+            }
+            await gitAccess.refresh(source);
+            return source;
+        },
+        async readInstallationMethod(source, skillPath, previewTree) {
+            return previewTree === undefined
+                ? readSourceInstallationMethod(sourceContentAccess, source, skillPath)
+                : readInstallationMethodFromSkillTree(previewTree, skillPath);
+        },
+        async executeInstallationMethod(method, context) {
+            await executeSourceInstallationMethod(method, context);
+        },
+        async resolveSourceVersion(source) {
+            if (sourceContentAccess.readResolvedVersion) {
+                return sourceContentAccess.readResolvedVersion(source);
+            }
+            return source.kind === "builtin" && AGENT_DEPOT_PACKAGE_VERSION !== undefined
+                ? Object.freeze({ kind: "builtin-package", version: AGENT_DEPOT_PACKAGE_VERSION })
+                : undefined;
+        },
+        ...(sourceContentAccess.readSkillTreeSnapshot === undefined
+            ? {}
+            : {
+                readSkillTreeSnapshot: (source, skillPath) => sourceContentAccess.readSkillTreeSnapshot(source, skillPath),
+            }),
+        async discoverSkills(sourceIds) {
+            const sources = await this.selectSources(sourceIds);
+            return discoverSkillsFromSources(sources, sourceContentAccess);
+        },
+        async listUserGlobalInstallations() {
+            return (await stateStore.load()).userGlobalInstallations;
+        },
+        async addUserGlobalInstallation(selection) {
+            requireInstallationLocation(selection);
+            await stateStore.update((state) => {
+                const identity = JSON.stringify([selection.source, selection.path]);
+                if (state.userGlobalInstallations.some((candidate) => JSON.stringify([candidate.source, candidate.path]) === identity)) {
+                    throw new SourceSelectionError(`User-global Skill ${JSON.stringify(selection.path)} is already recorded`);
+                }
+                return {
+                    state: {
+                        version: 1,
+                        gitSources: state.gitSources,
+                        userGlobalInstallations: [...state.userGlobalInstallations, selection],
+                    },
+                    result: undefined,
+                };
+            });
+        },
+        async updateUserGlobalInstallation(selection) {
+            requireInstallationLocation(selection);
+            await stateStore.update((state) => {
+                const identity = JSON.stringify([selection.source, selection.path]);
+                const index = state.userGlobalInstallations.findIndex((candidate) => JSON.stringify([candidate.source, candidate.path]) === identity);
+                if (index < 0) {
+                    throw new SourceSelectionError(`User-global Skill ${JSON.stringify(selection.path)} is not recorded`);
+                }
+                const installations = [...state.userGlobalInstallations];
+                installations[index] = selection;
+                return {
+                    state: {
+                        version: 1,
+                        gitSources: state.gitSources,
+                        userGlobalInstallations: installations,
+                    },
+                    result: undefined,
+                };
+            });
+        },
+        async removeUserGlobalInstallations(selections) {
+            await stateStore.update((state) => {
+                const selectedIdentities = new Set();
+                for (const selection of selections) {
+                    const identity = userGlobalInstallationIdentity(selection);
+                    if (selectedIdentities.has(identity)) {
+                        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(selection.path)} was selected more than once`);
+                    }
+                    selectedIdentities.add(identity);
+                    if (!state.userGlobalInstallations.some((candidate) => userGlobalInstallationIdentity(candidate) === identity)) {
+                        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(selection.path)} is not recorded`);
+                    }
+                }
+                return {
+                    state: {
+                        version: 1,
+                        gitSources: state.gitSources,
+                        userGlobalInstallations: state.userGlobalInstallations.filter((installation) => !selectedIdentities.has(userGlobalInstallationIdentity(installation))),
+                    },
+                    result: undefined,
+                };
+            });
+        },
+        async removeCatalogData() {
+            await stateStore.remove();
+        },
+    };
+}
+/** Converts persisted project identity into a read-only Source identity. */
+export function resolveProjectSource(projectSource) {
+    if (projectSource.kind === "builtin") {
+        return BUILT_IN_SOURCE;
+    }
+    if ("url" in projectSource) {
+        const id = sourceIdForUrl(projectSource.url);
+        return Object.freeze({
+            id,
+            kind: "git",
+            url: projectSource.url,
+            ...(projectSource.ref === undefined ? {} : { ref: projectSource.ref }),
+        });
+    }
+    throw new SourceMetadataError("Project Source paths are not independently resolvable by the Git-only V1 adapter; use a project-relative Source path with a supported adapter");
+}
+/**
+ * Validates the only external-method shape the CLI may accept. Unknown fields,
+ * shell strings, empty argv, and control characters all fail closed.
+ */
+export function parseSourceInstallationMethod(value) {
+    return parsePortableInstallationMethod(value, {
+        label: "upstream installation metadata",
+        error: (message) => new SourceMetadataError(message),
+    });
+}
+/** Resolves and validates a method cwd before any managed tree is replaced. */
+export async function resolveSourceInstallationMethodCwd(method, projectRootInput) {
+    const projectRoot = await realpath(path.resolve(projectRootInput)).catch((error) => {
+        throw new SourceMetadataError(`cannot resolve the project root: ${errorMessage(error)}`);
+    });
+    const requestedCwd = path.resolve(projectRoot, method.cwd ?? ".");
+    const cwd = await realpath(requestedCwd).catch((error) => {
+        throw new SourceMetadataError(`cannot resolve the installation method cwd: ${errorMessage(error)}`);
+    });
+    const relative = path.relative(projectRoot, cwd);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new SourceMetadataError("upstream installation method cwd escapes the project root after realpath resolution");
+    }
+    return cwd;
+}
+/** Executes a validated method with an argument vector and no shell. */
+export async function executeSourceInstallationMethod(method, context) {
+    const cwd = await resolveSourceInstallationMethodCwd(method, context.projectRoot);
+    const result = await runProcess(method.argv[0], method.argv.slice(1), { cwd });
+    if (result.code === 0) {
+        return;
+    }
+    const { code, signal, stderr } = result;
+    throw new SourceMetadataError(`upstream installation method failed${signal ? ` (${signal})` : ` (exit ${code ?? "unknown"})`}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function userGlobalInstallationIdentity(selection) {
+    return JSON.stringify([selection.source, selection.path]);
+}
+function sourceIdForUserGlobalInstallation(selection) {
+    return selection.source.kind === "builtin"
+        ? selection.source.id
+        : "url" in selection.source
+            ? sourceIdForUrl(selection.source.url)
+            : "";
+}
+async function readSourceInstallationMethod(sourceContentAccess, source, skillPath) {
+    if (!sourceContentAccess.readSkillTree) {
+        return undefined;
+    }
+    return readInstallationMethodFromSkillTree(await sourceContentAccess.readSkillTree(source, skillPath), skillPath);
+}
+/** Reads method metadata from one already captured Skill tree snapshot. */
+export function readInstallationMethodFromSkillTree(files, skillPath) {
+    const prefix = `${skillPath}/`;
+    const metadataFiles = files.filter((file) => file.path.startsWith(prefix) &&
+        SOURCE_METADATA_FILENAMES.includes(file.path.slice(prefix.length)));
+    if (metadataFiles.length > 1) {
+        throw new SourceMetadataError("selected Skill contains more than one installation metadata file");
+    }
+    const metadataFile = metadataFiles[0];
+    if (!metadataFile) {
+        return undefined;
+    }
+    if (metadataFile.content.byteLength > SOURCE_METADATA_MAX_BYTES) {
+        throw new SourceMetadataError("installation metadata file exceeds the safe size limit");
+    }
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(metadataFile.content).toString("utf8"));
+    }
+    catch (error) {
+        throw new SourceMetadataError(`installation metadata file is not valid JSON: ${errorMessage(error)}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new SourceMetadataError("installation metadata file must contain a JSON object");
+    }
+    const record = value;
+    return Object.hasOwn(record, "method") ? record.method : value;
+}
+function requireInstallationLocation(selection) {
+    if (selection.installation === undefined) {
+        throw new SourceSelectionError(`User-global Skill ${JSON.stringify(selection.path)} must include an installation location`);
+    }
+}

package/dist/src/tui/adoption-actions.js

@@ -0,0 +1,144 @@
+import { HOST_CHOICES } from "./catalog-actions.js";
+import { runInstall } from "./catalog-installs.js";
+import { errorText } from "./batch.js";
+import { defaultAdoptionHosts, findAdoptionCandidates, prepareAdoption } from "./installations.js";
+import { answerYesNo, applyChecklistOutcome, hostChecklistKey, moveCursor, versionInputKey } from "./mode-keys.js";
+function cancel(context) {
+    context.setMessage({ kind: "ok", text: "Adoption cancelled" });
+    context.browse();
+}
+function fail(context, error) {
+    if (!context.isMounted())
+        return;
+    context.setMessage({ kind: "error", text: errorText(error) });
+    context.browse();
+}
+/** `A` / Enter on an unmanaged Skill: looks for the Source Skills it could be adopted as. */
+export async function startAdoption(context, group) {
+    // Adoption keeps an existing directory in place, so it needs a real directory (the shared root first).
+    const entry = group.locations.find((location) => location.entry !== undefined)?.entry;
+    if (entry === undefined) {
+        context.setMessage({ kind: "error", text: "Adoption is not available for symlinks" });
+        return;
+    }
+    context.setMessage(undefined);
+    context.setMode({ kind: "busy", label: `Looking for a Source Skill named ${entry.name}...` });
+    try {
+        const candidates = await findAdoptionCandidates(context.operations, entry);
+        if (!context.isMounted())
+            return;
+        if (candidates.length === 0) {
+            context.setMessage({ kind: "error", text: `No Source Skill named "${entry.name}" exists in the registered Sources, so ${entry.path} cannot be adopted` });
+            context.browse();
+        }
+        else if (candidates.length === 1) {
+            context.setMode({ kind: "host", entry, skill: candidates[0], cursor: 0, selected: defaultAdoptionHosts(entry) });
+        }
+        else {
+            context.setMode({ kind: "pick", entry, candidates, cursor: 0 });
+        }
+    }
+    catch (error) {
+        fail(context, error);
+    }
+}
+async function prepare(context, mode, version) {
+    context.setMode({ kind: "busy", label: `Refreshing source and checking that ${mode.entry.name} matches...` });
+    try {
+        const adoption = await prepareAdoption(context.operations, context.env, mode.entry, mode.skill, { hosts: mode.hosts, version });
+        if (!context.isMounted())
+            return;
+        context.setMode({ kind: "confirm", entry: mode.entry, skill: mode.skill, adoption });
+    }
+    catch (error) {
+        fail(context, error);
+    }
+}
+async function confirm(context, mode, exposure) {
+    context.setMode({ kind: "busy", label: `Adopting ${mode.entry.name}...` });
+    let result;
+    try {
+        result = { kind: "ok", text: (await runInstall(mode.adoption.prepared, context.operations, exposure)).join(" ") };
+    }
+    catch (error) {
+        result = { kind: "error", text: errorText(error) };
+    }
+    await context.reload();
+    if (!context.isMounted())
+        return;
+    context.setMessage(result);
+    context.browse();
+}
+function handlePickKey(context, mode, input, key) {
+    const cursor = moveCursor(mode.cursor, mode.candidates.length, input, key);
+    if (key.escape)
+        cancel(context);
+    else if (cursor !== undefined)
+        context.setMode({ ...mode, cursor });
+    else if (key.return) {
+        context.setMode({ kind: "host", entry: mode.entry, skill: mode.candidates[mode.cursor], cursor: 0, selected: defaultAdoptionHosts(mode.entry) });
+    }
+}
+function handleHostKey(context, mode, input, key) {
+    applyChecklistOutcome(hostChecklistKey(mode, HOST_CHOICES, input, key), {
+        cancel: () => cancel(context),
+        update: (state) => context.setMode({ ...mode, ...state }),
+        submit: (hosts) => context.setMode({ kind: "version", entry: mode.entry, skill: mode.skill, hosts }),
+        setMessage: context.setMessage,
+    });
+}
+function handleVersionKey(context, mode, input, key) {
+    if (key.escape)
+        cancel(context);
+    else if (input === "1")
+        void prepare(context, mode, { policy: "latest" });
+    else if (input === "2")
+        context.setMode({ ...mode, kind: "fixed", value: "" });
+}
+function handleFixedKey(context, mode, input, key) {
+    const outcome = versionInputKey(mode.value, input, key);
+    if (outcome.kind === "cancel")
+        cancel(context);
+    else if (outcome.kind === "submit")
+        void prepare(context, mode, { policy: "fixed", version: mode.value });
+    else if (outcome.kind === "edit")
+        context.setMode({ ...mode, value: outcome.value });
+}
+function handleConfirmKey(context, mode, input, key) {
+    if (!mode.adoption.verdict.adoptable) {
+        if (key.escape || key.return || input === "n")
+            cancel(context);
+        return;
+    }
+    answerYesNo(input, key, () => {
+        if (mode.adoption.prepared.additionalHostExposure)
+            context.setMode({ ...mode, kind: "confirm-exposure" });
+        else
+            void confirm(context, mode, false);
+    }, () => cancel(context));
+}
+/** Handles a key in an adoption mode; other modes are ignored. */
+export function handleAdoptionKey(context, mode, input, key) {
+    switch (mode.kind) {
+        case "pick":
+            handlePickKey(context, mode, input, key);
+            return;
+        case "host":
+            handleHostKey(context, mode, input, key);
+            return;
+        case "version":
+            handleVersionKey(context, mode, input, key);
+            return;
+        case "fixed":
+            handleFixedKey(context, mode, input, key);
+            return;
+        case "confirm":
+            handleConfirmKey(context, mode, input, key);
+            return;
+        case "confirm-exposure":
+            answerYesNo(input, key, () => void confirm(context, mode, true), () => cancel(context));
+            return;
+        default:
+            return;
+    }
+}