ingestron 0.12.0

package/build/cli/cli/output.js

@@ -0,0 +1,130 @@
+/** Presentation is deliberately separate from operation results. JSON is the
+ * lossless API; terminal output is bounded, plain text and actionable. Never
+ * serialise arbitrary plugin data or resolved bindings in the default summary. */
+import { friendlyReference } from "@ingestron/core/adapter";
+import { stringify } from "yaml";
+export function exitCode(result) {
+    if (result.ok)
+        return 0;
+    const codes = result.diagnostics.map((d) => d.code);
+    if (codes.includes("CANCELLED"))
+        return 130;
+    if (codes.includes("NOT_IMPLEMENTED"))
+        return 4;
+    if (codes.some((c) => ["STALE", "OWNER", "CONFLICT"].includes(c)))
+        return 5;
+    if (codes.some((c) => [
+        "INPUT",
+        "BINDING",
+        "CAPABILITY",
+        "PACKAGE",
+        "OPTION",
+        "COMMAND",
+        "SCHEMA",
+    ].includes(c)))
+        return 3;
+    return 2;
+}
+const clean = (value) => String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
+function lines(title, items, empty) {
+    if (!items.length)
+        return empty;
+    return `${title} (${items.length})\n${items
+        .slice(0, 20)
+        .map((i) => `  ${clean(i)}`)
+        .join("\n")}${items.length > 20 ? "\n  More results available with --json or --verbose." : ""}`;
+}
+export function terminal(result, verbose = false, args = {}) {
+    if (!result.ok)
+        return result.diagnostics
+            .map((d) => `Error: ${clean(d.message)}${verbose ? ` [${d.code}]` : ""}${d.file ? `\n  File: ${clean(d.file)}${clean(d.pointer ?? "")}` : ""}${d.hint ? `\n  Next: ${clean(d.hint)}` : ""}`)
+            .join("\n");
+    const value = result.result;
+    if (verbose)
+        return `${result.operation.replaceAll("_", " ")}\n${typeof value === "string" ? value : stringify(value).trimEnd()}`;
+    if (value?.apiVersion === "ingestron.change/v1")
+        return (lines("Proposed file changes", value.changes.map((c) => `${c.before === null ? "Create" : "Update"} ${c.path}`), "No file changes needed.") + "\nPreview only; no files changed.");
+    if (value?.applied)
+        return lines("Saved files", value.files, "No file changes needed.");
+    switch (result.operation) {
+        case "plugin_browse":
+            return ((value.length
+                ? "Installed plugins\n\n" +
+                    value
+                        .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");
+        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" +
+                value.evidence +
+                "\nInstall: ingestron plugin install <owner/repository>@<version>");
+        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>");
+        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":
+            return `Source ${clean(value.id)}\n  Type: ${clean(value.type)}${value.format ? ` (${clean(value.format)})` : ""}\n  Execution: ${clean(value.selected.execution)}\n  Environment: ${clean(value.selected.environment)}\n  Provider: ${clean(value.selected.provider ?? "project default")}\nUse --verbose to inspect connection references.`;
+        case "contract_list":
+            return lines("Contracts", value.map((c) => `${c.id}  ${c.status}  ${c.path}`), "No contracts drafted.\nNext: ingestron contract draft <name> --metadata <file>");
+        case "contract_show":
+            return (`Contract ${clean(value.id)} (${clean(value.status)})\n` +
+                lines("Entities", (value.schema ?? []).map((s) => `${s.physicalName ?? s.name}: ${(s.properties ?? []).length} fields`), "No entities.") +
+                "\nUse --verbose to review the complete contract.");
+        case "contract_check":
+            return `Contract valid: ${clean(value.path)}${value.status === "draft" ? "\nStatus: draft; review business requirements before use." : ""}\n${clean(value.evidence)}`;
+        case "contract_validate":
+            return `Contract valid for native table authoring (${value.columns.length} columns).`;
+        case "inspect":
+            return lines("Flows", value.flows.map((f) => `${f.id}  ${f.kind}  ${f.tables.length} tables, ${f.outputs.length} outputs`), "No flows configured.\nNext: ingestron flow add <name> --contract <name> --standard <standard>");
+        case "flow_show":
+            return `Flow ${clean(value.id)}\n  Kind: ${clean(value.kind)}\n  Tables: ${Object.keys(value.tables ?? {})
+                .map(clean)
+                .join(", ") || "none"}\n  Outputs: ${Object.keys(value.publishes ?? {})
+                .map(clean)
+                .join(", ") || "none"}\nUse --verbose to inspect configuration.`;
+        case "validate":
+            return value.mode === "draft"
+                ? `Draft configuration checked (${value.flows} flows).\n${value.pending.length} unresolved inputs. Strict build readiness has not been checked.`
+                : `Project checks passed${value.nodes === undefined ? "" : ` (${value.nodes} planned nodes)`}.\nValidation is local; no platform connection was tested.`;
+        case "doctor":
+            return `Project ${clean(value.project)} (${clean(value.environment)})\n${value.pending.length} unresolved inputs.\n${clean(value.platformAccess)}\nNext: ${clean(value.next)}`;
+        case "runtime_prepare":
+        case "run":
+        case "run_status":
+            return `Run ${clean(value.id)}: ${clean(value.status)} (${clean(value.action)}).\nTarget: ${clean(value.configuration)}; flows: ${value.flows.map(clean).join(", ")}.\nUse ingestron run status ${clean(value.id)} to inspect the receipt.`;
+        case "build":
+            return `Built ${value.packages?.length ?? 1} project package(s) into ${clean(value.directory)}.\n${clean(value.evidence)}`;
+        case "generate":
+            return "Generated native assets.\nUse check --output <directory> to verify local output.";
+        case "validate_output":
+            return "Generated output checks passed.\nOwnership and syntax checked locally; no platform connection was tested.";
+        case "environments":
+            return lines("Environments", value.available.map((e) => `${e}${e === value.selected ? " (selected)" : ""}`), "No environments configured.");
+        case "tables":
+            return lines("Flow tables", value.map((f) => `${f.flow}: ${f.tables.join(", ") || "none"}`), "No tables configured.");
+        case "catalogue":
+            return lines(args.kind ?? "Capabilities", value.map((v) => `${v.id}${v.version ? "@" + v.version : ""}${v.description ? "  " + v.description : ""}`), `No ${args.kind ?? "capabilities"} available.\nNext: ingestron plugin list`);
+        case "provider_commands":
+            return lines("Plugin operations", value.commands.map((c) => `${c.name}  ${c.description}`), "No plugin operations available.");
+        case "plugin_command":
+        case "provider_command":
+            return "Plugin operation completed locally.\nUse --json, --verbose or --out to inspect its result.";
+        case "plan":
+            return `Local build plan ready (${value.nodes.length} nodes).\nUse --json or --verbose to inspect the plan.`;
+        case "diff":
+            return `Local differences: ${value.added.length} added, ${value.changed.length} changed, ${value.removed.length} removed.`;
+        case "config_explain":
+            return `Configuration: ${clean(value.path)} (${clean(value.environment)})\nUse --verbose to inspect declared and resolved values.`;
+        case "resolve":
+            return `Resolved project ${clean(value.project.id)} (${value.flows.length} flows).\n${value.pending.length} unresolved inputs. Use --verbose to inspect configuration.`;
+        case "read":
+            return value.content;
+        case "schema":
+            return "Schema available. Use --json for tools or --verbose to inspect it.";
+    }
+    return `${result.operation.replaceAll("_", " ")} completed.\nUse --json for structured data or --verbose for details.`;
+}

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

@@ -0,0 +1,14 @@
+interface Browser {
+    select(message: string, options: {
+        value: string;
+        label: string;
+        hint?: string;
+    }[]): Promise<string>;
+    search(): Promise<string>;
+    details(text: string): void;
+}
+/** Read-only navigation of installed plugin metadata. */
+export declare function browsePlugins(ui: Browser, query?: string, initialKind?: string, filters?: {
+    engine?: string;
+}, root?: string): Promise<void>;
+export {};

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

@@ -0,0 +1,74 @@
+import { browseProviders, pluginKindLabel } from "@ingestron/core/adapter";
+/** Read-only navigation of installed plugin metadata. */
+export async function browsePlugins(ui, query = "", initialKind, filters = {}, root = process.cwd()) {
+    browseProviders(root, query, initialKind, filters); // Validate filters even when catalogue is empty.
+    let kind = initialKind;
+    let listing = !!query || !!kind;
+    let page = 0;
+    for (;;) {
+        if (!listing) {
+            const choice = await ui.select("Browse plugins", [
+                { value: "all", label: "Browse all plugins" },
+                { value: "search", label: "Search plugins" },
+                ...["provider", "model-pack", "activity-pack", "report-pack"].map((value) => ({ value, label: pluginKindLabel(value) })),
+                {
+                    value: "connector",
+                    label: "Connectors",
+                    hint: "Installed connector packages",
+                },
+                { value: "exit", label: "Finish browsing" },
+            ]);
+            if (choice === "exit")
+                return;
+            kind = ["all", "search"].includes(choice) ? undefined : choice;
+            query = choice === "search" ? await ui.search() : "";
+            listing = true;
+            page = 0;
+        }
+        const plugins = browseProviders(root, query, kind, filters);
+        const visible = plugins.slice(page * 25, (page + 1) * 25);
+        const selected = await ui.select(plugins.length
+            ? `Select a plugin (${plugins.length} results, page ${page + 1})`
+            : "No plugins match; change category or search", [
+            ...visible.map((p) => ({
+                value: p.reference,
+                label: `${p.name} [${p.kindLabel}]`,
+                hint: `${p.availability} · ${p.description}`,
+            })),
+            ...(page > 0 ? [{ value: ":previous", label: "Previous page" }] : []),
+            ...((page + 1) * 25 < plugins.length
+                ? [{ value: ":next", label: "Next page" }]
+                : []),
+            { value: ":search", label: "Search this category" },
+            { value: ":back", label: "Change category / browse all" },
+            { value: ":exit", label: "Finish browsing" },
+        ]);
+        if (selected === ":next") {
+            page++;
+            continue;
+        }
+        if (selected === ":previous") {
+            page--;
+            continue;
+        }
+        if (selected === ":exit")
+            return;
+        if (selected === ":back") {
+            listing = false;
+            continue;
+        }
+        if (selected === ":search") {
+            query = await ui.search();
+            page = 0;
+            continue;
+        }
+        const plugin = plugins.find((p) => p.reference === selected);
+        ui.details(`${plugin.name} (${plugin.id})\n${plugin.kindLabel} · ${plugin.availability}\n\n${plugin.description}\n${plugin.evidence}\n\nLicence: ${plugin.licence}\nDocumentation: ${plugin.documentation}\nSource and package documentation: ${plugin.url}\n\nExact-version licences/notices and provenance are saved to .ingestron/plugin-info/ during installation. Engine compatibility is package-specific; installed metadata is not runtime verification.`);
+        const action = await ui.select("Next step", [
+            { value: "back", label: "Back to results" },
+            { value: "exit", label: "Finish browsing" },
+        ]);
+        if (action === "exit")
+            return;
+    }
+}

package/build/cli/cli/presentation.d.ts

@@ -0,0 +1,12 @@
+import type { Context, OperationName, Result } from "@ingestron/core";
+export interface Presentation {
+    tty: boolean;
+    plain?: boolean;
+    colour?: boolean;
+    progress?: boolean;
+    json?: boolean;
+}
+export declare function richTerminal(options: Presentation, env?: NodeJS.ProcessEnv): boolean;
+export declare function decorate(text: string, ok: boolean, options: Presentation): string;
+export declare function banner(text: string, options: Presentation): string;
+export declare function backgroundOperation(context: Context, operation: OperationName, args: unknown, label: string, options: Presentation): Promise<Result>;

package/build/cli/cli/presentation.js

@@ -0,0 +1,57 @@
+import { Worker } from "node:worker_threads";
+export function richTerminal(options, env = process.env) {
+    return (options.tty &&
+        !options.json &&
+        !options.plain &&
+        options.colour !== false &&
+        env.NO_COLOR === undefined &&
+        env.TERM !== "dumb" &&
+        !env.CI);
+}
+export function decorate(text, ok, options) {
+    if (!richTerminal(options))
+        return text;
+    const [title, ...body] = text.split("\n");
+    return `\x1b[${ok ? "32" : "31"}m${ok ? "[ok]" : "[!]"}\x1b[0m \x1b[1m${title}\x1b[0m${body.length ? "\n" + body.join("\n") : ""}`;
+}
+export function banner(text, options) {
+    return richTerminal(options)
+        ? `\x1b[36m+-- INGESTRON ----------------------------------+\x1b[0m\n\n${text}`
+        : text;
+}
+export async function backgroundOperation(context, operation, args, label, options) {
+    const animate = richTerminal(options) &&
+        options.progress !== false &&
+        process.env.INGESTRON_NO_ANIMATION !== "1" &&
+        !!process.stderr.isTTY;
+    const frames = ["|", "/", "-", "\\"];
+    let index = 0;
+    const safe = label
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .slice(0, Math.max(20, (process.stderr.columns ?? 80) - 8));
+    const draw = () => process.stderr.write(`\r\x1b[2K  ${frames[index++ % frames.length]} ${safe}`);
+    if (animate)
+        draw();
+    const timer = animate ? setInterval(draw, 100) : undefined;
+    try {
+        return await new Promise((resolve, reject) => {
+            const worker = new Worker(new URL("./operation-worker.js", import.meta.url), { workerData: { context, operation, args } });
+            let received = false;
+            worker.once("message", (result) => {
+                received = true;
+                resolve(result);
+            });
+            worker.once("error", reject);
+            worker.once("exit", (code) => {
+                if (!received)
+                    reject(new Error(`Operation worker stopped (${code})`));
+            });
+        });
+    }
+    finally {
+        if (timer)
+            clearInterval(timer);
+        if (animate)
+            process.stderr.write("\r\x1b[2K");
+    }
+}

package/build/cli/cli/workflow-commands.d.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander";
+import { type Context, type OperationName, type Result } from "@ingestron/core";
+interface Host {
+    context: () => Context;
+    run: (name: OperationName, args?: any) => void;
+    author: (name: OperationName, args: any) => void;
+    print: (result: Result, args?: any) => void;
+    readData: (file: string) => any;
+    canPrompt: () => boolean;
+    answer: (value: unknown) => Promise<any>;
+    perform: (operation: OperationName, args: any, label: string) => Promise<Result>;
+}
+/** Implemented CLI workflows over the versioned core operation API. */
+export declare function workflowCommands(app: Command, host: Host): void;
+export {};