@rbbtsn0w/adg 0.1.0-alpha.1 → 0.1.0-beta.2

package/dist/src/commands/remove.js

@@ -0,0 +1,102 @@
+import { existsSync, lstatSync, readdirSync, readlinkSync, rmdirSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { claudeSkillsDir, lockPath, marketplacePath, pluginDir } from "../paths.js";
+import { readLock, removeEntry, writeLock } from "../lock.js";
+import { readMarketplace, removeMarketplacePlugin, writeMarketplace } from "../marketplace.js";
+import { basename } from "node:path";
+import { resolveAgents } from "../agents/index.js";
+/**
+ * Remove an installed plugin: delete its directory, drop it from
+ * `.plugin-lock.json` and `marketplace.json`, and clean up any Claude
+ * skills-dir symlinks that pointed at it. Only paths under `pluginsDir` (plus
+ * symlinks that resolve back into it) are touched.
+ *
+ * Refuses when another installed plugin depends on it, unless `force` is set.
+ */
+export function removePlugin(opts) {
+    const { name } = opts;
+    const cwd = opts.cwd ?? process.cwd();
+    const lockFile = lockPath(opts.pluginsDir);
+    const lock = readLock(lockFile);
+    const inLock = name in lock.plugins;
+    // Locate the plugin via its recorded origin (nested for remote sources). An
+    // orphan that is on disk but absent from the lock falls back to the flat path.
+    const dir = inLock
+        ? pluginDir(opts.pluginsDir, name, lock.plugins[name].origin)
+        : join(opts.pluginsDir, name);
+    const onDisk = existsSync(dir);
+    if (!inLock && !onDisk) {
+        throw new Error(`plugin "${name}" is not installed in ${opts.pluginsDir}`);
+    }
+    if (!opts.force) {
+        const dependents = Object.entries(lock.plugins)
+            .filter(([n, e]) => n !== name && e.dependencies && name in e.dependencies)
+            .map(([n]) => n);
+        if (dependents.length > 0) {
+            throw new Error(`cannot remove "${name}": required by ${dependents.join(", ")}. ` +
+                `Remove the dependents first or pass --force.`);
+        }
+    }
+    // Clean up Claude symlinks (created by `adg plugins link --target claude`) in
+    // both global and project scopes — but only ones that resolve back to this
+    // plugin's directory, so unrelated entries are never disturbed.
+    const target = resolve(dir);
+    const unlinked = [];
+    for (const dir of [claudeSkillsDir(true, cwd), claudeSkillsDir(false, cwd)]) {
+        const linkPath = join(dir, name);
+        if (isSymlinkTo(linkPath, target)) {
+            rmSync(linkPath);
+            unlinked.push(linkPath);
+        }
+    }
+    let removedDir;
+    if (onDisk) {
+        rmSync(dir, { recursive: true, force: true });
+        removedDir = dir;
+        // Drop the per-marketplace bucket if it became empty (nested remote layout).
+        pruneEmptyParent(dirname(dir), opts.pluginsDir);
+    }
+    const removedFromLock = removeEntry(lock, name);
+    if (removedFromLock)
+        writeLock(lockFile, lock);
+    const marketFile = marketplacePath(opts.pluginsDir);
+    const market = readMarketplace(marketFile, basename(opts.pluginsDir));
+    const removedFromMarketplace = removeMarketplacePlugin(market, name);
+    if (removedFromMarketplace)
+        writeMarketplace(marketFile, market);
+    // Uninstall from the agents so we don't leave them enabled, pointing at a
+    // now-deleted directory. Best-effort across all; missing CLIs are skipped.
+    let agents;
+    if (opts.deactivate) {
+        const ctx = { pluginsDir: opts.pluginsDir, plugins: [name], scope: opts.scope ?? "project" };
+        agents = (opts.agents ?? resolveAgents()).map((a) => a.deactivate(ctx));
+    }
+    return { name, removedDir, unlinked, removedFromLock, removedFromMarketplace, agents };
+}
+/**
+ * Remove `parent` if it is an empty per-marketplace bucket below `pluginsDir`.
+ * Never touches `pluginsDir` itself (that would be the flat local layout).
+ */
+function pruneEmptyParent(parent, pluginsDir) {
+    if (resolve(parent) === resolve(pluginsDir))
+        return;
+    try {
+        if (readdirSync(parent).length === 0)
+            rmdirSync(parent);
+    }
+    catch {
+        // bucket already gone or not readable — nothing to prune
+    }
+}
+export function isSymlinkTo(linkPath, target) {
+    try {
+        if (!lstatSync(linkPath).isSymbolicLink())
+            return false;
+        // readlinkSync may return a path relative to the link's own directory; resolve
+        // it there (resolve ignores the base when the target is already absolute).
+        return resolve(dirname(linkPath), readlinkSync(linkPath)) === resolve(target);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/commands/select-agents.js

@@ -0,0 +1,40 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { allAgents, detectedAgents } from "../agents/index.js";
+/**
+ * Interactively choose which AI agents to adapt an installed plugin for.
+ *
+ * Mirrors the skills install flow: detect the agents present on the machine,
+ * pre-select them, and let the user toggle. When nothing is detected we fall
+ * back to pre-selecting every target so a fresh setup still adapts for all.
+ *
+ * Callers should only reach this in an interactive TTY without an explicit
+ * `--target`; non-interactive paths stay flag-driven.
+ */
+export async function selectTargetsInteractive() {
+    const agents = allAgents();
+    const detectedSet = new Set(detectedAgents().map((a) => a.id));
+    const initialValues = (detectedSet.size > 0 ? [...detectedSet] : agents.map((a) => a.id));
+    if (detectedSet.size > 0) {
+        const names = agents.filter((a) => detectedSet.has(a.id)).map((a) => pc.cyan(a.displayName)).join(", ");
+        p.log.info(`Detected: ${names}`);
+    }
+    else {
+        p.log.info(pc.dim("No agents detected locally — pre-selecting all."));
+    }
+    const selected = await p.multiselect({
+        message: `Which agents do you want to adapt for? ${pc.dim("(space to toggle)")}`,
+        options: agents.map((a) => ({
+            value: a.id,
+            label: a.displayName,
+            ...(detectedSet.has(a.id) ? { hint: "detected" } : {}),
+        })),
+        initialValues,
+        required: true,
+    });
+    if (p.isCancel(selected)) {
+        p.cancel("Installation cancelled");
+        process.exit(0);
+    }
+    return selected;
+}

package/dist/src/commands/select-components.js

@@ -0,0 +1,61 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { multiselectSkills } from "./multiselect-skills.js";
+function cancelled(value) {
+    if (p.isCancel(value)) {
+        p.cancel("Installation cancelled");
+        process.exit(0);
+    }
+    return false;
+}
+/**
+ * The "install everything?" gate. Returns true to install each selected plugin
+ * in full, false to drop into per-plugin component selection. Used by `add` in
+ * an interactive terminal when no --only/--skill flags were given.
+ */
+export async function confirmFullInstall(plugins) {
+    const list = plugins.length === 1 ? plugins[0] : `${plugins.length} plugins`;
+    const choice = await p.select({
+        message: `Install everything in ${pc.cyan(list)}?`,
+        options: [
+            { value: true, label: "Yes, install all", hint: "every skill, command, agent, mcp…" },
+            { value: false, label: "No, let me choose", hint: "pick components per plugin" },
+        ],
+        initialValue: true,
+    });
+    if (cancelled(choice))
+        return true;
+    return choice;
+}
+/**
+ * Per-plugin component picker (①). Choose which categories to expose; if skills
+ * is kept and the plugin has several, drill in to pick individual skills. Files
+ * are still installed in full — this only narrows what the runtime sees.
+ */
+export async function selectComponentsInteractive(req) {
+    const components = await p.multiselect({
+        message: `${pc.bold(req.name)} — what to install? ${pc.dim("(space to toggle)")}`,
+        options: req.present.map((c) => ({ value: c, label: `${c} (${req.contents[c].length})` })),
+        initialValues: [...req.present],
+        required: true,
+    });
+    if (cancelled(components))
+        return { components: [...req.present] };
+    const chosen = components;
+    const selection = { components: chosen };
+    // Drill into individual skills only when skills is kept and there's a choice.
+    if (chosen.includes("skills") && req.contents.skills.length > 1) {
+        const message = `${pc.bold(req.name)} — which skills? ${pc.dim("(space to toggle)")}`;
+        const options = req.contents.skills.map((s) => ({ value: s, label: s }));
+        const initialValues = [...req.contents.skills];
+        const skills = req.skillDescription
+            ? await multiselectSkills({ message, options, initialValues, loadDescription: req.skillDescription })
+            : await p.multiselect({ message, options, initialValues, required: true });
+        if (!cancelled(skills)) {
+            const picked = skills;
+            if (picked.length !== req.contents.skills.length)
+                selection.skills = picked;
+        }
+    }
+    return selection;
+}

package/dist/src/commands/select-plugins.js

@@ -0,0 +1,25 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+/**
+ * Interactive multiselect for choosing which plugins to install from a source
+ * that holds several. Mirrors the skills install flow. Native (reverse-adapted)
+ * plugins are flagged so the user knows they came from a Claude/Codex manifest.
+ */
+export async function selectPluginsInteractive(choices) {
+    const selected = await p.multiselect({
+        message: `Select plugins to install ${pc.dim("(space to toggle)")}`,
+        options: choices.map((c) => ({
+            value: c.name,
+            label: c.native ? `${c.name} ${pc.dim("(native)")}` : c.name,
+            ...(c.description
+                ? { hint: c.description.length > 60 ? c.description.slice(0, 57) + "..." : c.description }
+                : {}),
+        })),
+        required: true,
+    });
+    if (p.isCancel(selected)) {
+        p.cancel("Installation cancelled");
+        process.exit(0);
+    }
+    return selected;
+}

package/dist/src/commands/select-scope.js

@@ -0,0 +1,20 @@
+import * as p from "@clack/prompts";
+/**
+ * Ask whether to install into the project (.agents/plugins) or globally
+ * (~/.agents/plugins). Returns true for global. Used by `add` when no scope
+ * flag (--global/--project/--dir) was given in an interactive terminal.
+ */
+export async function selectScopeInteractive() {
+    const scope = await p.select({
+        message: "Installation scope",
+        options: [
+            { value: false, label: "Project", hint: ".agents/plugins (committed with your project)" },
+            { value: true, label: "Global", hint: "~/.agents/plugins (available across all projects)" },
+        ],
+    });
+    if (p.isCancel(scope)) {
+        p.cancel("Installation cancelled");
+        process.exit(0);
+    }
+    return scope;
+}

package/dist/src/commands/update.js

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { folderHash } from "../hash.js";
+import { packageFilter } from "../package.js";
+import { lockPath, installedPluginDir } from "../paths.js";
+import { readLock, writeLock } from "../lock.js";
+import { readManifest } from "../manifest.js";
+import { adaptPlugin } from "./adapt.js";
+import { resolveAgents } from "../agents/index.js";
+/**
+ * Re-scan installed plugins in a plugins directory, refreshing each lock
+ * entry's version and folderHash from disk. Entries whose content or version
+ * changed are reported as `changed`. A missing plugin directory is reported as
+ * an issue rather than silently dropped.
+ *
+ * With `resync`, changed plugins are re-adapted (honoring their selection) and
+ * re-installed into the agents so Claude/Codex reflect the new content.
+ */
+export function updateLock(pluginsDir, now = new Date().toISOString(), opts = {}) {
+    const lockFile = lockPath(pluginsDir);
+    const lock = readLock(lockFile);
+    const results = [];
+    const missing = [];
+    const changedNames = [];
+    for (const [name, entry] of Object.entries(lock.plugins)) {
+        const dir = installedPluginDir(pluginsDir, name, entry.origin);
+        if (!existsSync(dir)) {
+            missing.push(name);
+            continue;
+        }
+        const manifest = readManifest(dir);
+        const hash = folderHash(dir, [".claude-plugin", ".codex-plugin"], packageFilter(manifest, { includeProjections: false }));
+        const changed = hash !== entry.folderHash || manifest.version !== entry.version;
+        if (changed) {
+            entry.folderHash = hash;
+            entry.version = manifest.version;
+            entry.updatedAt = now;
+            // Regenerate runtime manifests from the updated source, honoring selection.
+            adaptPlugin(dir, ["claude", "codex"], entry.selection);
+            changedNames.push(name);
+        }
+        results.push({ name, changed, version: manifest.version, folderHash: hash });
+    }
+    writeLock(lockFile, lock);
+    const out = { results, missing };
+    if (opts.resync && changedNames.length > 0) {
+        const ctx = { pluginsDir, plugins: changedNames, scope: opts.scope ?? "project" };
+        out.agents = (opts.agents ?? resolveAgents()).map((a) => a.refresh(ctx));
+    }
+    return out;
+}

package/dist/src/commands/validate.js

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ADG_MANIFEST_PATH, collectIssues } from "../manifest.js";
+import { readFileSync } from "node:fs";
+/**
+ * Validate a plugin's manifest against the ADG schema and check that the
+ * directories/files it references actually exist.
+ */
+export function validatePlugin(pluginDir) {
+    const manifestFile = join(pluginDir, ADG_MANIFEST_PATH);
+    if (!existsSync(manifestFile)) {
+        return { ok: false, issues: [`${ADG_MANIFEST_PATH} not found in ${pluginDir}`] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(manifestFile, "utf8"));
+    }
+    catch (err) {
+        return { ok: false, issues: [`${manifestFile} is not valid JSON: ${err.message}`] };
+    }
+    const issues = collectIssues(raw);
+    if (issues.length > 0)
+        return { ok: false, issues };
+    // Reference checks (only when structural validation passed).
+    const m = raw;
+    const pathFields = [
+        ["agents", m.agents],
+        ["commands", m.commands],
+        ["apps", m.apps],
+        ["hooks", m.hooks],
+        ["mcp", m.mcp],
+    ];
+    for (const [field, value] of pathFields) {
+        if (typeof value === "string" && !existsSync(join(pluginDir, value))) {
+            issues.push(`${field} points to "${value}" which does not exist`);
+        }
+    }
+    if (typeof m.skills === "string") {
+        if (!existsSync(join(pluginDir, m.skills))) {
+            issues.push(`skills root "${m.skills}" does not exist`);
+        }
+    }
+    else if (Array.isArray(m.skills)) {
+        for (const s of m.skills) {
+            if (!existsSync(join(pluginDir, s)))
+                issues.push(`skill path "${s}" does not exist`);
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}

package/dist/src/components.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { resolveSkills } from "./skills.js";
+import { COMPONENT_TYPES } from "./types.js";
+export { COMPONENT_TYPES };
+/** Recursively collect regular (non-dotfile) file basenames, without extension. */
+function collectFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (e.name.startsWith("."))
+            continue;
+        if (e.isDirectory())
+            out.push(...collectFiles(join(dir, e.name)));
+        else
+            out.push(e.name.replace(/\.[^.]+$/, ""));
+    }
+    return out.sort();
+}
+/**
+ * A single file's member name: its basename without extension. `base` is
+ * injectable so the OS-separator handling can be exercised deterministically in
+ * tests (path.win32.basename vs path.posix.basename) regardless of host platform.
+ */
+export function fileMemberName(absPath, base = basename) {
+    return base(absPath).replace(/\.[^.]+$/, "");
+}
+/** Members of a declared path: a directory yields its files, a file yields its own name. */
+function membersOf(dir, rel) {
+    if (!rel)
+        return [];
+    const abs = join(dir, rel);
+    if (!existsSync(abs))
+        return [];
+    const files = collectFiles(abs);
+    if (files.length > 0)
+        return files;
+    return [fileMemberName(abs)]; // a single file
+}
+/** Server names declared in an MCP config file (mcpServers/servers map). */
+function mcpServers(file) {
+    if (!existsSync(file))
+        return [];
+    try {
+        const json = JSON.parse(readFileSync(file, "utf8"));
+        const servers = (json.mcpServers ?? json.servers);
+        return servers && typeof servers === "object" ? Object.keys(servers).sort() : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Enumerate what a plugin contains, by reading its manifest's component paths. */
+export function pluginContents(dir, manifest) {
+    return {
+        skills: resolveSkills(dir, manifest),
+        agents: membersOf(dir, manifest.agents),
+        commands: membersOf(dir, manifest.commands),
+        apps: membersOf(dir, manifest.apps),
+        hooks: membersOf(dir, manifest.hooks),
+        mcp: manifest.mcp ? mcpServers(join(dir, manifest.mcp)) : [],
+    };
+}
+/** Component types this plugin actually has (non-empty). */
+export function presentComponents(contents) {
+    return COMPONENT_TYPES.filter((c) => contents[c].length > 0);
+}
+/** Whether a category is exposed under a selection (no selection = everything). */
+export function isExposed(selection, category) {
+    return !selection || selection.components.includes(category);
+}
+/** Apply a selection to a contents map, returning only the exposed members. */
+export function exposedContents(contents, selection) {
+    if (!selection)
+        return contents;
+    const out = {};
+    for (const c of COMPONENT_TYPES) {
+        if (!isExposed(selection, c)) {
+            out[c] = [];
+        }
+        else if (c === "skills" && selection.skills) {
+            out[c] = contents.skills.filter((s) => selection.skills.includes(s));
+        }
+        else {
+            out[c] = contents[c];
+        }
+    }
+    return out;
+}

package/dist/src/deps.js

@@ -0,0 +1,46 @@
+import { satisfies } from "./semver.js";
+export class DependencyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DependencyError";
+    }
+}
+/**
+ * Compute a topological install order for `rootName` and its transitive
+ * dependencies, using `candidates` (name -> plugin) as the resolution universe.
+ *
+ * Dependencies are emitted before the plugins that depend on them, with
+ * `rootName` last. Missing dependencies, version-constraint violations, and
+ * dependency cycles are reported as DependencyError.
+ */
+export function resolveInstallOrder(rootName, candidates) {
+    if (!candidates.has(rootName)) {
+        throw new DependencyError(`plugin "${rootName}" not found among candidates`);
+    }
+    const order = [];
+    const visited = new Set(); // fully processed
+    const onStack = new Set(); // current DFS path (cycle detection)
+    const visit = (name, requiredBy, constraint) => {
+        const candidate = candidates.get(name);
+        if (!candidate) {
+            throw new DependencyError(`missing dependency "${name}"${requiredBy ? ` required by "${requiredBy}"` : ""}`);
+        }
+        if (constraint && !satisfies(candidate.manifest.version, constraint)) {
+            throw new DependencyError(`version conflict: "${requiredBy}" requires "${name}@${constraint}" but found ${candidate.manifest.version}`);
+        }
+        if (visited.has(name))
+            return;
+        if (onStack.has(name)) {
+            throw new DependencyError(`dependency cycle detected at "${name}"`);
+        }
+        onStack.add(name);
+        for (const dep of candidate.manifest.dependencies ?? []) {
+            visit(dep.name, name, dep.version);
+        }
+        onStack.delete(name);
+        visited.add(name);
+        order.push(name);
+    };
+    visit(rootName, null, null);
+    return order;
+}

package/dist/src/fsutil.js

@@ -0,0 +1,32 @@
+import { cpSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative } from "node:path";
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+export function writeJson(file, value) {
+    ensureDir(dirname(file));
+    writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+}
+export function writeText(file, value) {
+    ensureDir(dirname(file));
+    writeFileSync(file, value);
+}
+/**
+ * Copy a plugin directory, skipping VCS and dependency noise. When `include` is
+ * given (a root-relative path predicate, e.g. from `packageFilter`), only the
+ * declared payload is copied — dev cruft like `src/`/`test/` is left behind.
+ */
+export function copyPluginDir(src, dest, include) {
+    ensureDir(dirname(dest));
+    cpSync(src, dest, {
+        recursive: true,
+        filter: (from) => {
+            const base = from.split(/[/\\]/).pop() ?? "";
+            if (base === ".git" || base === "node_modules" || base === ".DS_Store")
+                return false;
+            if (!include)
+                return true;
+            return include(relative(src, from));
+        },
+    });
+}

package/dist/src/hash.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+/** Directory names that never contribute to a plugin's content hash. */
+const HASH_IGNORE = new Set([".git", "node_modules", ".DS_Store"]);
+/**
+ * Compute a deterministic content hash for a plugin directory.
+ *
+ * The hash incorporates each file's POSIX-normalized relative path and its
+ * bytes, sorted by path so the result is stable across filesystems and walk
+ * order. `extraIgnore` drops directory names by segment (e.g. generated adapter
+ * manifests). `include`, when given, restricts the hash to the packaged payload
+ * (root-relative path predicate, e.g. from `packageFilter`) so an in-place
+ * plugin and a copied install hash identically.
+ */
+export function folderHash(dir, extraIgnore = [], include) {
+    const ignore = new Set([...HASH_IGNORE, ...extraIgnore]);
+    const files = [];
+    collect(dir, dir, ignore, include, files);
+    files.sort();
+    const hash = createHash("sha256");
+    for (const rel of files) {
+        hash.update(rel, "utf8");
+        hash.update("\0");
+        hash.update(readFileSync(join(dir, rel)));
+        hash.update("\0");
+    }
+    // Self-describing digest (SRI-style) so the algorithm can evolve later.
+    return `sha256-${hash.digest("hex")}`;
+}
+function collect(root, current, ignore, include, out) {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+        if (ignore.has(entry.name))
+            continue;
+        const abs = join(current, entry.name);
+        const rel = relative(root, abs);
+        // Match ignore entries against any path segment (e.g. ".claude-plugin").
+        if (rel.split(sep).some((seg) => ignore.has(seg)))
+            continue;
+        const relPosix = rel.split(sep).join("/");
+        // Prune anything outside the packaged payload (directories too, by segment).
+        if (include && !include(relPosix))
+            continue;
+        if (entry.isDirectory()) {
+            collect(root, abs, ignore, include, out);
+        }
+        else if (entry.isFile()) {
+            out.push(relPosix);
+        }
+    }
+}

package/dist/src/lock.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { LOCK_VERSION } from "./types.js";
+export function emptyLock() {
+    return { version: LOCK_VERSION, plugins: {} };
+}
+export function readLock(file) {
+    if (!existsSync(file))
+        return emptyLock();
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof raw.version !== "number" || typeof raw.plugins !== "object" || raw.plugins === null) {
+        throw new Error(`${file} is not a valid .plugin-lock.json`);
+    }
+    // Pre-release policy: a lock from an older format version is fully
+    // regenerable from the plugin directories, so rebuild rather than merge
+    // incompatible entry shapes.
+    if (raw.version !== LOCK_VERSION)
+        return emptyLock();
+    return raw;
+}
+export function writeLock(file, lock) {
+    writeFileSync(file, JSON.stringify(lock, null, 2) + "\n");
+}
+/**
+ * Remove a plugin entry from the lock. Drops it from `lastSelected` too.
+ * Returns true if an entry was actually removed.
+ */
+export function removeEntry(lock, name) {
+    if (!(name in lock.plugins))
+        return false;
+    delete lock.plugins[name];
+    if (lock.lastSelected) {
+        lock.lastSelected = lock.lastSelected.filter((n) => n !== name);
+        if (lock.lastSelected.length === 0)
+            delete lock.lastSelected;
+    }
+    return true;
+}
+/**
+ * Insert or update a plugin entry. Preserves the original installedAt on update
+ * and always refreshes updatedAt. `lastSelected` is set to the touched plugin.
+ */
+export function upsertEntry(lock, name, entry, now = new Date().toISOString()) {
+    const prev = lock.plugins[name];
+    lock.plugins[name] = {
+        ...entry,
+        installedAt: prev?.installedAt ?? now,
+        updatedAt: now,
+    };
+    lock.lastSelected = [name];
+    return lock;
+}