@lynxship/cli 0.1.20 → 0.1.21

package/dist/ios-toolchain.js

@@ -1,336 +1,4 @@
-import { homedir, platform } from "node:os";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { captureProcess, commandExists, } from "./process-runner.js";
-function check(name, status, value, fix) {
-    return { name, status, ok: status !== "fail", value, fix };
-}
-function findHost(root, profile) {
-    const configured = profile.ios?.workspace ?? profile.ios?.project;
-    if (configured) {
-        const configuredPath = resolve(root, configured);
-        if (configuredPath.endsWith(".xcodeproj")) {
-            const workspace = configuredPath.replace(/\.xcodeproj$/, ".xcworkspace");
-            if (existsSync(workspace))
-                return workspace;
-        }
-        return configuredPath;
-    }
-    for (const directory of ["ios", "macos"]) {
-        try {
-            const candidate = readdirSync(join(root, directory)).find((name) => name.endsWith(".xcworkspace") || name.endsWith(".xcodeproj"));
-            if (candidate)
-                return join(root, directory, candidate);
-        }
-        catch {
-            // A native host is optional until an iOS build is requested.
-        }
-    }
-    return undefined;
-}
-function projectFlag(path) {
-    return path.endsWith(".xcworkspace") ? "-workspace" : "-project";
-}
-function commandOutput(result) {
-    return `${result.stdout}\n${result.stderr}`.trim();
-}
-function setting(output, name) {
-    return output.match(new RegExp(`^${name}\\s*=\\s*(.+)$`, "m"))?.[1]?.trim();
-}
-function provisioningProfilesDirectory() {
-    return join(homedir(), "Library", "MobileDevice", "Provisioning Profiles");
-}
-function provisioningProfileFiles() {
-    try {
-        return readdirSync(provisioningProfilesDirectory())
-            .filter((name) => /\.(?:mobileprovision|provisionprofile)$/.test(name))
-            .map((name) => join(provisioningProfilesDirectory(), name));
-    }
-    catch {
-        return [];
-    }
-}
-function plistValue(content, key) {
-    return content.match(new RegExp(`<key>${key}</key>\\s*<(?:string|date)>([^<]+)</`))?.[1];
-}
-async function validProvisioningProfile(file, root, bundleIdentifier) {
-    if (!commandExists("security"))
-        return false;
-    try {
-        const decoded = await captureProcess("security", ["cms", "-D", "-i", file], { cwd: root });
-        if (decoded.code !== 0)
-            return false;
-        const content = commandOutput(decoded);
-        const expiration = plistValue(content, "ExpirationDate");
-        if (!expiration || Number.isNaN(Date.parse(expiration)))
-            return false;
-        if (Date.parse(expiration) <= Date.now())
-            return false;
-        if (!bundleIdentifier)
-            return true;
-        const applicationIdentifier = plistValue(content, "application-identifier");
-        if (!applicationIdentifier)
-            return false;
-        const profileBundle = applicationIdentifier.split(".").slice(1).join(".");
-        return profileBundle === bundleIdentifier || profileBundle === "*";
-    }
-    catch {
-        return false;
-    }
-}
-async function hasValidProvisioningProfile(root, bundleIdentifier) {
-    const files = provisioningProfileFiles();
-    for (const file of files) {
-        if (await validProvisioningProfile(file, root, bundleIdentifier))
-            return true;
-    }
-    return false;
-}
-async function probeProject(root, context, profile, target) {
-    if (!context.path || !context.scheme || !commandExists("xcodebuild"))
-        return context;
-    const configuration = profile.ios?.configuration ??
-        (target === "simulator" ? "Debug" : "Release");
-    const settings = await captureProcess("xcodebuild", [
-        context.flag,
-        context.path,
-        "-scheme",
-        context.scheme,
-        "-configuration",
-        configuration,
-        "-showBuildSettings",
-    ], { cwd: root });
-    return { ...context, settings };
-}
-async function probeVersion(command, args, cwd) {
-    if (!commandExists(command))
-        return undefined;
-    try {
-        const result = await captureProcess(command, args, { cwd });
-        if (result.code !== 0)
-            return undefined;
-        return commandOutput(result).split(/\r?\n/)[0]?.trim();
-    }
-    catch {
-        return undefined;
-    }
-}
-async function probeCommand(command, args, cwd) {
-    if (!commandExists(command))
-        return false;
-    try {
-        return (await captureProcess(command, args, { cwd })).code === 0;
-    }
-    catch {
-        return false;
-    }
-}
-export async function inspectIosToolchain(root, profile, target = "device") {
-    const checks = [];
-    const isMac = platform() === "darwin";
-    const host = findHost(root, profile);
-    const hostExists = Boolean(host && existsSync(host));
-    const scheme = profile.ios?.scheme;
-    const simulator = target === "simulator";
-    const exportOptions = profile.ios?.exportOptionsPlist
-        ? resolve(root, profile.ios.exportOptionsPlist)
-        : undefined;
-    checks.push(check("ios-platform", isMac ? "pass" : "fail", isMac
-        ? "macOS"
-        : `${platform()} · macOS is required for an iOS ${simulator ? "Simulator app" : "IPA"}`, isMac
-        ? undefined
-        : "Run the iOS build on a macOS machine or macOS CI runner"));
-    if (!isMac) {
-        checks.push(check("ios-host", "warn", hostExists
-            ? "host found but not inspectable on this OS"
-            : "not inspected"));
-        return {
-            ok: checks.every((item) => item.status !== "fail"),
-            checks,
-            project: host,
-            scheme,
-            automaticSigning: false,
-        };
-    }
-    const developerDirectory = await probeVersion("xcode-select", ["-p"], root);
-    checks.push(check("xcode-select", developerDirectory ? "pass" : "fail", developerDirectory ?? "no active Xcode developer directory", developerDirectory
-        ? undefined
-        : "sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer"));
-    const xcodeVersion = await probeVersion("xcodebuild", ["-version"], root);
-    checks.push(check("xcode", xcodeVersion ? "pass" : "fail", xcodeVersion ?? "xcodebuild unavailable", xcodeVersion
-        ? undefined
-        : "Install Xcode, open it once, accept its license, then run xcode-select --install if needed"));
-    checks.push(check("xcrun", commandExists("xcrun") ? "pass" : "fail", commandExists("xcrun") ? "available" : "missing", commandExists("xcrun")
-        ? undefined
-        : "Install Xcode and select its command-line tools"));
-    checks.push(check("codesign", commandExists("codesign") ? "pass" : "fail", commandExists("codesign") ? "available" : "missing", commandExists("codesign")
-        ? undefined
-        : "Install Xcode command-line tools"));
-    checks.push(check("unzip", commandExists("unzip") ? "pass" : "fail", commandExists("unzip") ? "available" : "missing", commandExists("unzip")
-        ? undefined
-        : "Install the macOS command-line tools"));
-    checks.push(check("ios-host", hostExists ? "pass" : "fail", hostExists ? host : "Xcode project or workspace not found", hostExists
-        ? undefined
-        : "lynxship ios host init --bundle-identifier com.example.myapp"));
-    checks.push(check("ios-scheme", scheme ? "pass" : "fail", scheme ?? "missing from the selected build profile", scheme ? undefined : "Set ios.scheme in the selected build profile"));
-    const context = await probeProject(root, {
-        path: hostExists ? host : undefined,
-        flag: host ? projectFlag(host) : "-project",
-        scheme,
-    }, profile, target);
-    const settingsOutput = context.settings
-        ? commandOutput(context.settings)
-        : "";
-    checks.push(check("xcode-project-settings", !context.settings
-        ? "warn"
-        : context.settings.code === 0
-            ? "pass"
-            : "fail", !context.settings
-        ? "not inspected until host and scheme are configured"
-        : context.settings.code === 0
-            ? "scheme and configuration load successfully"
-            : "xcodebuild could not load the selected scheme", context.settings?.code === 0 || !context.settings
-        ? undefined
-        : "Open the project in Xcode and verify the scheme is shared and buildable"));
-    const automaticSigning = setting(settingsOutput, "CODE_SIGN_STYLE") === "Automatic";
-    const team = setting(settingsOutput, "DEVELOPMENT_TEAM");
-    checks.push(check("apple-team", simulator
-        ? "pass"
-        : context.settings?.code !== 0 || !context.settings
-            ? "warn"
-            : team
-                ? "pass"
-                : "fail", simulator
-        ? "not required for iOS Simulator"
-        : (team ?? "team not resolved from Xcode build settings"), simulator || team
-        ? undefined
-        : "Select the Apple Developer Team in Xcode Signing & Capabilities"));
-    const distribution = profile.distribution ?? profile.ios?.distribution ?? "store";
-    const identityResult = simulator
-        ? undefined
-        : await (commandExists("security")
-            ? captureProcess("security", ["find-identity", "-v", "-p", "codesigning"], {
-                cwd: root,
-            })
-            : undefined);
-    const identityOutput = identityResult ? commandOutput(identityResult) : "";
-    const identityCount = Number(identityOutput.match(/(\d+) valid identities found/)?.[1] ?? 0);
-    const requiredIdentity = distribution === "store" ? "Apple Distribution" : "Apple Development";
-    checks.push(check("apple-signing-identity", simulator
-        ? "pass"
-        : identityCount === 0 || !identityOutput.includes(requiredIdentity)
-            ? "fail"
-            : "pass", simulator
-        ? "not required for iOS Simulator"
-        : identityCount === 0
-            ? "no valid code-signing identity found"
-            : identityOutput.includes(requiredIdentity)
-                ? `${requiredIdentity} identity available`
-                : `${requiredIdentity} identity not found`, simulator ||
-        (identityCount > 0 && identityOutput.includes(requiredIdentity))
-        ? undefined
-        : "Install or select the Apple certificate in Xcode Settings > Accounts, then rerun doctor"));
-    const podfile = join(root, "ios", "Podfile");
-    const podRequired = existsSync(podfile);
-    const podVersion = podRequired
-        ? await probeVersion("pod", ["--version"], root)
-        : undefined;
-    checks.push(check("cocoapods", !podRequired || podVersion ? "pass" : "fail", !podRequired
-        ? "not required · no ios/Podfile"
-        : (podVersion ?? "Podfile found but pod is unavailable"), !podRequired || podVersion
-        ? undefined
-        : "gem install cocoapods, then run pod install in the project"));
-    let exportOptionsContent;
-    if (exportOptions && existsSync(exportOptions)) {
-        try {
-            exportOptionsContent = readFileSync(exportOptions, "utf8");
-        }
-        catch {
-            exportOptionsContent = undefined;
-        }
-    }
-    const exportMethod = exportOptionsContent?.match(/<key>method<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
-    const supportedExportMethods = new Set([
-        "app-store",
-        "ad-hoc",
-        "development",
-        "enterprise",
-    ]);
-    checks.push(check("export-options", simulator
-        ? "pass"
-        : !exportOptions
-            ? "fail"
-            : !existsSync(exportOptions)
-                ? "fail"
-                : !exportMethod || !supportedExportMethods.has(exportMethod)
-                    ? "fail"
-                    : "pass", simulator
-        ? "not required for iOS Simulator"
-        : !exportOptions
-            ? "missing from the production build profile"
-            : !existsSync(exportOptions)
-                ? `${exportOptions} not found`
-                : exportMethod && supportedExportMethods.has(exportMethod)
-                    ? `method: ${exportMethod}`
-                    : "method missing or invalid for an iOS export", simulator ||
-        (exportOptions &&
-            existsSync(exportOptions) &&
-            exportMethod &&
-            supportedExportMethods.has(exportMethod))
-        ? undefined
-        : "Set build.production.ios.exportOptionsPlist to a valid ExportOptions.plist"));
-    const manualProvisioning = setting(settingsOutput, "CODE_SIGN_STYLE") === "Manual" ||
-        exportOptionsContent?.includes("<key>provisioningProfiles</key>") === true;
-    const profilesAvailable = await hasValidProvisioningProfile(root, setting(settingsOutput, "PRODUCT_BUNDLE_IDENTIFIER"));
-    checks.push(check("ios-provisioning", simulator
-        ? "pass"
-        : manualProvisioning && !profilesAvailable
-            ? "fail"
-            : automaticSigning && !profilesAvailable
-                ? "warn"
-                : "pass", simulator
-        ? "not required for iOS Simulator"
-        : manualProvisioning && !profilesAvailable
-            ? "manual signing selected but no local provisioning profile was found"
-            : automaticSigning && !profilesAvailable
-                ? "Xcode-managed provisioning will be requested during the build"
-                : profilesAvailable
-                    ? "local provisioning profile available"
-                    : "not required by the detected signing mode", simulator || !(manualProvisioning && !profilesAvailable)
-        ? undefined
-        : "Download a matching .mobileprovision/.provisionprofile from Apple Developer and install it in Xcode"));
-    const simctlAvailable = await probeCommand("xcrun", ["--find", "simctl"], root);
-    const devicectlAvailable = await probeCommand("xcrun", ["--find", "devicectl"], root);
-    checks.push(check("ios-device-tools", simctlAvailable || devicectlAvailable ? "pass" : "warn", simctlAvailable && devicectlAvailable
-        ? "simctl and devicectl available"
-        : simctlAvailable
-            ? "simctl available · devicectl unavailable"
-            : devicectlAvailable
-                ? "devicectl available · simctl unavailable"
-                : "simctl and devicectl unavailable", simctlAvailable || devicectlAvailable
-        ? undefined
-        : "Install the full Xcode toolchain, then rerun lynxship doctor --platform ios"));
-    if (simulator) {
-        const runtimeResult = await (commandExists("xcrun")
-            ? captureProcess("xcrun", ["simctl", "list", "runtimes"], { cwd: root })
-            : undefined);
-        const runtimeOutput = runtimeResult ? commandOutput(runtimeResult) : "";
-        const hasRuntime = /iOS\s+[0-9]/.test(runtimeOutput);
-        checks.push(check("ios-simulator-runtime", hasRuntime ? "pass" : "fail", hasRuntime
-            ? "iOS Simulator runtime available"
-            : "no iOS Simulator runtime found", hasRuntime
-            ? undefined
-            : "Open Xcode > Settings > Components and install an iOS Simulator runtime"));
-    }
-    const failures = checks.filter((item) => item.status === "fail");
-    return {
-        ok: failures.length === 0,
-        checks,
-        project: host,
-        scheme,
-        automaticSigning,
-    };
-}
+export { inspectIosToolchain } from "./ios-toolchain/inspection.js";
 export function formatIosToolchainFailure(report) {
     return report.checks
         .filter((item) => item.status === "fail")

package/dist/plugins/contracts.d.ts

@@ -0,0 +1,28 @@
+import type { AutolinkContribution, BuildContribution, CloudIntegrationContribution, PluginCapability, PluginPermission, PluginPlanChange, 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[];
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/plugins/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/plugins/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,4BAA4B,EAC5B,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,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"}

package/dist/plugins/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/plugins/discovery.d.ts

@@ -0,0 +1,19 @@
+import type { Platform } from "@lynxship/contracts";
+import { type JsonObject, type LynxShipPluginDefinition, type PluginPlatform, type PluginReference } from "@lynxship/plugin-api";
+import type { LynxShipConfig } from "../config.js";
+import type { ProjectPluginInfo, PluginReport } from "./contracts.js";
+export interface ResolvedPlugin {
+    info: ProjectPluginInfo;
+    definition?: LynxShipPluginDefinition;
+}
+export declare function pluginReference(reference: PluginReference): {
+    name: string;
+    options: JsonObject;
+};
+export declare function resolvePlugin(root: string, reference: PluginReference, load?: boolean): Promise<ResolvedPlugin>;
+export declare function pluginReferences(config: LynxShipConfig): PluginReference[];
+export declare function inspectProjectPlugins(root: string, config: LynxShipConfig): Promise<PluginReport>;
+export declare function appliesToPlatform(platforms: readonly PluginPlatform[] | undefined, platform: Platform): boolean;
+export declare function mergeJson(left: JsonObject, right: JsonObject): JsonObject;
+export declare function safeProjectFile(root: string, file: string): string;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/plugins/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/plugins/discovery.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAuBtE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,CAAC,EAAE,wBAAwB,CAAC;CACvC;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,eAAe,GAAG;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;CACrB,CAGA;AA8FD,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,eAAe,EAC1B,IAAI,UAAO,GACV,OAAO,CAAC,cAAc,CAAC,CAgIzB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,EAAE,CAI1E;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EAChD,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAOT;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAkBzE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAYlE"}

package/dist/plugins/discovery.js

@@ -0,0 +1,250 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { capabilities, isKnownList, LYNXSHIP_PLUGIN_API_VERSION, KNOWN_CAPABILITIES, KNOWN_PERMISSIONS, permissions, validPluginDefinition, } from "./validation.js";
+export 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 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}`,
+        };
+    }
+}
+export 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",
+            },
+        };
+    }
+}
+export 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 };
+}
+export function appliesToPlatform(platforms, platform) {
+    return (!platforms ||
+        platforms.length === 0 ||
+        platforms.includes("all") ||
+        platforms.includes(platform));
+}
+export 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;
+}
+export 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;
+}

package/dist/plugins/native-operations.d.ts

@@ -0,0 +1,28 @@
+import type { Platform } from "@lynxship/contracts";
+import { type BuildContribution, type CloudIntegrationContribution, type JsonObject, type LynxShipPluginDefinition, type NativeFileOperation, type AutolinkContribution, type PluginPermission, type PluginPlanChange, type TemplateContribution } from "@lynxship/plugin-api";
+export interface OwnedNativeOperation {
+    plugin: string;
+    operation: NativeFileOperation;
+}
+declare function permissionForContribution(contribution: {
+    config?: JsonObject;
+    build?: BuildContribution;
+    native?: readonly NativeFileOperation[];
+    autolink?: AutolinkContribution;
+    templates?: readonly TemplateContribution[];
+    cloud?: readonly CloudIntegrationContribution[];
+}): PluginPermission[];
+export declare function assertPluginContribution(plugin: LynxShipPluginDefinition, contribution: unknown): asserts contribution is {
+    config?: JsonObject;
+    build?: BuildContribution;
+    native?: readonly NativeFileOperation[];
+    autolink?: AutolinkContribution;
+    templates?: readonly TemplateContribution[];
+    cloud?: readonly CloudIntegrationContribution[];
+};
+export declare function assertPluginPermissions(plugin: LynxShipPluginDefinition, contribution: Parameters<typeof permissionForContribution>[0]): void;
+export declare function inspectNativeOperation(root: string, owned: OwnedNativeOperation, platform: Platform): Promise<PluginPlanChange | undefined>;
+export declare function assertNativeConflicts(root: string, operations: readonly OwnedNativeOperation[]): void;
+export declare function applyNativeOperationsAtomically(root: string, operations: readonly OwnedNativeOperation[], platform: Platform): Promise<PluginPlanChange[]>;
+export {};
+//# sourceMappingURL=native-operations.d.ts.map