@lynxship/cli 0.1.16 → 0.1.18

package/README.md

@@ -25,6 +25,26 @@ npx @lynxship/cli@latest doctor --project-dir ./my-lynx-app
 
 The package exposes the `lynxship` executable.
 
+## Plugin ecosystem
+
+Install a community plugin as a normal project dependency, list it in
+`lynxship.json`, then validate it before building:
+
+```bash
+npm install --save-dev @example/lynx-plugin
+npx lynxship plugin doctor
+npx lynxship plugin list
+npx lynxship plugin apply --platform android --profile production
+```
+
+The public contract is exported by `@lynxship/plugin-api`. Plugins can make
+JSON configuration contributions and bounded, idempotent Android/iOS/native
+file changes. Autolink remains the official Lynx `lynx.lib.json` and codegen
+workflow. Template and cloud contributions are discoverable metadata until a
+reviewed provider or template service consumes them.
+
+See the full contract in the repository `docs/plugin-ecosystem.md`.
+
 ## Vue Lynx projects
 
 LynxShip supports projects created with the official Vue Lynx scaffold. Vue
@@ -514,7 +534,8 @@ actual recording and analysis.
 
 ## Package layout
 
-The CLI is backed by public `@lynxship/*` runtime packages in this workspace.
+The CLI is backed by public `@lynxship/*` runtime packages in this workspace,
+including the public `@lynxship/plugin-api` contract.
 Their published versions may differ from the CLI version; workspace ranges are
 rewritten to released versions when the package is packed. Publish a changed
 runtime package before publishing the CLI when its source or version changed.

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { type Platform } from "@lynxship/contracts";
+import type { PluginReference } from "@lynxship/plugin-api";
 export interface BuildProfile {
     distribution?: string;
     channel?: string;
@@ -43,6 +44,7 @@ export interface BuildProfile {
 }
 export interface LynxShipConfig {
     projectId?: string;
+    plugins?: PluginReference[];
     cli?: {
         apiUrl?: string;
         organizationId?: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -33,6 +33,7 @@ const allowedRootKeys = new Set([
     "submit",
     "update",
     "artifacts",
+    "plugins",
 ]);
 export function validateConfig(config, options = {}) {
     assert(config && typeof config === "object" && !Array.isArray(config), "CONFIG_INVALID", "lynxship.json must contain an object");
@@ -41,6 +42,20 @@ export function validateConfig(config, options = {}) {
     assert(!options.ci || unknown.length === 0, "CONFIG_UNKNOWN_KEY", `Unknown configuration key(s): ${unknown.join(", ")}`, { unknown });
     if (value.projectId !== undefined)
         assert(typeof value.projectId === "string" && value.projectId.length > 0, "CONFIG_PROJECT_ID", "projectId must be a non-empty string");
+    if (value.plugins !== undefined) {
+        assert(Array.isArray(value.plugins), "CONFIG_PLUGINS", "plugins must be an array of package names or [package, options] tuples");
+        for (const plugin of value.plugins) {
+            const validString = typeof plugin === "string" && plugin.length > 0;
+            const validTuple = Array.isArray(plugin) &&
+                plugin.length === 2 &&
+                typeof plugin[0] === "string" &&
+                plugin[0].length > 0 &&
+                plugin[1] !== null &&
+                typeof plugin[1] === "object" &&
+                !Array.isArray(plugin[1]);
+            assert(validString || validTuple, "CONFIG_PLUGINS", "Each plugin must be a package name or [package name, JSON options]");
+        }
+    }
     assert(value.runtimeVersion?.policy === undefined ||
         ["fingerprint", "manual"].includes(value.runtimeVersion.policy), "CONFIG_RUNTIME_POLICY", "runtimeVersion.policy must be fingerprint or manual");
     if (value.runtimeVersion?.policy === "manual")

package/dist/index.js

@@ -35,6 +35,7 @@ import { hasHarmonyHost, runRealHarmonyBuild } from "./harmony-build.js";
 import { hasWebConfiguration, runRealWebBuild } from "./web-build.js";
 import { hasDesktopHost, runRealDesktopBuild } from "./desktop-build.js";
 import { extractDevServerUrl, shouldPrintDevServerQr } from "./dev-qr.js";
+import { applyProjectPlugins, inspectProjectPlugins } from "./plugins.js";
 import { inspectDesktopTarget, inspectHarmonyTarget, inspectWebTarget, } from "./target-toolchain.js";
 const rawArgs = process.argv.slice(2);
 const args = [...rawArgs];
@@ -216,7 +217,20 @@ async function executeBuild(options, showResult = true) {
     // Host initialization can write lynxship.json (for example, the generated
     // iOS scheme). Always read it again before resolving the build profile so a
     // first build uses the host that was just created in the same invocation.
-    const effectiveConfig = wait && !local ? await loadConfig(root) : config;
+    const loadedConfig = wait && !local ? await loadConfig(root) : config;
+    const pluginApplication = wait && !local
+        ? await applyProjectPlugins(root, loadedConfig, { platform, profile })
+        : {
+            config: loadedConfig,
+            report: { configured: 0, plugins: [] },
+            applied: [],
+            templates: [],
+            cloud: [],
+            build: [],
+            changes: [],
+            autolink: [],
+        };
+    const effectiveConfig = pluginApplication.config;
     if (platform === "android" || platform === "ios")
         await requireAutolinkReady(root, platform);
     const runtime = await inspectRuntimeFingerprint(root, platform, effectiveConfig);
@@ -418,6 +432,7 @@ function commandTitle(command) {
         devtool: "Lynx DevTool diagnostics",
         trace: "Lynx Trace diagnostics",
         recorder: "Lynx Recorder diagnostics",
+        plugin: "LynxShip plugins",
     }[command] ?? command);
 }
 function helpText() {
@@ -433,6 +448,10 @@ Commands:
   devtool doctor          Check Lynx DevTool integration and dev runtime
   trace doctor            Check Lynx Trace prerequisites
   recorder doctor         Check Lynx Recorder prerequisites
+  plugin list             List project plugins and their capabilities
+  plugin doctor            Validate plugin packages without modifying native files
+  plugin apply             Apply project plugin native changes for a platform
+  plugin apply --dry-run   Preview plugin native changes without writing files
   autolink check          Check Lynx native-library Autolink wiring
   autolink codegen        Run the project's Native Module codegen script
   ota doctor              Check native OTA host integration
@@ -905,6 +924,80 @@ async function main() {
         });
         return;
     }
+    if (command === "plugin") {
+        const subcommand = args.shift() ?? "list";
+        assert(["list", "doctor", "apply"].includes(subcommand), "CLI_PLUGIN_COMMAND", "Use \`lynxship plugin list\`, \`lynxship plugin doctor\` or \`lynxship plugin apply\`.");
+        await requireProjectRoot();
+        const config = await loadConfig(root);
+        const report = await inspectProjectPlugins(root, config);
+        if (subcommand === "apply") {
+            const platform = platformValue(flag("--platform", "android"));
+            const profile = flag("--profile", "production");
+            const dryRun = args.includes("--dry-run");
+            const result = await applyProjectPlugins(root, config, {
+                platform,
+                profile,
+                mode: dryRun ? "plan" : "apply",
+            });
+            printValue({
+                status: dryRun ? "planned" : "applied",
+                platform,
+                profile,
+                plugins: result.applied,
+                nativeChanges: result.changes.filter((change) => change.changed)
+                    .length,
+                changes: result.changes,
+                templates: result.templates,
+                cloud: result.cloud,
+                build: result.build,
+            }, {
+                title: `LynxShip plugins · ${platform}`,
+                rows: [
+                    {
+                        label: "Applied",
+                        value: result.applied.length ? result.applied.join(", ") : "none",
+                        valueColor: "green",
+                    },
+                    {
+                        label: "Native changes",
+                        value: String(result.changes.filter((change) => change.changed).length),
+                        valueColor: "blue",
+                    },
+                ],
+                done: dryRun
+                    ? "No native files were modified; review the planned changes."
+                    : "Project plugin changes are applied atomically and idempotently.",
+            });
+            return;
+        }
+        const invalid = report.plugins.filter((plugin) => plugin.status !== "ready");
+        printValue(report, {
+            title: `LynxShip plugins · ${subcommand}`,
+            rows: report.plugins.length > 0
+                ? report.plugins.map((plugin) => ({
+                    label: plugin.name,
+                    value: `${plugin.status} · ${plugin.capabilities.join(", ") || "no capabilities"} · ${plugin.reason}`,
+                    valueColor: plugin.status === "ready"
+                        ? "green"
+                        : plugin.status === "missing"
+                            ? "red"
+                            : "yellow",
+                }))
+                : [
+                    {
+                        label: "Plugins",
+                        value: "none configured",
+                        valueColor: "muted",
+                    },
+                ],
+            done: invalid.length === 0
+                ? "All project plugin manifests are valid."
+                : "Fix the invalid plugin package before building.",
+        });
+        if (subcommand === "doctor" && invalid.length > 0)
+            process.exitCode = 1;
+        return;
+    }
     if (command === "doctor") {
         const config = await loadConfig(root);
         const configuration = await readConfigurationStatus();
@@ -946,6 +1039,8 @@ async function main() {
         const nodeSupported = nodeMajor >= 22;
         const nodeRecommended = nodeMajor % 2 === 0;
         const framework = await detectLynxFramework(root);
+        const pluginReport = await inspectProjectPlugins(root, config);
+        const invalidPlugins = pluginReport.plugins.filter((plugin) => plugin.status !== "ready");
         const checks = [
             {
                 name: "lynx-framework",
@@ -1002,6 +1097,16 @@ async function main() {
                 status: config.projectId ? "pass" : "fail",
                 value: config.projectId ? "found" : "missing · fix: lynxship init",
             },
+            {
+                name: "lynxship-plugins",
+                ok: invalidPlugins.length === 0,
+                status: invalidPlugins.length === 0 ? "pass" : "fail",
+                value: invalidPlugins.length === 0
+                    ? pluginReport.configured === 0
+                        ? "none configured"
+                        : `${pluginReport.configured} plugin(s) ready`
+                    : `${invalidPlugins.map((plugin) => plugin.name).join(", ")} · fix: lynxship plugin doctor`,
+            },
             {
                 name: "credential-store",
                 ok: true,

package/dist/plugin-api.d.ts

@@ -0,0 +1,2 @@
+export * from "@lynxship/plugin-api";
+//# sourceMappingURL=plugin-api.d.ts.map

package/dist/plugin-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/plugin-api.js

@@ -0,0 +1 @@
+export * from "@lynxship/plugin-api";

package/dist/plugins.d.ts

@@ -0,0 +1,35 @@
+import type { Platform } from "@lynxship/contracts";
+import { type BuildContribution, type CloudIntegrationContribution, type PluginCapability, type AutolinkContribution, type PluginPermission, type PluginPlanChange, type TemplateContribution } from "@lynxship/plugin-api";
+import type { LynxShipConfig } from "./config.js";
+export interface ProjectPluginInfo {
+    name: string;
+    version?: string;
+    packagePath?: string;
+    entry?: string;
+    apiVersion?: number;
+    capabilities: PluginCapability[];
+    permissions: PluginPermission[];
+    status: "ready" | "missing" | "invalid";
+    reason: string;
+}
+export interface PluginReport {
+    configured: number;
+    plugins: ProjectPluginInfo[];
+}
+export interface PluginApplication {
+    config: LynxShipConfig;
+    report: PluginReport;
+    applied: string[];
+    templates: TemplateContribution[];
+    cloud: CloudIntegrationContribution[];
+    build: BuildContribution[];
+    changes: PluginPlanChange[];
+    autolink: AutolinkContribution[];
+}
+export declare function inspectProjectPlugins(root: string, config: LynxShipConfig): Promise<PluginReport>;
+export declare function applyProjectPlugins(root: string, config: LynxShipConfig, target: {
+    platform: Platform;
+    profile: string;
+    mode?: "plan" | "apply";
+}): Promise<PluginApplication>;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EAKjC,KAAK,gBAAgB,EAErB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EAGrB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAclD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,KAAK,EAAE,4BAA4B,EAAE,CAAC;IACtC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAqUD,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,YAAY,CAAC,CAQvB;AA+XD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GACvE,OAAO,CAAC,iBAAiB,CAAC,CAqF5B"}

package/dist/plugins.js

@@ -0,0 +1,595 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile, } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { LYNXSHIP_PLUGIN_API_VERSION, } from "@lynxship/plugin-api";
+function pluginReference(reference) {
+    if (typeof reference === "string")
+        return { name: reference, options: {} };
+    return { name: reference[0], options: reference[1] };
+}
+function packageDirectory(entry) {
+    let current = dirname(entry);
+    while (true) {
+        if (existsSync(join(current, "package.json")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return dirname(entry);
+        current = parent;
+    }
+}
+function parsePackageJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function packageJsonFromEntry(entry) {
+    return join(packageDirectory(entry), "package.json");
+}
+function findInstalledPackageJson(root, name) {
+    let current = root;
+    while (true) {
+        const candidate = join(current, "node_modules", ...name.split("/"), "package.json");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function capabilities(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((candidate) => ["config", "build", "native", "autolink", "template", "cloud"].includes(candidate));
+}
+const KNOWN_CAPABILITIES = [
+    "config",
+    "build",
+    "native",
+    "autolink",
+    "template",
+    "cloud",
+];
+const KNOWN_PERMISSIONS = [
+    "config:write",
+    "build:metadata",
+    "native:write",
+    "autolink:metadata",
+    "template:register",
+    "cloud:provider",
+];
+function isKnownList(value, allowed) {
+    return (Array.isArray(value) &&
+        value.every((candidate) => typeof candidate === "string" && allowed.includes(candidate)));
+}
+function permissions(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((candidate) => [
+        "config:write",
+        "build:metadata",
+        "native:write",
+        "autolink:metadata",
+        "template:register",
+        "cloud:provider",
+    ].includes(candidate));
+}
+function validPluginDefinition(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const definition = value;
+    return (definition.apiVersion === LYNXSHIP_PLUGIN_API_VERSION &&
+        typeof definition.name === "string" &&
+        definition.name.length > 0 &&
+        isKnownList(definition.capabilities, KNOWN_CAPABILITIES) &&
+        isKnownList(definition.permissions, KNOWN_PERMISSIONS) &&
+        (definition.platforms === undefined ||
+            isKnownList(definition.platforms, [
+                "all",
+                "android",
+                "ios",
+                "harmonyos",
+                "web",
+                "desktop",
+            ])) &&
+        typeof definition.apply === "function");
+}
+function resolvePackageEntry(root, name) {
+    try {
+        const requireFromProject = createRequire(join(root, "package.json"));
+        let entry;
+        let packagePath;
+        try {
+            entry = requireFromProject.resolve(name);
+            packagePath = packageJsonFromEntry(entry);
+        }
+        catch {
+            packagePath = findInstalledPackageJson(root, name) ?? "";
+            if (!packagePath)
+                throw new Error("Cannot find module '" + name + "'");
+            entry = packagePath;
+        }
+        const packageJson = parsePackageJson(packagePath);
+        const plugin = packageJson.lynxship?.plugin;
+        if (typeof plugin !== "string" || !plugin)
+            return {
+                packagePath,
+                reason: `${name} does not declare package.json#lynxship.plugin`,
+            };
+        const packageRoot = dirname(packagePath);
+        const resolved = resolve(packageRoot, plugin);
+        const outside = relative(packageRoot, resolved).startsWith("..");
+        if (outside)
+            return {
+                packagePath,
+                reason: `${name} points its plugin entry outside the package`,
+            };
+        if (!existsSync(resolved))
+            return {
+                packagePath,
+                reason: `${name} plugin entry does not exist: ${plugin}`,
+            };
+        return { packagePath, entry: resolved };
+    }
+    catch (error) {
+        return {
+            reason: error instanceof Error
+                ? `Cannot resolve ${name}: ${error.message}`
+                : `Cannot resolve ${name}`,
+        };
+    }
+}
+async function resolvePlugin(root, reference, load = true) {
+    const requested = pluginReference(reference);
+    const resolved = resolvePackageEntry(root, requested.name);
+    if (!resolved.packagePath || !resolved.entry) {
+        return {
+            info: {
+                name: requested.name,
+                capabilities: [],
+                permissions: [],
+                status: "missing",
+                reason: resolved.reason ?? "Plugin package was not found",
+            },
+        };
+    }
+    const packageJson = parsePackageJson(resolved.packagePath);
+    const metadata = packageJson.lynxship;
+    const apiVersion = typeof metadata?.apiVersion === "number" ? metadata.apiVersion : undefined;
+    const packageCapabilities = capabilities(metadata?.capabilities);
+    const packagePermissions = permissions(metadata?.permissions);
+    if (!isKnownList(metadata?.capabilities, KNOWN_CAPABILITIES) ||
+        !isKnownList(metadata?.permissions, KNOWN_PERMISSIONS)) {
+        return {
+            info: {
+                name: requested.name,
+                version: typeof packageJson.version === "string"
+                    ? packageJson.version
+                    : undefined,
+                packagePath: resolved.packagePath,
+                entry: resolved.entry,
+                apiVersion,
+                capabilities: packageCapabilities,
+                permissions: packagePermissions,
+                status: "invalid",
+                reason: "Plugin package capabilities and permissions must be arrays of known values",
+            },
+        };
+    }
+    if (apiVersion !== LYNXSHIP_PLUGIN_API_VERSION) {
+        return {
+            info: {
+                name: requested.name,
+                version: typeof packageJson.version === "string"
+                    ? packageJson.version
+                    : undefined,
+                packagePath: resolved.packagePath,
+                entry: resolved.entry,
+                apiVersion,
+                capabilities: packageCapabilities,
+                permissions: packagePermissions,
+                status: "invalid",
+                reason: `Plugin API ${String(apiVersion ?? "missing")} is not supported; expected ${LYNXSHIP_PLUGIN_API_VERSION}`,
+            },
+        };
+    }
+    const info = {
+        name: requested.name,
+        version: typeof packageJson.version === "string" ? packageJson.version : undefined,
+        packagePath: resolved.packagePath,
+        entry: resolved.entry,
+        apiVersion,
+        capabilities: packageCapabilities,
+        permissions: packagePermissions,
+        status: "ready",
+        reason: "Plugin manifest is valid",
+    };
+    if (!load)
+        return { info };
+    try {
+        const module = (await import(pathToFileURL(resolved.entry).href));
+        const definition = module.default ?? module.plugin;
+        if (!validPluginDefinition(definition)) {
+            return {
+                info: {
+                    ...info,
+                    status: "invalid",
+                    reason: "Plugin entry must export a LynxShipPluginDefinition",
+                },
+            };
+        }
+        if (capabilities(definition.capabilities).join(",") !==
+            packageCapabilities.join(",") ||
+            permissions(definition.permissions).join(",") !==
+                packagePermissions.join(",")) {
+            return {
+                info: {
+                    ...info,
+                    status: "invalid",
+                    reason: "Plugin code capabilities/permissions do not match package.json",
+                },
+            };
+        }
+        if (definition.name !== requested.name &&
+            definition.name !== packageJson.name) {
+            return {
+                info: {
+                    ...info,
+                    status: "invalid",
+                    reason: `Plugin entry name '${definition.name}' does not match its package`,
+                },
+            };
+        }
+        return { info, definition };
+    }
+    catch (error) {
+        return {
+            info: {
+                ...info,
+                status: "invalid",
+                reason: error instanceof Error
+                    ? `Plugin entry failed to load: ${error.message}`
+                    : "Plugin entry failed to load",
+            },
+        };
+    }
+}
+function pluginReferences(config) {
+    const value = config.plugins;
+    if (!Array.isArray(value))
+        return [];
+    return value;
+}
+export async function inspectProjectPlugins(root, config) {
+    const references = pluginReferences(config);
+    const plugins = await Promise.all(references.map(async (reference) => (await resolvePlugin(root, reference, false)).info));
+    return { configured: references.length, plugins };
+}
+function appliesToPlatform(platforms, platform) {
+    return (!platforms ||
+        platforms.length === 0 ||
+        platforms.includes("all") ||
+        platforms.includes(platform));
+}
+function mergeJson(left, right) {
+    const result = { ...left };
+    for (const [key, value] of Object.entries(right)) {
+        const current = result[key];
+        if (current &&
+            typeof current === "object" &&
+            !Array.isArray(current) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            result[key] = mergeJson(current, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function safeProjectFile(root, file) {
+    if (isAbsolute(file))
+        throw new Error(`Plugin native file must be relative: ${file}`);
+    const target = resolve(root, file);
+    const projectRelative = relative(root, target);
+    if (!projectRelative ||
+        projectRelative.startsWith("..") ||
+        isAbsolute(projectRelative))
+        throw new Error(`Plugin native file escapes the project: ${file}`);
+    return target;
+}
+function permissionForContribution(contribution) {
+    const required = [];
+    if (contribution.config)
+        required.push("config:write");
+    if (contribution.build)
+        required.push("build:metadata");
+    if (contribution.native?.length)
+        required.push("native:write");
+    if (contribution.autolink)
+        required.push("autolink:metadata");
+    if (contribution.templates?.length)
+        required.push("template:register");
+    if (contribution.cloud?.length)
+        required.push("cloud:provider");
+    return required;
+}
+function capabilityForPermission(permission) {
+    return permission.split(":")[0];
+}
+function isJsonObject(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function assertPluginContribution(plugin, contribution) {
+    if (!isJsonObject(contribution))
+        throw new Error(`Plugin '${plugin.name}' returned an invalid contribution object`);
+    if (contribution.config !== undefined && !isJsonObject(contribution.config))
+        throw new Error(`Plugin '${plugin.name}' returned an invalid config contribution`);
+    if (contribution.native !== undefined && !Array.isArray(contribution.native))
+        throw new Error(`Plugin '${plugin.name}' returned an invalid native contribution`);
+    for (const operation of contribution.native ?? []) {
+        if (!isJsonObject(operation))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid native operation`);
+        if (!["all", "android", "ios", "harmonyos", "web", "desktop"].includes(String(operation.platform)) ||
+            typeof operation.file !== "string" ||
+            operation.file.length === 0 ||
+            !["ensure-text", "append-text", "replace-text", "json-merge"].includes(String(operation.operation)))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid native operation`);
+        if ((operation.operation === "ensure-text" ||
+            operation.operation === "append-text") &&
+            typeof operation.text !== "string")
+            throw new Error(`Plugin '${plugin.name}' returned an invalid text operation`);
+        if (operation.operation === "replace-text" &&
+            (typeof operation.from !== "string" || typeof operation.to !== "string"))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid replacement operation`);
+        if (operation.operation === "json-merge" && !isJsonObject(operation.value))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid JSON merge operation`);
+    }
+    if (contribution.autolink !== undefined) {
+        if (!isJsonObject(contribution.autolink))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid Autolink contribution`);
+        for (const key of ["packageNames", "capabilities"]) {
+            const value = contribution.autolink[key];
+            if (value !== undefined &&
+                (!Array.isArray(value) ||
+                    !value.every((item) => typeof item === "string")))
+                throw new Error(`Plugin '${plugin.name}' returned invalid Autolink metadata`);
+        }
+    }
+    if (contribution.build !== undefined) {
+        if (!isJsonObject(contribution.build))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid build contribution`);
+        for (const key of [
+            "requiredTools",
+            "artifactExtensions",
+            "notes",
+        ]) {
+            const value = contribution.build[key];
+            if (value !== undefined &&
+                (!Array.isArray(value) ||
+                    !value.every((item) => typeof item === "string")))
+                throw new Error(`Plugin '${plugin.name}' returned invalid build metadata`);
+        }
+    }
+    for (const template of Array.isArray(contribution.templates)
+        ? contribution.templates
+        : []) {
+        if (!isJsonObject(template) ||
+            typeof template.id !== "string" ||
+            typeof template.displayName !== "string" ||
+            typeof template.source !== "string")
+            throw new Error(`Plugin '${plugin.name}' returned an invalid template contribution`);
+    }
+    for (const integration of Array.isArray(contribution.cloud)
+        ? contribution.cloud
+        : []) {
+        if (!isJsonObject(integration) ||
+            typeof integration.id !== "string" ||
+            typeof integration.displayName !== "string" ||
+            !Array.isArray(integration.capabilities) ||
+            !integration.capabilities.every((item) => ["build", "artifacts", "updates", "submit"].includes(String(item))))
+            throw new Error(`Plugin '${plugin.name}' returned an invalid cloud contribution`);
+    }
+}
+function assertPluginPermissions(plugin, contribution) {
+    const missing = permissionForContribution(contribution).filter((permission) => !plugin.permissions.includes(permission));
+    const missingCapabilities = permissionForContribution(contribution)
+        .map(capabilityForPermission)
+        .filter((capability) => !plugin.capabilities.includes(capability));
+    if (missing.length)
+        throw new Error(`Plugin '${plugin.name}' returned contributions without declaring permission(s): ${missing.join(", ")}`);
+    if (missingCapabilities.length)
+        throw new Error(`Plugin '${plugin.name}' returned contributions without declaring capability(ies): ${[...new Set(missingCapabilities)].join(", ")}`);
+}
+async function mergeJsonFile(file, value) {
+    const current = JSON.parse(await readFile(file, "utf8"));
+    await writeFile(file, `${JSON.stringify(mergeJson(current, value), null, 2)}\n`);
+}
+async function inspectNativeOperation(root, owned, platform) {
+    const operation = owned.operation;
+    if (!appliesToPlatform([operation.platform], platform))
+        return undefined;
+    const file = safeProjectFile(root, operation.file);
+    const current = existsSync(file) ? await readFile(file, "utf8") : "";
+    let changed = false;
+    if (operation.operation === "json-merge") {
+        if (!existsSync(file))
+            throw new Error(`Plugin JSON target does not exist: ${operation.file}`);
+        const merged = `${JSON.stringify(mergeJson(JSON.parse(current), operation.value), null, 2)}\n`;
+        changed = merged !== current;
+    }
+    else if (operation.operation === "ensure-text") {
+        changed = !current.includes(operation.text);
+    }
+    else if (operation.operation === "append-text") {
+        changed = !current.includes(operation.text);
+    }
+    else if (operation.operation === "replace-text") {
+        if (!current.includes(operation.from))
+            throw new Error(`Plugin replacement target was not found in ${operation.file}`);
+        changed = current.replace(operation.from, operation.to) !== current;
+    }
+    return {
+        plugin: owned.plugin,
+        platform,
+        file: operation.file,
+        operation: operation.operation,
+        changed,
+    };
+}
+async function applyNativeOperation(root, operation, platform) {
+    if (!appliesToPlatform([operation.platform], platform))
+        return;
+    const file = safeProjectFile(root, operation.file);
+    await mkdir(dirname(file), { recursive: true });
+    if (operation.operation === "json-merge") {
+        if (!existsSync(file))
+            throw new Error(`Plugin JSON target does not exist: ${operation.file}`);
+        await mergeJsonFile(file, operation.value);
+        return;
+    }
+    const current = existsSync(file) ? await readFile(file, "utf8") : "";
+    if (operation.operation === "ensure-text") {
+        if (!current.includes(operation.text))
+            await writeFile(file, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${operation.text}\n`);
+        return;
+    }
+    if (operation.operation === "append-text") {
+        if (current.includes(operation.text))
+            return;
+        await writeFile(file, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${operation.text}\n`);
+        return;
+    }
+    if (operation.operation !== "replace-text")
+        return;
+    if (!current.includes(operation.from))
+        throw new Error(`Plugin replacement target was not found in ${operation.file}`);
+    await writeFile(file, current.replace(operation.from, operation.to));
+}
+function assertNativeConflicts(root, operations) {
+    const seen = new Map();
+    for (const owned of operations) {
+        const file = safeProjectFile(root, owned.operation.file);
+        const previous = seen.get(file);
+        if (!previous) {
+            seen.set(file, owned);
+            continue;
+        }
+        const currentOperation = owned.operation;
+        const previousOperation = previous.operation;
+        if (currentOperation.operation === "replace-text" &&
+            previousOperation.operation === "replace-text" &&
+            currentOperation.from === previousOperation.from)
+            throw new Error(`Conflicting or duplicate LynxShip plugins '${previous.plugin}' and '${owned.plugin}' both replace '${currentOperation.from}' in ${currentOperation.file}`);
+    }
+}
+async function applyNativeOperationsAtomically(root, operations, platform) {
+    assertNativeConflicts(root, operations);
+    const backups = new Map();
+    for (const owned of operations) {
+        if (!appliesToPlatform([owned.operation.platform], platform))
+            continue;
+        const file = safeProjectFile(root, owned.operation.file);
+        if (!backups.has(file))
+            backups.set(file, existsSync(file) ? await readFile(file, "utf8") : undefined);
+    }
+    try {
+        const changes = (await Promise.all(operations.map((operation) => inspectNativeOperation(root, operation, platform)))).filter((change) => Boolean(change));
+        for (const owned of operations)
+            await applyNativeOperation(root, owned.operation, platform);
+        return changes;
+    }
+    catch (error) {
+        for (const [file, content] of backups) {
+            if (content === undefined)
+                await rm(file, { force: true });
+            else {
+                await mkdir(dirname(file), { recursive: true });
+                await writeFile(file, content);
+            }
+        }
+        throw new Error(`${error instanceof Error ? error.message : String(error)}; native plugin changes were rolled back`);
+    }
+}
+export async function applyProjectPlugins(root, config, target) {
+    const references = pluginReferences(config);
+    const resolved = [];
+    for (const reference of references)
+        resolved.push(await resolvePlugin(root, reference));
+    const report = {
+        configured: references.length,
+        plugins: resolved.map((plugin) => plugin.info),
+    };
+    const invalid = report.plugins.find((plugin) => plugin.status !== "ready");
+    if (invalid)
+        throw new Error(`LynxShip plugin '${invalid.name}' is invalid: ${invalid.reason}`);
+    let effectiveConfig = JSON.parse(JSON.stringify(config));
+    const applied = [];
+    const templates = [];
+    const cloud = [];
+    const build = [];
+    const autolink = [];
+    const operations = [];
+    for (let index = 0; index < resolved.length; index += 1) {
+        const plugin = resolved[index];
+        const reference = references[index];
+        if (!plugin?.definition || !reference)
+            continue;
+        if (!appliesToPlatform(plugin.definition.platforms, target.platform))
+            continue;
+        const options = pluginReference(reference).options;
+        const context = {
+            rootDir: root,
+            platform: target.platform,
+            profile: target.profile,
+            mode: target.mode ?? "apply",
+            projectId: config.projectId,
+            config: effectiveConfig,
+            options,
+        };
+        const contribution = await plugin.definition.apply(context);
+        if (!contribution) {
+            applied.push(plugin.info.name);
+            continue;
+        }
+        assertPluginContribution(plugin.definition, contribution);
+        assertPluginPermissions(plugin.definition, contribution);
+        if (contribution.config)
+            effectiveConfig = mergeJson(effectiveConfig, contribution.config);
+        for (const operation of contribution.native ?? [])
+            operations.push({ plugin: plugin.info.name, operation });
+        if (contribution.autolink)
+            autolink.push(contribution.autolink);
+        templates.push(...(contribution.templates ?? []));
+        cloud.push(...(contribution.cloud ?? []));
+        if (contribution.build)
+            build.push(contribution.build);
+        applied.push(plugin.info.name);
+    }
+    let changes;
+    if (target.mode === "plan") {
+        assertNativeConflicts(root, operations);
+        changes = (await Promise.all(operations.map((operation) => inspectNativeOperation(root, operation, target.platform)))).filter((change) => Boolean(change));
+    }
+    else {
+        changes = await applyNativeOperationsAtomically(root, operations, target.platform);
+    }
+    return {
+        config: effectiveConfig,
+        report,
+        applied,
+        templates,
+        cloud,
+        build,
+        autolink,
+        changes,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynxship/cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Build, sign, store, submit and update LynxJS applications from the terminal.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,10 @@
       "types": "./dist/frameworks.d.ts",
       "import": "./dist/frameworks.js"
     },
+    "./plugin-api": {
+      "types": "./dist/plugin-api.d.ts",
+      "import": "./dist/plugin-api.js"
+    },
     "./ui/*": {
       "types": "./dist/ui/*.d.ts",
       "import": "./dist/ui/*.js"
@@ -76,9 +80,10 @@
     "@resvg/resvg-js": "2.6.2",
     "jsdom": "29.1.1",
     "pngjs": "7.0.0",
-    "@lynxship/contracts": "0.1.0",
     "@lynxship/build-orchestrator": "0.1.0",
+    "@lynxship/contracts": "0.1.0",
     "@lynxship/submit": "0.1.0",
+    "@lynxship/plugin-api": "0.1.0",
     "@lynxship/signing": "0.1.0",
     "@lynxship/db": "0.1.0"
   },