@iseoane/agent-depot 0.4.1 → 0.5.1

package/dist/src/package-state.js

@@ -0,0 +1,404 @@
+import { chmod, mkdir, readFile, rmdir } 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 { PACKAGE_HOSTS, selectionKey, } from "./package-model.js";
+import { PROJECT_MANIFEST_VERSION, ProjectManifestError, parseProjectManifest } from "./project-manifest.js";
+import { defaultSourceStatePath } from "./source-state.js";
+export class PackageStateError extends Error {
+    constructor(statePath, reason) {
+        super(`Package state at ${JSON.stringify(statePath)} is invalid: ${reason}. The file was not modified; inspect or repair it before retrying.`);
+        this.name = "PackageStateError";
+    }
+}
+export class PackageStateLockError extends Error {
+    constructor(statePath) {
+        super(`Package state at ${JSON.stringify(statePath)} is busy; no changes were made. Retry after the other process finishes.`);
+        this.name = "PackageStateLockError";
+    }
+}
+/** Raised before any filesystem call when a digest cannot name a receipt file. */
+export class PackageApprovalDigestError extends Error {
+    constructor(digest) {
+        super(`Approval digest ${JSON.stringify(digest)} is not a SHA-256 hex digest; no receipt was read or written.`);
+        this.name = "PackageApprovalDigestError";
+    }
+}
+const EMPTY_STATE = Object.freeze({ version: 1, packages: Object.freeze([]) });
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_RETRY_MS = 10;
+const APPROVAL_DIGEST = /^[0-9a-fA-F]{64}$/u;
+const SELECTION_KEYS = {
+    pi: ["host", "root", "source", "version"],
+    claude: ["host", "marketplaceRoot", "pluginName", "source", "version"],
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function containsControlCharacter(value) {
+    return Array.from(value).some((character) => (character.codePointAt(0) ?? 0) <= 0x1f || character.codePointAt(0) === 0x7f);
+}
+function assertKeys(value, allowed, label, statePath) {
+    const allowedKeys = new Set(allowed);
+    const unsupported = Object.keys(value).find((key) => !allowedKeys.has(key));
+    if (unsupported) {
+        throw new PackageStateError(statePath, `${label} contains unsupported field ${JSON.stringify(unsupported)}`);
+    }
+}
+function nonEmptyString(value, label, statePath) {
+    if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+        throw new PackageStateError(statePath, `${label} must be a non-empty string without surrounding whitespace`);
+    }
+    if (/\s/u.test(value) || containsControlCharacter(value)) {
+        throw new PackageStateError(statePath, `${label} contains unsafe whitespace or control characters`);
+    }
+    return value;
+}
+function timestamp(value, label, statePath) {
+    if (typeof value !== "string" || Number.isNaN(Date.parse(value)) || new Date(value).toISOString() !== value) {
+        throw new PackageStateError(statePath, `${label} must be an ISO-8601 UTC timestamp`);
+    }
+    return value;
+}
+/** A Source-relative directory in the one canonical form discovery produces. */
+function sourceDirectory(value, label, statePath) {
+    if (typeof value !== "string") {
+        throw new PackageStateError(statePath, `${label} must be a string`);
+    }
+    if (value !== "" && (value === "." || value.startsWith("./") || value.endsWith("/") || value.includes("//") || value.split("/").includes("."))) {
+        throw new PackageStateError(statePath, `${label} must be the canonical Source-relative directory, "" for the Source root`);
+    }
+    return value;
+}
+function pluginName(value, label, statePath) {
+    const name = nonEmptyString(value, label, statePath);
+    if (name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+        throw new PackageStateError(statePath, `${label} must be one path segment`);
+    }
+    return name;
+}
+function commitId(value, label, statePath) {
+    const candidate = nonEmptyString(value, label, statePath);
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(candidate)) {
+        throw new PackageStateError(statePath, `${label} must be a 40- or 64-character lowercase commit ID`);
+    }
+    return candidate;
+}
+function parseCoordinates(value, label, statePath) {
+    if (value.host !== "pi" && value.host !== "claude") {
+        const hosts = PACKAGE_HOSTS.map((host) => JSON.stringify(host)).join(" or ");
+        throw new PackageStateError(statePath, `${label}.host must be ${hosts}`);
+    }
+    assertKeys(value, SELECTION_KEYS[value.host], label, statePath);
+    if (value.host === "pi") {
+        const root = sourceDirectory(value.root, `${label}.root`, statePath);
+        return {
+            coordinates: Object.freeze({ host: "pi", root }),
+            manifestPath: root === "" ? "package.json" : `${root}/package.json`,
+        };
+    }
+    const marketplaceRoot = sourceDirectory(value.marketplaceRoot, `${label}.marketplaceRoot`, statePath);
+    const name = pluginName(value.pluginName, `${label}.pluginName`, statePath);
+    return {
+        coordinates: Object.freeze({ host: "claude", marketplaceRoot, pluginName: name }),
+        manifestPath: marketplaceRoot === ""
+            ? ".claude-plugin/marketplace.json"
+            : `${marketplaceRoot}/.claude-plugin/marketplace.json`,
+    };
+}
+function parseVersionEvidence(value, label, statePath) {
+    if (!isRecord(value)) {
+        throw new PackageStateError(statePath, `${label} must be an object`);
+    }
+    if (value.kind === "manifest-version") {
+        assertKeys(value, ["kind", "version", "declaredBy"], label, statePath);
+        const version = nonEmptyString(value.version, `${label}.version`, statePath);
+        if (value.declaredBy !== "bundle" && value.declaredBy !== "marketplace-entry") {
+            throw new PackageStateError(statePath, `${label}.declaredBy must be "bundle" or "marketplace-entry"`);
+        }
+        return Object.freeze({ kind: "manifest-version", version, declaredBy: value.declaredBy });
+    }
+    if (value.kind === "git-commit") {
+        assertKeys(value, ["kind", "commit"], label, statePath);
+        return Object.freeze({ kind: "git-commit", commit: commitId(value.commit, `${label}.commit`, statePath) });
+    }
+    throw new PackageStateError(statePath, `${label}.kind must be "manifest-version" or "git-commit"`);
+}
+function parseSelection(value, label, statePath) {
+    if (!isRecord(value)) {
+        throw new PackageStateError(statePath, `${label} must be an object`);
+    }
+    const { coordinates, manifestPath } = parseCoordinates(value, label, statePath);
+    try {
+        // The manifest path is a probe, discarded after parsing. It reuses the one
+        // parser that owns Source canonicalization, ref safety, and the pin rules,
+        // and its containment rule rejects a root that escapes the Source.
+        const [parsed] = parseProjectManifest({
+            version: PROJECT_MANIFEST_VERSION,
+            skills: [{ source: value.source, path: manifestPath, version: value.version, hosts: [coordinates.host] }],
+        }, statePath).skills;
+        return Object.freeze({ ...coordinates, source: parsed.source, version: parsed.version });
+    }
+    catch (error) {
+        const field = coordinates.host === "pi" ? "root" : "marketplaceRoot";
+        const reason = error instanceof ProjectManifestError
+            ? error.reason.replace(/^skills\[0\]\.path/u, `${label}.${field}`).replace(/^skills\[0\]\./u, `${label}.`)
+            : error instanceof Error ? error.message : "the selection is invalid";
+        throw new PackageStateError(statePath, `${label} is invalid (${reason})`);
+    }
+}
+function parseInstalledPackage(value, index, statePath) {
+    const label = `packages[${index}]`;
+    if (!isRecord(value)) {
+        throw new PackageStateError(statePath, `${label} must be an object`);
+    }
+    assertKeys(value, ["selection", "installId", "lastDelegatedCommit", "verified", "verifiedAt"], label, statePath);
+    const selection = parseSelection(value.selection, `${label}.selection`, statePath);
+    const installId = nonEmptyString(value.installId, `${label}.installId`, statePath);
+    const lastDelegatedCommit = value.lastDelegatedCommit === undefined
+        ? undefined
+        : commitId(value.lastDelegatedCommit, `${label}.lastDelegatedCommit`, statePath);
+    const verified = value.verified === undefined
+        ? undefined
+        : parseVersionEvidence(value.verified, `${label}.verified`, statePath);
+    const verifiedAt = timestamp(value.verifiedAt, `${label}.verifiedAt`, statePath);
+    return Object.freeze({
+        selection,
+        installId,
+        ...(lastDelegatedCommit === undefined ? {} : { lastDelegatedCommit }),
+        ...(verified === undefined ? {} : { verified }),
+        verifiedAt,
+    });
+}
+function parseState(value, statePath) {
+    if (!isRecord(value)) {
+        throw new PackageStateError(statePath, "the root value must be an object");
+    }
+    assertKeys(value, ["version", "packages"], "the state", statePath);
+    if (value.version !== 1) {
+        throw new PackageStateError(statePath, "the state version is unsupported");
+    }
+    if (!Array.isArray(value.packages)) {
+        throw new PackageStateError(statePath, "packages must be an array");
+    }
+    const keys = new Set();
+    const packages = value.packages.map((item, index) => {
+        const record = parseInstalledPackage(item, index, statePath);
+        const key = selectionKey(record.selection);
+        if (keys.has(key)) {
+            throw new PackageStateError(statePath, `packages[${index}] duplicates another selection`);
+        }
+        keys.add(key);
+        return record;
+    });
+    packages.sort((left, right) => compareKeys(selectionKey(left.selection), selectionKey(right.selection)));
+    return Object.freeze({ version: 1, packages: Object.freeze(packages) });
+}
+function compareKeys(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function sameCoordinates(left, right) {
+    if (left.host === "pi" && right.host === "pi") {
+        return left.root === right.root;
+    }
+    if (left.host === "claude" && right.host === "claude") {
+        return left.marketplaceRoot === right.marketplaceRoot && left.pluginName === right.pluginName;
+    }
+    return false;
+}
+function applyChanges(state, changes) {
+    const verifiedAt = new Date().toISOString();
+    const records = new Map(state.packages.map((record) => [selectionKey(record.selection), record]));
+    let changed = false;
+    for (const change of changes) {
+        if (change.kind === "upsert") {
+            records.set(selectionKey(change.record.selection), Object.freeze({ ...change.record, verifiedAt }));
+            changed = true;
+        }
+        else if (records.delete(selectionKey(change.selection))) {
+            changed = true;
+        }
+    }
+    if (!changed) {
+        return { state, changed: false };
+    }
+    const packages = [...records.values()];
+    packages.sort((left, right) => compareKeys(selectionKey(left.selection), selectionKey(right.selection)));
+    return { state: Object.freeze({ version: 1, packages: Object.freeze(packages) }), changed: true };
+}
+function normalizeApprovalDigest(digest) {
+    if (typeof digest !== "string" || !APPROVAL_DIGEST.test(digest)) {
+        throw new PackageApprovalDigestError(digest);
+    }
+    return digest.toLowerCase();
+}
+function isApprovedReceipt(contents, digest) {
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        return false;
+    }
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (Object.keys(value).some((key) => key !== "version" && key !== "digest")) {
+        return false;
+    }
+    // The stored digest must agree with the filename, so a copied or renamed
+    // receipt cannot approve a declaration it never covered.
+    return value.version === 1 && value.digest === digest;
+}
+export function defaultPackageStateDirectory(environment = process.env, platform = process.platform, homeDirectory = homedir()) {
+    const pathApi = platform === "win32" ? path.win32 : path.posix;
+    return pathApi.dirname(defaultSourceStatePath(environment, platform, homeDirectory));
+}
+/** The one writer for `packages.json` and the approval receipts beside it. */
+export class PackageStateStore {
+    path;
+    approvalsDirectory;
+    constructor(stateDirectory = defaultPackageStateDirectory()) {
+        this.path = path.join(stateDirectory, "packages.json");
+        this.approvalsDirectory = path.join(stateDirectory, "package-approvals");
+    }
+    /** Recorded selections in selection-key order. A missing file is an empty list. */
+    async list() {
+        const release = await this.acquireLock();
+        try {
+            return (await this.loadUnlocked()).packages;
+        }
+        finally {
+            await release();
+        }
+    }
+    async find(selection) {
+        const key = selectionKey(this.normalizeSelection(selection));
+        return (await this.list()).find((record) => selectionKey(record.selection) === key);
+    }
+    /** Records whose selection carries these coordinates, for a plan's affected set. */
+    async findAffected(coordinates) {
+        return (await this.list()).filter((record) => sameCoordinates(record.selection, coordinates));
+    }
+    async upsert(record) {
+        const normalized = this.normalizeRecord(record);
+        await this.update((state) => applyChanges(state, [{ kind: "upsert", record: normalized }]));
+    }
+    async drop(selection) {
+        const normalized = this.normalizeSelection(selection);
+        await this.update((state) => applyChanges(state, [{ kind: "drop", selection: normalized }]));
+    }
+    /**
+     * Applies keyed changes in one locked window, so a multi-record outcome commits
+     * at once. The list is decided before the lock, so a concurrent writer for the
+     * same selection is last-writer-wins rather than merged.
+     */
+    async reconcile(changes) {
+        if (changes.length === 0) {
+            return;
+        }
+        const normalized = changes.map((change) => change.kind === "upsert"
+            ? { kind: "upsert", record: this.normalizeRecord(change.record) }
+            : { kind: "drop", selection: this.normalizeSelection(change.selection) });
+        await this.update((state) => applyChanges(state, normalized));
+    }
+    /** Writes the receipt for a digest that `packageApprovalDigest` already produced. */
+    async approve(digest) {
+        const approvalDigest = normalizeApprovalDigest(digest);
+        const receipt = `${JSON.stringify({ version: 1, digest: approvalDigest }, null, 2)}\n`;
+        await mkdir(this.approvalsDirectory, { recursive: true, mode: 0o700 });
+        await chmod(this.approvalsDirectory, 0o700);
+        await writeFileAtomically(path.join(this.approvalsDirectory, `${approvalDigest}.json`), receipt, { mode: 0o600 });
+    }
+    /** Reads a receipt. A missing, malformed, or mismatched receipt needs approval again. */
+    async approvalStatus(digest) {
+        const approvalDigest = normalizeApprovalDigest(digest);
+        let contents;
+        try {
+            contents = await readFile(path.join(this.approvalsDirectory, `${approvalDigest}.json`), "utf8");
+        }
+        catch (error) {
+            if (isMissingFile(error)) {
+                return "needs approval";
+            }
+            throw error;
+        }
+        return isApprovedReceipt(contents, approvalDigest) ? "approved" : "needs approval";
+    }
+    normalizeSelection(selection) {
+        // One canonical spelling per Source, so the key derived here matches the key
+        // derived again when the same record is parsed back off disk.
+        return parseSelection(selection, "selection", this.path);
+    }
+    normalizeRecord(record) {
+        return { ...record, selection: this.normalizeSelection(record.selection) };
+    }
+    async update(mutate) {
+        const release = await this.acquireLock();
+        try {
+            const update = mutate(await this.loadUnlocked());
+            if (!update.changed) {
+                return;
+            }
+            await this.saveUnlocked(update.state);
+        }
+        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 PackageStateError(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 });
+        await writeFileAtomically(this.path, `${JSON.stringify(normalized, null, 2)}\n`, { 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 PackageStateLockError(this.path);
+                }
+                await delay(LOCK_RETRY_MS);
+            }
+        }
+    }
+}
+function isMissingFile(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isAlreadyExists(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}

package/dist/src/process-runner.js

@@ -12,6 +12,12 @@ export function runProcess(command, args, options = {}) {
         let stderr = "";
         let stderrBytes = 0;
         let outputTooLarge = false;
+        let timedOut = false;
+        const timeout = options.timeoutMs === undefined ? undefined : setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, options.timeoutMs);
+        timeout?.unref();
         child.stdout?.on("data", (chunk) => {
             stdoutBytes += chunk.length;
             if (options.maxOutputBytes !== undefined && stdoutBytes > options.maxOutputBytes) {
@@ -35,7 +41,9 @@ export function runProcess(command, args, options = {}) {
         });
         child.on("error", reject);
         child.on("close", (code, signal) => {
-            resolve({ code, signal, stdout: Buffer.concat(stdout), stderr, outputTooLarge });
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            resolve({ code, signal, stdout: Buffer.concat(stdout), stderr, outputTooLarge, ...(timedOut ? { timedOut: true } : {}) });
         });
     });
 }

package/dist/src/profile-cli.js

@@ -3,11 +3,15 @@ import { buildProfileExport, requireProfileExportSelection, writeProfileExport }
 import { applyProfileImport, buildProfileImport } from "./profile-import.js";
 import { serializeProfile } from "./profile.js";
 import { CliUsageError } from "./usage-error.js";
-export const EXPORT_USAGE = "agent-depot export [--out <file>] [--no-sources] [--no-skills] [--no-apps] [--source <id|url>...] [--skill <path|name>...] [--app <name>...]";
-export const IMPORT_USAGE = "agent-depot import <file> [--yes] [--no-sources] [--no-skills] [--no-apps] [--source <id|url>...] [--skill <path|name>...] [--app <name>...]";
-export async function runProfileExport(values, operations, apps, output, diagnostic, homeDirectory) {
+export const EXPORT_USAGE = "agent-depot export [--out <file>] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
+export const IMPORT_USAGE = "agent-depot import <file> [--yes] [--no-sources] [--no-skills] [--no-apps] [--no-packages] [--source <id|url>...] [--skill <path|name>...] [--app <name>...] [--package <selection>...]";
+export async function runProfileExport(values, operations, apps, output, diagnostic, homeDirectory, packageOperations) {
     const { filters, out } = parseProfileOptions(values, false);
-    const plan = await buildProfileExport(operations, apps, { ...filters, homeDirectory });
+    const plan = await buildProfileExport(operations, apps, {
+        ...filters,
+        homeDirectory,
+        ...(packageOperations === undefined ? {} : { packageOperations }),
+    });
     for (const line of plan.preview)
         diagnostic(line);
     requireProfileExportSelection(plan.profile);
@@ -21,8 +25,8 @@ export async function runProfileExport(values, operations, apps, output, diagnos
     return 0;
 }
 function parseProfileOptions(values, importing) {
-    const sources = [], skills = [], appNames = [];
-    const filters = { sources, skills, apps: appNames };
+    const sources = [], skills = [], appNames = [], packageNames = [];
+    const filters = { sources, skills, apps: appNames, packages: packageNames };
     let out;
     let confirmed = false;
     for (let index = 0; index < values.length; index++) {
@@ -38,7 +42,9 @@ function parseProfileOptions(values, importing) {
             filters.noSkills = true;
         else if (option === "--no-apps")
             filters.noApps = true;
-        else if (["--out", "--source", "--skill", "--app"].includes(option)) {
+        else if (option === "--no-packages")
+            filters.noPackages = true;
+        else if (["--out", "--source", "--skill", "--app", "--package"].includes(option)) {
             const value = values[++index];
             if (!value || value.startsWith("--"))
                 throw new CliUsageError(`${option} requires a value`);
@@ -50,7 +56,7 @@ function parseProfileOptions(values, importing) {
                 out = value;
             }
             else {
-                const names = option === "--source" ? sources : option === "--skill" ? skills : appNames;
+                const names = option === "--source" ? sources : option === "--skill" ? skills : option === "--app" ? appNames : packageNames;
                 if (names.includes(value))
                     throw new CliUsageError(`Duplicate ${option} ${JSON.stringify(value)}`);
                 names.push(value);
@@ -74,7 +80,7 @@ export async function runProfileImport(values, operations, apps, output, environ
     catch (error) {
         throw new Error(`${file}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
     }
-    const plan = await buildProfileImport(input, operations, apps, filters);
+    const plan = await buildProfileImport(input, operations, apps, filters, environment.packageOperations);
     for (const line of plan.preview)
         output(line);
     if (!confirmed) {

package/dist/src/profile-export.js

@@ -2,8 +2,10 @@ import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { loadAppOwnedSkillFilter } from "./app-owned-skills.js";
 import { sourceIdForUrl } from "./git-source.js";
+import { bundleRoot, describeCoordinates } from "./package-model.js";
 import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
 import { parseProfile, PROFILE_FORMAT, serializeProfile } from "./profile.js";
+import { formatVersionPolicy } from "./skill-install.js";
 import { scanUserGlobalSkillInventory } from "./user-global-skill-inventory.js";
 export function selectProfileItems(items, requested, disabled, names, block) {
     if (disabled && requested?.length)
@@ -14,6 +16,24 @@ export function selectProfileItems(items, requested, disabled, names, block) {
     }
     return disabled ? [] : items.filter(item => !requested?.length || names(item).some(name => requested.includes(name)));
 }
+/** The Package identities a `--package` filter accepts, matching `describeCoordinates`. */
+export function packageFilterNames(selection) {
+    const root = bundleRoot(selection);
+    const names = [describeCoordinates(selection)];
+    if (root !== "") {
+        names.push(root);
+        const basename = path.posix.basename(root);
+        if (basename !== root)
+            names.push(basename);
+    }
+    if (selection.host === "claude")
+        names.push(selection.pluginName);
+    return names;
+}
+/** One Package line, shared by the export preview and the import plan label. */
+export function describeProfilePackage(selection) {
+    return `Package ${describeCoordinates(selection)} (${formatVersionPolicy(selection.version)})`;
+}
 function validateOne(block, item) {
     const profile = parseProfile({ format: PROFILE_FORMAT, agentDepotVersion: AGENT_DEPOT_PACKAGE_VERSION,
         sources: [], skills: [], apps: [], [block]: [item] });
@@ -34,6 +54,11 @@ export async function buildProfileExport(operations, apps, options = {}) {
     const allInstallations = await operations.listUserGlobalInstallations();
     const installations = selectProfileItems(allInstallations, options.skills, options.noSkills, skill => [skill.path, path.posix.basename(skill.path)], "skills");
     const entries = selectProfileItems(await apps.load(), options.apps, options.noApps, entry => [entry.recipe?.name ?? path.basename(entry.file)], "apps");
+    const packageRecords = options.packageOperations === undefined ? [] : await options.packageOperations.list();
+    if (options.packageOperations === undefined && options.packages?.length) {
+        throw new Error("Profile export requires Package operations to select Packages");
+    }
+    const selectedPackages = selectProfileItems(packageRecords, options.packages, options.noPackages, record => packageFilterNames(record.selection), "packages");
     const owned = await loadAppOwnedSkillFilter({ appEnvironment: { recipesDirectory: apps.directory },
         reportWarning: warn });
     const portableSources = [];
@@ -79,6 +104,15 @@ export async function buildProfileExport(operations, apps, options = {}) {
             exclude("apps", `App recipe ${path.basename(entry.file)}`, error instanceof Error ? error.message : String(error));
         }
     }
+    const packages = [];
+    for (const record of selectedPackages) {
+        try {
+            packages.push(validateOne("packages", record.selection));
+        }
+        catch (error) {
+            exclude("packages", describeProfilePackage(record.selection), `not portable (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
     if (!options.noSkills) {
         const inventory = await scanUserGlobalSkillInventory({
             homeDirectory: options.homeDirectory, managedInstallations: allInstallations,
@@ -89,7 +123,7 @@ export async function buildProfileExport(operations, apps, options = {}) {
         }
     }
     const profile = parseProfile({ format: PROFILE_FORMAT, agentDepotVersion: AGENT_DEPOT_PACKAGE_VERSION,
-        sources: portableSources, skills, apps: recipes });
+        sources: portableSources, skills, apps: recipes, packages });
     return {
         profile,
         exclusions: diagnostics.filter((item) => "block" in item),
@@ -98,13 +132,13 @@ export async function buildProfileExport(operations, apps, options = {}) {
     };
 }
 function sourceWarnings(profile) {
-    return profile.skills.flatMap(skill => {
-        const identity = skill.source;
-        if (identity.kind === "external" && "url" in identity && !profile.sources.some(source => source.url === identity.url)) {
-            return [{ kind: "source", message: `WARNING: Skill ${skill.path} references Source ${identity.url} not included in profile` }];
-        }
-        return [];
-    });
+    const missing = (source, label) => source.kind === "external" && "url" in source && !profile.sources.some(candidate => candidate.url === source.url)
+        ? [{ kind: "source", message: `WARNING: ${label} references Source ${source.url} not included in profile` }]
+        : [];
+    return [
+        ...profile.skills.flatMap(skill => missing(skill.source, `Skill ${skill.path}`)),
+        ...profile.packages.flatMap(selection => missing(selection.source, describeProfilePackage(selection))),
+    ];
 }
 /** Shared preview for a frontend-selected subset; Source warnings are recomputed. */
 export function profileExportPreview(profile, diagnostics = []) {
@@ -112,12 +146,13 @@ export function profileExportPreview(profile, diagnostics = []) {
         ...profile.sources.map(source => `Source ${sourceIdForUrl(source.url)} ${source.url} (included: ${source.included})`),
         ...profile.skills.map(skill => `Skill ${skill.path} [${skill.hosts.join(", ")}] (${skill.version.policy})`),
         ...profile.apps.map(recipe => `App recipe ${recipe.name} (${recipe.platform ?? "all platforms"}; no approval)`),
+        ...profile.packages.map(selection => `${describeProfilePackage(selection)}; no receipt, no installed state`),
         ...diagnostics.flatMap(item => "block" in item ? [`Excluded ${item.label}: ${item.reason}`] : item.kind === "load" ? [item.message] : []),
         ...sourceWarnings(profile).map(warning => warning.message)];
 }
 /** Empty profiles are valid to parse, but are not useful export artifacts. */
 export function requireProfileExportSelection(profile) {
-    if (!profile.sources.length && !profile.skills.length && !profile.apps.length) {
+    if (!profile.sources.length && !profile.skills.length && !profile.apps.length && !profile.packages.length) {
         throw new Error("Nothing selected; nothing written.");
     }
 }