@iseoane/agent-depot 0.2.1 → 0.4.0

package/dist/src/app-recipes.js

@@ -0,0 +1,116 @@
+import { parsePortableInstallationMethod, PROJECT_HOSTS, } from "./project-manifest.js";
+export const APP_GITHUB_PATTERN = "^[\\w-][\\w.-]*/[\\w-][\\w.-]*$";
+export const APP_NPM_PATTERN = "^(?:@[a-z0-9~-][a-z0-9._~-]*/)?[a-z0-9~-][a-z0-9._~-]*$";
+export const APP_SKILL_PATTERN = "^(?!\\*+$)(?!\\s*$)[^/\\\\\\u0000]+$";
+function object(value, keys, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${field}: expected an object`);
+    }
+    const record = value;
+    const unsupported = Object.keys(record).find((key) => !keys.includes(key));
+    if (unsupported !== undefined)
+        throw new Error(`${field}.${unsupported}: unsupported recipe field`);
+    return record;
+}
+function text(value, field) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${field}: expected non-empty text`);
+    return value;
+}
+function argv(value, field) {
+    return parsePortableInstallationMethod({ kind: "command", argv: value }, { label: `${field}:` }).argv;
+}
+function step(value, field) {
+    const item = object(value, ["argv", "manual"], field);
+    if (item.argv === undefined && item.manual === undefined) {
+        throw new Error(`${field}: step needs argv or manual`);
+    }
+    return {
+        ...(item.argv === undefined ? {} : { argv: argv(item.argv, `${field}.argv`) }),
+        ...(item.manual === undefined ? {} : { manual: text(item.manual, `${field}.manual`) }),
+    };
+}
+function version(value, field) {
+    const item = object(value, ["argv", "pattern"], field);
+    const pattern = text(item.pattern, `${field}.pattern`);
+    try {
+        new RegExp(pattern);
+    }
+    catch (error) {
+        throw new Error(`${field}.pattern: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Count captures while ignoring escapes, character classes and non-capturing/lookaround groups.
+    let captures = 0;
+    let inClass = false;
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (pattern[i] === "[")
+            inClass = true;
+        if (pattern[i] === "]")
+            inClass = false;
+        const namedCapture = /^\?<[^=!]/u.test(pattern.slice(i + 1));
+        if (!inClass && pattern[i] === "(" && (pattern[i + 1] !== "?" || namedCapture))
+            captures++;
+    }
+    if (captures !== 1)
+        throw new Error(`${field}.pattern: expected exactly one capture group`);
+    return { argv: argv(item.argv, `${field}.argv`), pattern };
+}
+function hosts(value, field) {
+    return Object.fromEntries(Object.entries(object(value, PROJECT_HOSTS, field)).map(([host, item]) => [host, step(item, `${field}.${host}`)]));
+}
+function latest(value) {
+    const item = object(value, ["github", "npm", "argv", "pattern"], "latest");
+    if (Object.keys(item).length === 1 && item.github !== undefined) {
+        const github = text(item.github, "latest.github");
+        if (!new RegExp(APP_GITHUB_PATTERN).test(github))
+            throw new Error("latest.github: expected owner/repo");
+        return { github };
+    }
+    if (Object.keys(item).length === 1 && item.npm !== undefined) {
+        const npm = text(item.npm, "latest.npm");
+        if (npm.length > 214 || !new RegExp(APP_NPM_PATTERN).test(npm) || ["node_modules", "favicon.ico"].includes(npm)) {
+            throw new Error("latest.npm: expected a valid npm package name");
+        }
+        return { npm };
+    }
+    return version(item, "latest");
+}
+export function parseAppRecipe(value) {
+    const item = object(value, [
+        "name", "platform", "homepage", "install", "update", "uninstall", "version",
+        "latest", "setup", "teardown", "skills",
+    ], "recipe");
+    if (item.platform !== undefined && (typeof item.platform !== "string" || !["linux", "windows", "darwin"].includes(item.platform))) {
+        throw new Error("platform: unsupported platform");
+    }
+    let skills;
+    if (item.skills !== undefined) {
+        if (!Array.isArray(item.skills))
+            throw new Error("skills: expected a list");
+        skills = [];
+        for (const [index, skill] of item.skills.entries()) {
+            const pattern = text(skill, `skills[${index}]`);
+            if (!new RegExp(APP_SKILL_PATTERN, "u").test(pattern)) {
+                throw new Error(`skills[${index}]: expected a non-empty name pattern without path separators or NUL, and not only stars`);
+            }
+            skills.push(pattern);
+        }
+    }
+    return {
+        name: text(item.name, "name"),
+        install: step(item.install, "install"),
+        update: step(item.update, "update"),
+        uninstall: step(item.uninstall, "uninstall"),
+        version: version(item.version, "version"),
+        ...(item.platform === undefined ? {} : { platform: item.platform }),
+        ...(item.homepage === undefined ? {} : { homepage: text(item.homepage, "homepage") }),
+        ...(item.latest === undefined ? {} : { latest: latest(item.latest) }),
+        ...(item.setup === undefined ? {} : { setup: hosts(item.setup, "setup") }),
+        ...(item.teardown === undefined ? {} : { teardown: hosts(item.teardown, "teardown") }),
+        ...(skills === undefined ? {} : { skills }),
+    };
+}

package/dist/src/app-schema.js

@@ -0,0 +1,45 @@
+import { APP_GITHUB_PATTERN, APP_NPM_PATTERN, APP_SKILL_PATTERN } from "./app-recipes.js";
+import { PROJECT_HOSTS } from "./project-manifest.js";
+const argv = {
+    type: "array", minItems: 1, items: { type: "string", minLength: 1 },
+    description: "Bare no-shell executable and arguments; user-method safety rules also apply.",
+};
+const text = { type: "string", minLength: 1 };
+const step = {
+    type: "object", additionalProperties: false,
+    properties: { argv, manual: text },
+    anyOf: [{ required: ["argv"] }, { required: ["manual"] }],
+};
+const version = {
+    type: "object", additionalProperties: false, required: ["argv", "pattern"],
+    properties: {
+        argv, pattern: { ...text, description: "Valid JavaScript regex with exactly one capture group." },
+    },
+};
+const hosts = {
+    type: "object", additionalProperties: false,
+    properties: Object.fromEntries(PROJECT_HOSTS.map((host) => [host, step])),
+};
+export const APP_RECIPE_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "Agent Depot App recipe", type: "object", additionalProperties: false,
+    required: ["name", "install", "update", "uninstall", "version"],
+    properties: {
+        name: text, platform: { enum: ["linux", "windows", "darwin"] }, homepage: text,
+        install: step, update: step, uninstall: step, version,
+        latest: {
+            oneOf: [
+                version,
+                {
+                    type: "object", additionalProperties: false, required: ["github"],
+                    properties: { github: { ...text, pattern: APP_GITHUB_PATTERN } },
+                },
+                {
+                    type: "object", additionalProperties: false, required: ["npm"],
+                    properties: { npm: { ...text, pattern: APP_NPM_PATTERN, maxLength: 214, not: { enum: ["node_modules", "favicon.ico"] } } },
+                },
+            ],
+        },
+        setup: hosts, teardown: hosts, skills: { type: "array", items: { ...text, pattern: APP_SKILL_PATTERN } },
+    },
+};

package/dist/src/app-version.js

@@ -0,0 +1,46 @@
+/** Strict SemVer ordering; unlike Skill's permissive comparator, opaque inputs stay distinguishable. */
+export function compareAppVersions(left, right) {
+    const parse = (value) => {
+        const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/u.exec(normalizeAppVersion(value));
+        if (!match)
+            return undefined;
+        const pre = match[4]?.split(".") ?? [];
+        if (pre.some(part => /^\d+$/u.test(part) && /^0\d/u.test(part)))
+            return undefined;
+        return { core: match.slice(1, 4).map(part => BigInt(part)), pre };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (!a || !b)
+        return undefined;
+    for (let index = 0; index < 3; index++) {
+        if (a.core[index] !== b.core[index])
+            return a.core[index] < b.core[index] ? -1 : 1;
+    }
+    if (!a.pre.length || !b.pre.length)
+        return Math.sign(b.pre.length - a.pre.length);
+    for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index++) {
+        const x = a.pre[index];
+        const y = b.pre[index];
+        if (x === y)
+            continue;
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const numericX = /^\d+$/u.test(x);
+        const numericY = /^\d+$/u.test(y);
+        if (numericX && numericY)
+            return BigInt(x) < BigInt(y) ? -1 : 1;
+        if (numericX !== numericY)
+            return numericX ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+export function normalizeAppVersion(version) {
+    return version.replace(/^v(?=\d)/u, "");
+}
+export function sameAppVersion(left, right) {
+    return compareAppVersions(left, right) === 0 || normalizeAppVersion(left) === normalizeAppVersion(right);
+}

package/dist/src/atomic-file.js

@@ -0,0 +1,26 @@
+import { randomUUID } from "node:crypto";
+import { rename, unlink, writeFile } from "node:fs/promises";
+/** Write a unique temporary sibling, then publish it with rename. */
+export async function writeFileAtomically(file, contents, options = {}) {
+    const temporaryPath = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx", mode: options.mode });
+        try {
+            await rename(temporaryPath, file);
+        }
+        catch (error) {
+            const code = error.code;
+            if (!options.allowLockedReplaceFallback || !["EEXIST", "EPERM", "ENOTEMPTY"].includes(code ?? "")) {
+                throw error;
+            }
+            // Source state holds its read-modify-write lock while using this Windows fallback.
+            await writeFile(file, contents, "utf8");
+        }
+    }
+    finally {
+        await unlink(temporaryPath).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+    }
+}

package/dist/src/cli.js

@@ -3,6 +3,9 @@ import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
+import { checkAppUpdates, createAppOperations } from "./app-flow.js";
+import { describeAppResult, describeManualCompletion, runAppCommand } from "./app-cli.js";
+import { EXPORT_USAGE, IMPORT_USAGE, runProfileExport, runProfileImport } from "./profile-cli.js";
 import { pathsOverlap } from "./path-safety.js";
 import { skillTreeBaseline } from "./skill-discovery.js";
 import { BuiltInSourceError, createSourceOperations, resolveProjectSource, SourceMetadataError, SourceNotFoundError, } from "./sources.js";
@@ -28,11 +31,19 @@ const USAGE = [
     "  agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--yes] [--confirm-additional-host]",
     "  agent-depot install --scope project --manifest --portable-v1 [--yes] [--confirm-additional-host]",
     "  agent-depot update check --scope <project|user-global>",
-    "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>...) [--yes] [--confirm-path <relative-path>...]",
+    "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>... | --app <name>...) [--yes] [--confirm-path <relative-path>...]",
+    "    Apps run after Skills; --all --scope project skips Apps.",
     "  agent-depot skill remove <id|path>... [--yes]",
     "  agent-depot skill remove <id|path> --host <host>... [--yes]",
     "  agent-depot skill host add <id|path> --host <host>... [--yes] [--confirm-additional-host]",
     "  agent-depot uninstall [--skills] [--unmanaged-skill <exact-global-path>...] [--data] [--cli] [--yes]",
+    "  agent-depot app schema|list",
+    "  agent-depot app validate <file>...",
+    "  agent-depot app approve <name> [--yes]",
+    "  agent-depot app install|update|uninstall <name> [--yes] [--manual-done]",
+    "  agent-depot app uninstall <name> --forget [--yes]",
+    `  ${EXPORT_USAGE}`,
+    `  ${IMPORT_USAGE}`,
     "  agent-depot tui",
     "  agent-depot --version",
 ].join("\n");
@@ -60,6 +71,9 @@ const SOURCE_SUBCOMMANDS = new Map([
     ["migrate", (values, { operations, dependencies, output }) => runSourceMigration(values, operations, dependencies, output)],
 ]);
 const COMMANDS = new Map([
+    ["import", (values, { operations, dependencies, output }) => runProfileImport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies)],
+    ["export", (values, { operations, dependencies, output }) => runProfileExport(values, operations, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output, dependencies.stderr ?? (line => console.error(line)), dependencies.homeDirectory)],
+    ["app", (values, { dependencies, output }) => runAppCommand(values, dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory }), output)],
     ["install", async (values, { operations, dependencies, output }) => {
             await runInstall(values, operations, dependencies, output);
             return 0;
@@ -669,21 +683,73 @@ async function runUninstall(argv, operations, dependencies, output) {
 }
 async function runUpdate(argv, operations, dependencies, output) {
     const options = parseUpdateOptions(argv);
-    const { assessment, installed, context } = await loadUpdates({
-        scope: options.scope,
-        operations,
-        ...(dependencies.homeDirectory === undefined ? {} : { homeDirectory: dependencies.homeDirectory }),
-        ...(dependencies.projectRoot === undefined ? {} : { projectRoot: dependencies.projectRoot }),
-        ...(dependencies.sourceAccess === undefined ? {} : { sourceAccess: dependencies.sourceAccess }),
-        ...(dependencies.projectManifestStore === undefined ? {} : { projectManifestStore: dependencies.projectManifestStore }),
-        ...(dependencies.installationOptions?.fileSystem === undefined ? {} : { installationFileSystem: dependencies.installationOptions.fileSystem }),
-    });
-    const userGlobalInventory = options.action === "check" && options.scope === "user-global"
-        ? await scanUserGlobalSkillInventory({ homeDirectory: context.projectRoot, managedInstallations: installed })
-        : undefined;
-    outputUpdateAssessment(assessment, options.scope, output, userGlobalInventory);
+    const apps = dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory });
+    let appUpdates = [];
+    let appCheckFailed = false;
+    if (options.scope === "user-global") {
+        try {
+            appUpdates = await checkAppUpdates(apps);
+        }
+        catch (error) {
+            appCheckFailed = true;
+            output(`Error (Apps): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    let loaded;
+    try {
+        loaded = await loadUpdates({
+            scope: options.scope,
+            operations,
+            ...(dependencies.homeDirectory === undefined ? {} : { homeDirectory: dependencies.homeDirectory }),
+            ...(dependencies.projectRoot === undefined ? {} : { projectRoot: dependencies.projectRoot }),
+            ...(dependencies.sourceAccess === undefined ? {} : { sourceAccess: dependencies.sourceAccess }),
+            ...(dependencies.projectManifestStore === undefined ? {} : { projectManifestStore: dependencies.projectManifestStore }),
+            ...(dependencies.installationOptions?.fileSystem === undefined ? {} : { installationFileSystem: dependencies.installationOptions.fileSystem }),
+        });
+    }
+    catch (error) {
+        output(`Error (Skills, ${options.scope}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (loaded) {
+        const { assessment, installed, context } = loaded;
+        const userGlobalInventory = options.action === "check" && options.scope === "user-global"
+            ? await scanUserGlobalSkillInventory({ homeDirectory: context.projectRoot, managedInstallations: installed, reportWarning: output })
+            : undefined;
+        outputUpdateAssessment(assessment, options.scope, output, userGlobalInventory);
+    }
+    for (const item of appUpdates) {
+        output(`App ${item.entry.recipe?.name ?? item.entry.file}: ${item.status}; installed ${item.installedVersion ?? "unknown"}; latest ${item.latestVersion ?? "unknown"}${item.reason ? `; ${item.reason}` : ""}`);
+    }
+    if (!loaded)
+        return 1;
     if (options.action === "check") {
-        return 0;
+        return appCheckFailed ? 1 : 0;
+    }
+    const { assessment, context } = loaded;
+    const selectedApps = options.all ? appUpdates.filter(item => item.status === "update available")
+        : options.requestedApps.map(name => {
+            const matches = appUpdates.filter(item => item.entry.recipe?.name === name);
+            if (matches.length !== 1 || matches[0].status !== "update available") {
+                throw new CliUsageError(`App ${JSON.stringify(name)} is unknown or not updateable`);
+            }
+            return matches[0];
+        });
+    const appPlans = [];
+    let appFailed = appCheckFailed ? 1 : 0;
+    for (const item of selectedApps) {
+        try {
+            const plan = await apps.planLifecycle(item.entry, "update", undefined, item);
+            output(`Preview: update App ${item.entry.recipe.name}: ${JSON.stringify(plan.argv ?? [])}; executable ${plan.executable ?? "unresolved"}; cwd ${plan.cwd}; environment ${plan.environment}`);
+            if (plan.warning)
+                output(plan.warning);
+            if (plan.manual)
+                output(`Manual (never executed): ${plan.manual}`);
+            appPlans.push(plan);
+        }
+        catch (error) {
+            appFailed++;
+            output(`App ${item.entry.recipe.name}: preview failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     const selected = selectUpdateCandidates(assessment, options);
     const { plans, failures: previewFailures, nonCanonicalPaths } = await previewUpdateCandidates(selected, context);
@@ -717,10 +783,32 @@ async function runUpdate(argv, operations, dependencies, output) {
     for (const item of result.failed) {
         output(`Failed Skill ${JSON.stringify(item.selection.path)} (${item.id}): ${item.error ?? "unknown error"}`);
     }
-    output(`Update summary: ${result.updated.length} updated, ${result.failed.length} failed`);
-    return result.failed.length === 0 ? 0 : 1;
+    let appUpdated = 0;
+    for (const plan of appPlans) {
+        try {
+            const outcome = await apps.executeLifecycle(plan, true);
+            output(`App ${plan.entry.recipe.name}: ${describeAppResult(outcome)}${outcome.reason ? `: ${outcome.reason}` : ""}`);
+            if (outcome.status === "installed")
+                appUpdated++;
+            else {
+                appFailed++;
+                if (outcome.manual) {
+                    output(`Manual (never executed): ${outcome.manual}`);
+                    output(describeManualCompletion(plan));
+                }
+            }
+        }
+        catch (error) {
+            appFailed++;
+            output(`App ${plan.entry.recipe.name}: failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    output(`Update summary: ${result.updated.length + appUpdated} updated, ${result.failed.length + appFailed} failed`);
+    return result.failed.length + appFailed === 0 ? 0 : 1;
 }
 function selectUpdateCandidates(assessment, options) {
+    if (!options.all && !options.requested.length)
+        return [];
     const requested = options.all
         ? "all"
         : resolveUpdateSelectionIds(assessment, options.requested);
@@ -742,6 +830,7 @@ function parseUpdateOptions(argv) {
     let all = false;
     let confirmed = false;
     const requested = [];
+    const requestedApps = [];
     const confirmedPaths = [];
     for (let index = 1; index < argv.length; index += 1) {
         switch (argv[index]) {
@@ -754,6 +843,9 @@ function parseUpdateOptions(argv) {
             case "--all":
                 all = true;
                 break;
+            case "--app":
+                requestedApps.push(requireOptionValue(argv, ++index, "--app"));
+                break;
             case "--skill":
                 requested.push(requireOptionValue(argv, ++index, "--skill"));
                 break;
@@ -767,12 +859,16 @@ function parseUpdateOptions(argv) {
     if (scope !== "project" && scope !== "user-global") {
         throw new CliUsageError("Update scope must be explicit: use --scope project or --scope user-global");
     }
-    if (action === "check" && (all || requested.length > 0 || confirmed || confirmedPaths.length > 0)) {
+    if (action === "check" && (all || requested.length > 0 || requestedApps.length > 0 || confirmed || confirmedPaths.length > 0)) {
         throw new CliUsageError("update check only accepts --scope; use update apply to select and apply updates");
     }
-    if (action === "apply" && (all === (requested.length > 0))) {
-        throw new CliUsageError("update apply requires exactly one selection mode: --all or one or more --skill values");
+    if (action === "apply" && (all === (requested.length + requestedApps.length > 0))) {
+        throw new CliUsageError("update apply requires exactly one selection mode: --all or one or more --skill/--app values");
     }
+    if (requestedApps.length && scope !== "user-global")
+        throw new CliUsageError("Apps are user-global only");
+    if (new Set(requestedApps).size !== requestedApps.length)
+        throw new CliUsageError("Duplicate App selection");
     if (scope === "user-global" && confirmedPaths.length > 0) {
         throw new CliUsageError("--confirm-path only applies to --scope project");
     }
@@ -781,6 +877,7 @@ function parseUpdateOptions(argv) {
         scope: scope,
         all,
         requested: Object.freeze(requested),
+        requestedApps: Object.freeze(requestedApps),
         confirmed,
         confirmedPaths: Object.freeze(confirmedPaths),
     };

package/dist/src/process-runner.js

@@ -10,6 +10,7 @@ export function runProcess(command, args, options = {}) {
         const stdout = [];
         let stdoutBytes = 0;
         let stderr = "";
+        let stderrBytes = 0;
         let outputTooLarge = false;
         child.stdout?.on("data", (chunk) => {
             stdoutBytes += chunk.length;
@@ -22,7 +23,15 @@ export function runProcess(command, args, options = {}) {
         });
         child.stderr?.setEncoding("utf8");
         child.stderr?.on("data", (chunk) => {
-            stderr += chunk;
+            const bytes = Buffer.from(chunk);
+            const remaining = options.maxStderrBytes === undefined
+                ? bytes.length : Math.max(0, options.maxStderrBytes - stderrBytes);
+            stderrBytes += bytes.length;
+            stderr += bytes.subarray(0, remaining).toString("utf8");
+            if (options.maxStderrBytes !== undefined && stderrBytes > options.maxStderrBytes) {
+                outputTooLarge = true;
+                child.kill();
+            }
         });
         child.on("error", reject);
         child.on("close", (code, signal) => {

package/dist/src/profile-cli.js

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import { buildProfileExport, requireProfileExportSelection, writeProfileExport } from "./profile-export.js";
+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) {
+    const { filters, out } = parseProfileOptions(values, false);
+    const plan = await buildProfileExport(operations, apps, { ...filters, homeDirectory });
+    for (const line of plan.preview)
+        diagnostic(line);
+    requireProfileExportSelection(plan.profile);
+    const content = serializeProfile(plan.profile);
+    if (out === undefined)
+        output(content.trimEnd());
+    else {
+        await writeProfileExport(out, plan.profile);
+        diagnostic(`Exported profile to ${out}`);
+    }
+    return 0;
+}
+function parseProfileOptions(values, importing) {
+    const sources = [], skills = [], appNames = [];
+    const filters = { sources, skills, apps: appNames };
+    let out;
+    let confirmed = false;
+    for (let index = 0; index < values.length; index++) {
+        const option = values[index];
+        if (option === "--yes" && importing) {
+            if (confirmed)
+                throw new CliUsageError("Duplicate --yes");
+            confirmed = true;
+        }
+        else if (option === "--no-sources")
+            filters.noSources = true;
+        else if (option === "--no-skills")
+            filters.noSkills = true;
+        else if (option === "--no-apps")
+            filters.noApps = true;
+        else if (["--out", "--source", "--skill", "--app"].includes(option)) {
+            const value = values[++index];
+            if (!value || value.startsWith("--"))
+                throw new CliUsageError(`${option} requires a value`);
+            if (option === "--out") {
+                if (importing)
+                    throw new CliUsageError(`Usage: ${IMPORT_USAGE}`);
+                if (out !== undefined)
+                    throw new CliUsageError("Duplicate --out");
+                out = value;
+            }
+            else {
+                const names = option === "--source" ? sources : option === "--skill" ? skills : appNames;
+                if (names.includes(value))
+                    throw new CliUsageError(`Duplicate ${option} ${JSON.stringify(value)}`);
+                names.push(value);
+            }
+        }
+        else
+            throw new CliUsageError(`Usage: ${importing ? IMPORT_USAGE : EXPORT_USAGE}`);
+    }
+    return { filters, out, confirmed };
+}
+export async function runProfileImport(values, operations, apps, output, environment = {}) {
+    const file = values[0];
+    if (!file || file.startsWith("--"))
+        throw new CliUsageError(`Usage: ${IMPORT_USAGE}`);
+    const { filters, confirmed } = parseProfileOptions(values.slice(1), true);
+    const content = await readFile(file, "utf8");
+    let input;
+    try {
+        input = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`${file}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const plan = await buildProfileImport(input, operations, apps, filters);
+    for (const line of plan.preview)
+        output(line);
+    if (!confirmed) {
+        output("Import not confirmed; rerun with --yes. Nothing was written.");
+        return 0;
+    }
+    const results = await applyProfileImport(plan, operations, apps, confirmed, output, environment);
+    for (const result of results)
+        output(`${result.status}: ${result.item.label}${result.detail ? `; ${result.detail}` : ""}`);
+    return results.some(result => result.status === "failed") ? 1 : 0;
+}