ingestron 0.12.1 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.13.1 — Node.js runtime compatibility
+
+- Require Node 22.12 or newer instead of excluding newer major versions. CI tests
+  Node 22.12.0, 22.23.2 and 24.12.0, including installed CLI and MCP workflows.
+- Pin core 0.12.1 so the transitive core package no longer warns on Node 24.
+
+## 0.13.0 — simpler plugin installation
+
+- CLI and MCP resolve official `github` and `local` names through shared adapter logic.
+  Omitted versions and `@latest` select qualified compatible releases, then pin exact
+  versions/commits. Repeated installs reuse locks; updates are explicit.
+- Installation now only caches packages. Register project providers separately with
+  `plugin configure`; `--cache-only` remains accepted and `install --name` gives a
+  migration diagnostic. Existing full references and custom tag prefixes still work.
+- Core remains pinned at 0.12.0; no source/provider runtime change is required.
+
 ## 0.12.1 — project-relative secret files
 
 - Use `run --secrets-file .env` instead of `--env-file`. Node interprets the old

package/README.md

@@ -10,7 +10,7 @@ the CLI does not install a platform provider or connect to a cloud account.
 
 ## Get started
 
-Use Node 22, Git and pnpm 10.15.0. Build the public source:
+Use Node 22.12 or newer, Git and pnpm 10.15.0. Build the public source:
 
 ```sh
 git clone https://github.com/ingestron/cli.git
@@ -29,13 +29,13 @@ To install this checkout's CLI in your terminal:
 
 ```sh
 pnpm pack --pack-destination build/release
-npm install --global ./build/release/ingestron-0.12.0.tgz
+npm install --global ./build/release/ingestron-0.13.1.tgz
 ingestron --version
 ```
 
 This source release prepares the npm package named `ingestron`; it does not claim
 that the same CLI version is already published on npm. Its core dependency is the
-public, exact version `@ingestron/core@0.12.0`.
+public, exact version `@ingestron/core@0.12.1`.
 
 Follow the [five-minute quickstart](docs/quickstart.md) for a project you can keep.
 
@@ -45,12 +45,14 @@ Commands use resource groups such as `source`, `contract`, `flow`, `config` and
 `plugin`. Installed plugins can add their own namespace:
 
 ```text
-ingestron plugin install owner/repository@1.2.3
+ingestron plugin install local
+ingestron plugin install github
 ingestron <namespace> <resource> <verb> --input request.json
 ```
 
-The repository/version above is a placeholder: use a compatible plugin you can
-access. Browse installed packages with `ingestron plugin browse`. Command help
+Installation caches an exact, qualified version without changing project configuration.
+Use `github@1.32.1` for an explicit pin, or `plugin update github` to check for a newer
+qualified release. Browse installed packages with `ingestron plugin browse`. Command help
 shows the selected plugin's input schema without executing it.
 
 - [Command reference](docs/commands.md) — implemented groups, options and errors.

package/THIRD_PARTY_NOTICES.md

@@ -75,7 +75,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-### @ingestron/core@0.12.0
+### @ingestron/core@0.12.1
 
 Declared licence: Apache-2.0
 

package/build/cli/cli/operation-worker.js

@@ -1,5 +1,5 @@
 /** Keep package-network work off the presentation thread so progress reflects
  * actual pending work. This worker uses the same JSON operations as MCP/Web. */
 import { parentPort, workerData } from "node:worker_threads";
-import { execute } from "@ingestron/core";
-parentPort.postMessage(execute(workerData.context, workerData.operation, workerData.args));
+import { executePluginOperation } from "./plugin-resolution.js";
+parentPort.postMessage(await executePluginOperation(workerData.context, workerData.operation, workerData.args));

package/build/cli/cli/output.js

@@ -54,7 +54,7 @@ export function terminal(result, verbose = false, args = {}) {
                         .map((p) => `  ${clean(p.id).padEnd(13)} ${clean(p.name)} [${clean(p.kindLabel)} · ${clean(p.availability)}]\n    ${clean(p.description)}\n    ${clean(p.url)}`)
                         .join("\n\n")
                 : "No installed plugins match this search.") +
-                "\n\nBrowse versions: ingestron plugin versions <owner/repository>\nGuided install: ingestron plugin install\nInstall: ingestron plugin install owner/repository@1.2.3");
+                "\n\nBrowse versions: ingestron plugin versions github\nGuided install: ingestron plugin install\nInstall: ingestron plugin install github");
         case "plugin_versions":
             return (lines(`Versions for ${value.provider}`, value.versions.map((v) => `${v.reference}${v.ambiguous ? "  (conflicting tags; select a commit)" : ""}`), "No stable version tags found.") +
                 "\n\n" +
@@ -63,7 +63,7 @@ export function terminal(result, verbose = false, args = {}) {
         case "packages_install":
             return `${value.cached ? "Using cached" : "Installed"} plugin ${clean(friendlyReference(args.reference ?? value.reference ?? "package"))}.${value.informationFile ? `\nPlugin information and licence evidence: ${clean(value.informationFile)}` : ""}`;
         case "packages_list":
-            return lines("Installed plugins", Object.keys(value.packages).map(friendlyReference), "No plugins installed.\nNext: ingestron plugin install <owner/repository>@<version>");
+            return lines("Installed plugins", Object.keys(value.packages).map(friendlyReference), "No plugins installed.\nNext: ingestron plugin install local");
         case "source_list":
             return lines("Sources", value.map((s) => `${s.id}  ${s.type}${s.format ? "/" + s.format : ""}  ${s.execution}`), "No sources configured.\nNext: ingestron source add <name> --type <type>");
         case "source_show":

package/build/cli/cli/plugin-resolution.d.ts

@@ -0,0 +1,22 @@
+/** Official-name convenience at the adapter boundary; core only receives exact references. */
+import { type Context, type OperationName, type Result } from "@ingestron/core";
+export declare const officialPlugins: {
+    readonly github: {
+        readonly repository: "ingestron/connectors";
+        readonly path: "connectors/github/connector.yaml";
+        readonly tagPrefix: "github-";
+    };
+    readonly local: {
+        readonly repository: "ingestron/provider-local";
+        readonly path: "plugin/provider.yaml";
+        readonly tagPrefix: "";
+    };
+};
+export declare function officialName(reference: string): {
+    name: keyof typeof officialPlugins;
+    version: string;
+} | undefined;
+export declare function catalogueReleases(value: any, name: keyof typeof officialPlugins, host?: string): string[];
+export declare function fetchCatalogue(): Promise<unknown>;
+export declare function resolvePluginArgs(context: Context, operation: OperationName, args: any, catalogue?: typeof fetchCatalogue): Promise<any>;
+export declare function executePluginOperation(context: Context, operation: OperationName, args?: any): Promise<Result>;

package/build/cli/cli/plugin-resolution.js

@@ -0,0 +1,164 @@
+/** Official-name convenience at the adapter boundary; core only receives exact references. */
+import { executeAsync, operationSchemas, } from "@ingestron/core";
+import { check, packageLock, Problem } from "@ingestron/core/adapter";
+import { coreVersion } from "../version.js";
+export const officialPlugins = {
+    github: {
+        repository: "ingestron/connectors",
+        path: "connectors/github/connector.yaml",
+        tagPrefix: "github-",
+    },
+    local: {
+        repository: "ingestron/provider-local",
+        path: "plugin/provider.yaml",
+        tagPrefix: "",
+    },
+};
+const catalogueUrl = "https://raw.githubusercontent.com/ingestron/connectors/main/catalogue.json";
+const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const compare = (a, b) => {
+    const x = a.split(".").map(Number), y = b.split(".").map(Number);
+    return y[0] - x[0] || y[1] - x[1] || y[2] - x[2];
+};
+export function officialName(reference) {
+    if (reference.includes("/"))
+        return undefined;
+    const [name, version, extra] = reference.split("@");
+    check(Object.hasOwn(officialPlugins, name), "PACKAGE", `Unknown official plugin '${name}'. Use github, local, or an explicit owner/repository reference.`);
+    check(extra === undefined &&
+        (version === undefined || version === "latest" || stable.test(version)), "PACKAGE", "Use a stable version, @latest, or omit the version for an official plugin");
+    return { name: name, version };
+}
+export function catalogueReleases(value, name, host = coreVersion) {
+    const identity = officialPlugins[name];
+    check(value?.apiVersion === "ingestron.catalogue/v1", "CATALOGUE", "Unsupported official catalogue format");
+    const entry = value.plugins?.[name];
+    check(entry &&
+        entry.repository === identity.repository &&
+        entry.path === identity.path &&
+        entry.tagPrefix === identity.tagPrefix &&
+        Array.isArray(entry.releases) &&
+        entry.releases.length <= 1000, "CATALOGUE", `Invalid official catalogue identity for ${name}`);
+    const seen = new Set();
+    for (const release of entry.releases) {
+        check(stable.test(release.version) &&
+            !seen.has(release.version) &&
+            Array.isArray(release.coreVersions) &&
+            release.coreVersions.length > 0 &&
+            release.coreVersions.every((v) => typeof v === "string" && stable.test(v)), "CATALOGUE", `Invalid qualified release for ${name}`);
+        seen.add(release.version);
+    }
+    return entry.releases
+        .filter((r) => r.coreVersions.includes(host))
+        .map((r) => r.version)
+        .sort(compare);
+}
+export async function fetchCatalogue() {
+    try {
+        const response = await fetch(catalogueUrl, {
+            signal: AbortSignal.timeout(10000),
+            redirect: "error",
+        });
+        check(response.ok && response.body, "CATALOGUE", "Official catalogue is unavailable; retry or install an explicit version");
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                check(size <= 262144, "CATALOGUE", "Official catalogue exceeds the size limit");
+                chunks.push(value);
+            }
+        }
+        finally {
+            await reader.cancel();
+        }
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof Problem)
+            throw error;
+        throw new Problem("CATALOGUE", "Cannot read the official catalogue; retry or install an explicit version");
+    }
+}
+export async function resolvePluginArgs(context, operation, args, catalogue = fetchCatalogue) {
+    if (operation !== "packages_install" && operation !== "plugin_versions")
+        return args;
+    const field = operation === "packages_install" ? "reference" : "provider";
+    const alias = officialName(args[field]);
+    if (!alias)
+        return args;
+    const identity = officialPlugins[alias.name];
+    check(args.tagPrefix === undefined || args.tagPrefix === identity.tagPrefix, "OPTION", "Official plugin tag prefixes cannot be overridden; use an explicit reference for custom tags");
+    if (operation === "plugin_versions")
+        return {
+            ...args,
+            provider: identity.repository,
+            tagPrefix: identity.tagPrefix,
+        };
+    // Check permissions before catalogue network access, just as core does before install.
+    check(context.allowWrite, "PERMISSION", "Package installation requires write access");
+    check(!(args.update && args.frozen), "PACKAGE", "Frozen installation cannot update packages");
+    const base = `${identity.repository}/${identity.path}@`;
+    let version = alias.version;
+    if (version === undefined || version === "latest") {
+        const installed = Object.keys(packageLock(context.root).packages)
+            .filter((r) => r.startsWith(base) && stable.test(r.slice(base.length)))
+            .map((r) => r.slice(base.length))
+            .sort(compare);
+        if (!args.update && installed.length)
+            version = installed[0];
+        else {
+            check(!args.frozen, "PACKAGE", "Frozen installation requires an existing exact lock; install an exact version first");
+            check(context.allowNetwork, "PERMISSION", "Latest plugin resolution requires explicit package-network access");
+            check(!args.fromGit, "OPTION", "Use an exact version with --from-git; latest selects official qualified releases");
+            const versions = catalogueReleases(await catalogue(), alias.name);
+            check(versions.length, "COMPATIBILITY", `No qualified ${alias.name} release supports core ${coreVersion}; update the CLI or select an explicitly compatible version`);
+            version = [...versions, ...installed].sort(compare)[0];
+        }
+    }
+    // Even 'update' must never retarget an existing immutable version lock.
+    return {
+        ...args,
+        reference: `${base}${version}`,
+        tagPrefix: identity.tagPrefix,
+        update: false,
+    };
+}
+export async function executePluginOperation(context, operation, args = {}) {
+    try {
+        if (operation === "packages_install" || operation === "plugin_versions") {
+            const parsed = operationSchemas[operation].safeParse(args);
+            check(parsed.success, "SCHEMA", "Invalid plugin operation arguments");
+            if (operation === "packages_install")
+                check(context.allowWrite, "PERMISSION", "Package installation requires write access");
+            check(context.allowNetwork || parsed.data?.fromGit, "PERMISSION", "Package access requires explicit package-network access");
+            args = await resolvePluginArgs(context, operation, parsed.data);
+        }
+        const result = await executeAsync(context, operation, args);
+        // Keep custom manifest paths in every returned installable reference.
+        if (operation === "plugin_versions" && result.ok) {
+            const identity = Object.values(officialPlugins).find((p) => p.repository === args.provider && p.tagPrefix === args.tagPrefix);
+            if (identity)
+                result.result.versions = result.result.versions.map((v) => ({
+                    ...v,
+                    reference: `${identity.repository}/${identity.path}@${v.version}`,
+                }));
+        }
+        return result;
+    }
+    catch (error) {
+        const e = error instanceof Problem
+            ? error
+            : new Problem("PACKAGE", "Plugin resolution failed; check the reference and catalogue");
+        return {
+            apiVersion: "ingestron.operation/v1",
+            operation,
+            ok: false,
+            diagnostics: [{ code: e.code, message: e.message }],
+        };
+    }
+}

package/build/cli/cli/workflow-commands.js

@@ -1,10 +1,7 @@
+import { officialName } from "./plugin-resolution.js";
 import { browsePlugins } from "./plugin-browser.js";
 import * as prompts from "@clack/prompts";
 import { friendlyReference } from "@ingestron/core/adapter";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { packageYaml, resolvePackage } from "@ingestron/core/adapter";
-import { execute, } from "@ingestron/core";
 import { check } from "@ingestron/core/adapter";
 /** Implemented CLI workflows over the versioned core operation API. */
 export function workflowCommands(app, host) {
@@ -179,16 +176,19 @@ export function workflowCommands(app, host) {
         .action((id) => run("run_status", { id }));
     // Installation is explicit; browsing only inspects installed packages.
     const installProvider = async (reference, options, update = false) => {
-        if (!reference || !reference.includes("@")) {
-            check(canPrompt(), "INPUT", "Choose an exact reference, e.g. plugin install owner/repository@1.2.3. Use plugin versions owner/repository to inspect tags.");
+        if (!reference) {
+            check(canPrompt(), "INPUT", "Choose an official plugin: plugin install github or plugin install local; explicit owner/repository@version references also work.");
+            reference = await answer(prompts.text({
+                message: "Official plugin name or owner/repository",
+                validate: (value) => /^(github|local|[\w.-]+\/[\w.-]+)$/.test(value ?? "")
+                    ? undefined
+                    : "Use github, local or owner/repository",
+            }));
+        }
+        check(typeof reference === "string", "INPUT", "Choose a plugin reference");
+        if (reference.includes("/") && !reference.includes("@")) {
+            check(canPrompt(), "INPUT", "Explicit repositories require an exact version: owner/repository@1.2.3. Official names github and local can omit the version.");
             check(!options.frozen, "OPTION", "Frozen installation requires an exact locked reference");
-            if (!reference)
-                reference = await answer(prompts.text({
-                    message: "Plugin GitHub repository (owner/repository)",
-                    validate: (value) => /^[\w.-]+\/[\w.-]+$/.test(value ?? "")
-                        ? undefined
-                        : "Use owner/repository",
-                }));
             const available = await perform("plugin_versions", {
                 provider: reference,
                 ...(options.fromGit ? { fromGit: options.fromGit } : {}),
@@ -210,6 +210,8 @@ export function workflowCommands(app, host) {
             }));
         }
         check(typeof reference === "string", "INPUT", "Choose a provider version");
+        officialName(reference);
+        check(!options.name, "OPTION", "Installation no longer configures projects. Use plugin configure <exact-reference> --name <configuration>.");
         const result = await perform("packages_install", {
             reference,
             update,
@@ -221,41 +223,7 @@ export function workflowCommands(app, host) {
             print(result);
             return;
         }
-        const provider = [
-            "ingestron.provider/v1",
-            "ingestron.connector/v1",
-        ].includes(packageYaml(resolvePackage(context().root, result.result.reference).file)
-            .apiVersion);
-        if (options.cacheOnly ||
-            !provider ||
-            !existsSync(resolve(context().root, "project.yaml"))) {
-            print(result, { reference });
-            return;
-        }
-        const proposal = execute(context(), "plugin_configure", {
-            reference,
-            update,
-            ...(options.name ? { name: options.name } : {}),
-        });
-        if (!proposal.ok) {
-            print(proposal);
-            return;
-        }
-        const applied = execute(context(), "apply", {
-            proposal: proposal.result,
-        });
-        if (!applied.ok) {
-            print(applied);
-            return;
-        }
-        print({
-            ...result,
-            result: {
-                ...result.result,
-                configured: true,
-                files: applied.result.files,
-            },
-        }, { reference });
+        print(result, { reference: result.result.reference });
     };
     const plugin = app
         .command("plugin")
@@ -288,7 +256,7 @@ export function workflowCommands(app, host) {
         .action((id) => run("plugin_show", { id }));
     plugin
         .command("versions <provider>")
-        .description("List exact version tags from GitHub; supports owner/repository")
+        .description("List stable tags for an official name or owner/repository; compatibility checked at install")
         .option("--from-git <directory>", "Inspect a local Git repository")
         .option("--tag-prefix <prefix>", "Component tag prefix in a shared repository")
         .action(async (provider, options) => print(await perform("plugin_versions", { provider, ...options }, `Finding versions for ${provider}`)));
@@ -299,12 +267,12 @@ export function workflowCommands(app, host) {
     for (const update of [false, true])
         plugin
             .command(`${update ? "update <reference>" : "install [reference]"}`)
-            .description("Install an exact version or choose interactively; register provider defaults")
+            .description("Cache a plugin without changing project configuration; official names default to latest qualified")
             .option("--from-git <directory>", "Local Git source")
             .option("--tag-prefix <prefix>", "Component tag prefix in a shared repository")
             .option("--frozen", "Require an existing immutable lock")
-            .option("--name <configuration>", "Provider configuration name (default: platform name)")
-            .option("--cache-only", "Install without changing project provider configuration")
+            .option("--name <configuration>", "Removed: use plugin configure --name instead")
+            .option("--cache-only", "Compatibility option; cache-only is now the default")
             .action((reference, options) => installProvider(reference, options, update));
     plugin
         .command("configure <reference>")

package/build/cli/mcp/index.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { execute, executeAsync, operationSchemas, } from "@ingestron/core";
+import { execute, operationSchemas } from "@ingestron/core";
+import { executePluginOperation } from "../cli/plugin-resolution.js";
 import { version } from "../version.js";
 export function createServer(root, allowWrite = false, environment = "dev", allowNetwork = false, allowExecute = false) {
     const server = new McpServer({ name: "ingestron", version }, {
@@ -32,7 +33,7 @@ export function createServer(root, allowWrite = false, environment = "dev", allo
                         ["plugin_versions", "packages_install"].includes(name)),
             },
         }, async (request) => {
-            const result = await executeAsync({ root, environment, allowWrite, allowNetwork, allowExecute }, name, request);
+            const result = await executePluginOperation({ root, environment, allowWrite, allowNetwork, allowExecute }, name, request);
             return {
                 content: [{ type: "text", text: JSON.stringify(result) }],
                 isError: !result.ok,

package/build/cli/version.d.ts

@@ -1 +1,2 @@
 export declare const version: string;
+export declare const coreVersion: string;

package/build/cli/version.js

@@ -11,3 +11,4 @@ while (!existsSync(join(root, "package.json")) ||
     root = parent;
 }
 export const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+export const coreVersion = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).dependencies["@ingestron/core"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ingestron",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "type": "module",
   "description": "Build repeatable data pipelines from reviewed contracts and versioned standards.",
   "license": "Apache-2.0",
@@ -20,11 +20,11 @@
     "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
-    "node": ">=22 <23"
+    "node": ">=22.12.0"
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ingestron/core": "0.12.0",
+    "@ingestron/core": "0.12.1",
     "@modelcontextprotocol/sdk": "1.30.0",
     "commander": "15.0.0",
     "yaml": "2.9.0"