@ingestron/core 0.12.0

package/dist/assets/schemas/provenance.json

@@ -0,0 +1,16 @@
+[
+  {
+    "file": "odcs-3.1.0.json",
+    "source": "https://api.github.com/repos/bitol-io/open-data-contract-standard/git/blobs/fb74095224e367b6be7bb12d96a3624db2685c81",
+    "blob": "fb74095224e367b6be7bb12d96a3624db2685c81",
+    "sha256": "1a35de14c688b400fef306564f66e2af3304f057cd5cd6e7b847c1a8bf252c5b",
+    "accessed": "2026-09-06"
+  },
+  {
+    "file": "ODCS-LICENSE",
+    "source": "https://api.github.com/repos/bitol-io/open-data-contract-standard/git/blobs/261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64",
+    "blob": "261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64",
+    "sha256": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4",
+    "accessed": "2026-09-06"
+  }
+]

package/dist/compiler-fingerprint.json

@@ -0,0 +1,84 @@
+{
+  "files": {
+    "dist/assets/schemas/ODCS-LICENSE": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4",
+    "dist/assets/schemas/odcs-3.1.0.json": "1a35de14c688b400fef306564f66e2af3304f057cd5cd6e7b847c1a8bf252c5b",
+    "dist/assets/schemas/provenance.json": "4b5eb1fd89b81223f7946113b651d5a3a18adaa28948e43c3615dd851fb6844e",
+    "dist/core/authoring.js": "43025703f23b61090d1ea6912e387e5ed74a93568f068339f9a7ecae88795a51",
+    "dist/core/config.js": "b7e7138f7cc4a7b4ec8f6d0f0616c8802f2d802ec29aa09b40c1fc5c9324e016",
+    "dist/core/connections.js": "bd351bcb05275321078409b4de83648751a51e609ab5c5fc5489f1fe31433bcd",
+    "dist/core/connector-package.js": "c1d39fce629a524fa199ed5d0dffe6a36c500e1018fbb8379d700330372b46a7",
+    "dist/core/contracts.js": "a1b7fd28f776117cca86a25c6c70e852ff57ffea2bb9e7accbf2d583948d9dde",
+    "dist/core/deliveries.js": "a4d2cb1213bc4c02cffb962dcb943ba98e261d37cfb21041948ec637599db080",
+    "dist/core/delivery-exports.js": "d895b044c08f2059f0275724205120c72dd4bf5b74170bb01bdf42dd9d526d56",
+    "dist/core/development.js": "2b55b15d545172e527cf66868d96d97c5ca081d0a83892ffd253eadaa3cc1b39",
+    "dist/core/ecosystem-authoring.js": "782f20a08408af1c3c93ab27b521a86f2d6cddac042c2503cb58c4a76fdcd6fc",
+    "dist/core/errors.js": "8117e35fba84ae34627cb7d3bef46aaf6d8718c512140fa0ab08ccbdeeeec8c3",
+    "dist/core/execution.js": "496807e7428528e31e76d51144dfd84682d435467b30a35574310af525ddeca7",
+    "dist/core/extension-packs.js": "6b2aaa83e51f40e176cc4cfed574a4a17646bb3f526666fe8e0456d2912a8045",
+    "dist/core/fingerprint.js": "0edb56b544171ac20cc97fd58850eda5acefd3c725114b9d8bcc15b4971c5a36",
+    "dist/core/generate.js": "7f80617867186d216d49fcd91ebefb1807d7fe22c62b3b95ae311fe5096b08e8",
+    "dist/core/installation.js": "1eacb76525839743a2ebda9c24dc0a96edf485113fd4892e799663c60c31b548",
+    "dist/core/installed-plugins.js": "817ed411aef6f5b966a1828893081406805d2c8764d2ca20fd7e250e8a2168a8",
+    "dist/core/model-pack-schema.js": "e3eb7ff33ddc652643e3f896637de0034004cd0cf26b0e296a074f830ae0b870",
+    "dist/core/model-packs.js": "fee776ea0804dc66c9f140e57d94a3922d69c52d03c72079842ec43417616b0d",
+    "dist/core/operations.js": "bd6217f7eb33c3c5649f8edecab3ce87d4774c9ff790feff8763ebab71866531",
+    "dist/core/package-references.js": "bd3085eb6dcdac399d79af109d0a9e710a0532eba61e5298dc842aec9c7ef10a",
+    "dist/core/packages.js": "9c699b518a5c364c361d2b856f3fc6e67fe43ce0dc906b8aa474e341c5e49110",
+    "dist/core/planner.js": "f91902f4c37a7588965360fcddbda79301b59a0b66ef2f70c0378fa5dfcc7088",
+    "dist/core/project-build.js": "1f1002b4f6c506986c5aa6a5bb01ad5f3b4658a7a1319b65d79eaa67916fb994",
+    "dist/core/provider-commands.js": "8bd82821f6ed0eefce8216e7c03c271f28cb9f4bfda7724d5c1de6be1855e535",
+    "dist/core/provider-starter.js": "0ad05cbfed3d934196f82f8b50cb982314796ef9c5f012ad49935166e93e0fb0",
+    "dist/core/report-pack-schema.js": "fe8ecdc2b8deacd8b2a1e46588ee06744a7b6d8e7342786e320f74cc848665fa",
+    "dist/core/schema.js": "4cbad607f372584fe83f44a121bd978dea7529db5c1eb51168dcd62812c2eeab",
+    "dist/core/workflows.js": "1a5fe93b34d963efb07ab1f67641106386fa3ef9d9e80bd3e59c13795925fda6",
+    "dist/plugins/authoring.js": "ff985a7173c7aeda4a431a8603a4ab8631dc5134486578ede7d1301ebc3e6a19",
+    "dist/plugins/compatibility.js": "a6591cfa4ca5a324fd29856e51319e39be470d6ed835ee268b293727ce11f8b7",
+    "dist/plugins/generation.js": "7b0bae4de23edab4c2596d1f8ed2244d70b30fcae60395994b3964ffc845e9d5",
+    "dist/plugins/provider-renderer.js": "b05c469e19cfd57a47fb81e2dcf7fc01f27fcd09bdf2e6f5679a39e99365753f",
+    "dist/plugins/provider-worker.js": "ad66928002e95eefd0026c7d246e12e0b32f67e26f97164190f2c91518142602",
+    "dist/sdk/adapter.js": "d613c1ec890ce1a7384890a97cb50d3e272d34631a67c65d90349a227267df44",
+    "dist/sdk/index.js": "6d136aaf90903fbcc2de4b40fbed9f361472161c60fc5b1b8a9b9e5583ceefdd",
+    "dist/sdk/schemas.js": "7df73031cd262b2130e16861415873cd55086353f8b4b2a648a6910907e9f56e",
+    "dist/version.js": "48af2aa1e425f1e387c082bbf0ad2c0c8d757c468101a614c3864153a94e6889"
+  },
+  "sources": {
+    "src/core/authoring.ts": "fe80e823cfb82b39894aac9c5f733d489241b4a22bed278079254acff45a0aca",
+    "src/core/config.ts": "f282eb246438608e1951556dfeab9372daf65330a15a9d159d36d1f940370344",
+    "src/core/connections.ts": "19327f428382189a73a462cfd0b48943c0ba3b000633412b35da1d2ded81868b",
+    "src/core/connector-package.ts": "f302432c3954a6230ddf02e3ae796c0a641e52984c0db3bfbfc10b3d5539e49e",
+    "src/core/contracts.ts": "b7445086085b17d5ae8d5a7f4e2e849f286948e1a2a146ceb79660846e8616e5",
+    "src/core/deliveries.ts": "6be0a7059c057420ba22a5515703164a892fac9e79a5bdb0e0871ea0b92ddd15",
+    "src/core/delivery-exports.ts": "45a4d13e73a3809340fcd0f018dd06e2e360c67c1a117c672cd48be463c82d58",
+    "src/core/development.ts": "decd47d8f6ca3289fea45331f27b99b0feb7188ae0a9e152c6459cc00658e7bd",
+    "src/core/ecosystem-authoring.ts": "4c4385f2c9a3208d32e425183555916742a856dc6cc1bb44a806e94bb7537cba",
+    "src/core/errors.ts": "55e7ec3239bb3bcae73cf37e700cd83b9ea3336bf5514062827a3627a606977d",
+    "src/core/execution.ts": "44ebbe7b6f64e0c3c224dd6f419939e500de92b7e4e8b283b0b33266e1d1fbf1",
+    "src/core/extension-packs.ts": "76671a6971598212c9ec0bb0ce9b75feee13dec09565fa0adc9f050a6ae668ec",
+    "src/core/fingerprint.ts": "f74ebb99800a07975ec16618fb5c70d2a7d33ab3d4bb6de37c4a8ba211e9847e",
+    "src/core/generate.ts": "5efadcd0957f124f44fa1af082d8850da24956e6f802de2fea43b6cd4460ecd2",
+    "src/core/installation.ts": "fefd909eb9583cb6c51fad7de421cfcd1da86969bdc1cf47ba1cf83a70ca23f0",
+    "src/core/installed-plugins.ts": "951d15cdd8ca4a2c7d97fb01a46838822fe1b2fcf083ff8cf4bdca20d0997a2d",
+    "src/core/model-pack-schema.ts": "bc9b30ab257fd25766cba63aa2fb6891c05e4b3eccf56d820caaab2dcc4147b4",
+    "src/core/model-packs.ts": "a110d319f6feeff22a2d0d3a99ce5e49e56817d0cc27ab77d831d04a945ddfd3",
+    "src/core/operations.ts": "3f63b1a7bab027c81a8b27dc31094910df34af6ea333b5f12590b9cf85904cb4",
+    "src/core/package-references.ts": "5c5cee7e140158928e2e5a37f426520c7c2f042546a37eed4507d79326181f5a",
+    "src/core/packages.ts": "b32d52adf6d4c3673cc70b5bc8638e5986fe4790b9e9ac386e057561cec13b32",
+    "src/core/planner.ts": "498f5405f3088ee6d54ec8ab4a458813757697c150a56eab33f547aebb214da1",
+    "src/core/project-build.ts": "feb0fe50aff7b1fbdc8d96bcdb177a72a412639d1af98c3cff3b010de90a6428",
+    "src/core/provider-commands.ts": "f8a045230f61be0273910276b51e5c2e4bc0659f34c8a9361a38ab292c39eb4c",
+    "src/core/provider-starter.ts": "e0f50e2de10d7ec345f64ab3f7b0a08bd0e7df70f36b7d9ccaed78d98ce3a47e",
+    "src/core/report-pack-schema.ts": "cf2c68f3725cef847627ce61acd0887f04d0067bc324841d8a552bcb12d274b0",
+    "src/core/schema.ts": "dc1c5464878916bbdee08662320310bb202a21ebfca9e534a30746603c9aa46f",
+    "src/core/workflows.ts": "b8afae8637eb92b58ab41a41fc245950e1c8e8820a6a27358508ae54c04c7a78",
+    "src/plugins/authoring.ts": "a0d68d406b4569c0b48eec458407d24c3d4eeed5b7918c6c4fcb3828ada93fe5",
+    "src/plugins/compatibility.ts": "b5d357a1dc2a972cf8209311602f9fd816ba0a59cbe747f86f1b5567754073ea",
+    "src/plugins/generation.ts": "a495906af09cf7bf820c7aba390bf742d7e94328ce708a2ff40f613f451fe237",
+    "src/plugins/provider-renderer.ts": "ed7b498fd2b0e0a0111f428dcbeeb9561397dcd0f4a661a4de352ef469d84d3f",
+    "src/plugins/provider-worker.ts": "ce6b7b3dfc60e3ddd8f281e7f55eb6b46402be31429aacfd3d298bff4fce7a48",
+    "src/sdk/adapter.ts": "f3a7617498763a245b5d6f68441b6af9a8c1ee6ae3f9ced5ff641c0078436be2",
+    "src/sdk/index.ts": "60bcd61da2a15404024b7d7489774e95c5d69ed58c93ce1133cc5d6f6db27c93",
+    "src/sdk/schemas.ts": "8d40480c31bc14ee3e9e0a2d0646e6bdc136c790647826f87568cde5475e33bf",
+    "scripts/build-assets.mjs": "faa89a8b2e9eedbd02d0582c0cb6cc35c4b7b79d9b4940bb2e31ae739baea52e",
+    "src/version.ts": "c1d73f25230389b6f911e973feb1fd9b142cb6b34626cecad25820b5953df4a4"
+  }
+}

package/dist/core/authoring.d.ts

@@ -0,0 +1,55 @@
+export interface Change {
+    path: string;
+    before: string | null;
+    after: string;
+}
+export interface Proposal {
+    apiVersion: "ingestron.change/v1";
+    id: string;
+    revision: string;
+    changes: Change[];
+}
+export declare function preview(root: string, replacements: Record<string, string>): Proposal;
+export declare function apply(root: string, proposal: Proposal): {
+    applied: boolean;
+    proposalId: string;
+    files: string[];
+};
+export declare function initialise(root: string, options: {
+    id: string;
+    provider?: string;
+    environments?: string[];
+}): Proposal;
+export declare function migrateProvider(root: string, options: {
+    package: string;
+    to: string;
+}): Proposal;
+export declare function addFlow(root: string, options: {
+    id: string;
+    kind: "ingestion" | "transformation";
+    standard?: string;
+    sourceKind?: string;
+    format?: string;
+    sourceBinding?: string;
+    inputDataset?: string;
+    provider?: string;
+}): Proposal;
+export declare function addTable(root: string, options: {
+    flow: string;
+    id: string;
+    contract: string;
+}): Proposal;
+export declare function configureTable(root: string, flow: string, id: string, patch: Record<string, unknown>): Proposal;
+export declare function addDataset(root: string, options: {
+    flow: string;
+    id: string;
+    contract: string;
+    from: string;
+}): Proposal;
+export declare function addEnvironment(root: string, options: {
+    name: string;
+    from: string;
+}): Proposal;
+export declare function editValue(root: string, environment: string, pointer: string, value: unknown): Proposal;
+export declare function configureFlow(root: string, flow: string, patch: Record<string, unknown>): Proposal;
+export declare function addStep(root: string, flow: string, step: unknown, after?: string): Proposal;

package/dist/core/authoring.js

@@ -0,0 +1,315 @@
+import { friendlyReference } from "./package-references.js";
+import { providerAuthor, providerReference } from "../plugins/authoring.js";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, realpathSync, } from "node:fs";
+import { resolve, dirname, relative } from "node:path";
+import { parseDocument, stringify } from "yaml";
+import { check, digest, canonical, merge, Problem } from "./errors.js";
+import { Configuration } from "./config.js";
+import { contractColumns } from "./contracts.js";
+import { fence, installedProviders, canonicalPackageReference, } from "./packages.js";
+const yaml = (text, file) => {
+    const doc = parseDocument(text, { uniqueKeys: true });
+    check(!doc.errors.length, "YAML", doc.errors[0]?.message ?? "Invalid YAML", file);
+    return doc;
+};
+function revision(root) {
+    const lockFile = resolve(root, "packages.lock.yaml");
+    const lock = existsSync(lockFile) ? digest(readFileSync(lockFile)) : null;
+    if (!existsSync(resolve(root, "project.yaml")))
+        return digest(canonical({ project: null, lock }));
+    const reader = new Configuration(root);
+    reader.load();
+    return digest(canonical({ files: reader.files, lock }));
+}
+export function preview(root, replacements) {
+    root = resolve(root);
+    const changes = Object.entries(replacements)
+        .map(([name, after]) => {
+        const file = fence(root, name);
+        const before = existsSync(file) ? readFileSync(file, "utf8") : null;
+        return { path: name, before, after };
+    })
+        .filter((c) => c.before !== c.after);
+    const body = {
+        apiVersion: "ingestron.change/v1",
+        revision: revision(root),
+        changes,
+    };
+    return { ...body, id: digest(canonical(body)) };
+}
+export function apply(root, proposal) {
+    root = resolve(root);
+    const { id, ...body } = proposal;
+    check(id === digest(canonical(body)) &&
+        proposal.apiVersion === "ingestron.change/v1", "PROPOSAL", "Invalid change proposal");
+    check(revision(root) === proposal.revision, "STALE", "Project inputs changed since this proposal was reviewed");
+    check(Array.isArray(proposal.changes) && proposal.changes.length <= 1000, "PROPOSAL", "Invalid or oversized change list");
+    for (const change of proposal.changes)
+        check((change.path.split("/").at(-1) === ".gitignore" &&
+            !change.path
+                .split("/")
+                .slice(0, -1)
+                .some((part) => part.startsWith("."))) ||
+            (/\.(ya?ml|json|sql|py|m?js|md|txt|pbip|pbir|pbism|bim|svg|sql\.j2|py\.j2)$/.test(change.path) &&
+                !change.path.split("/").some((part) => part.startsWith("."))), "PATH", "Authoring applies only visible project configuration/source files");
+    for (const change of proposal.changes) {
+        const file = fence(root, change.path);
+        check((existsSync(file) ? readFileSync(file, "utf8") : null) === change.before, "STALE", `File changed since preview: ${change.path}`);
+    }
+    mkdirSync(root, { recursive: true });
+    const guard = fence(root, ".ingestron-write.lock");
+    try {
+        writeFileSync(guard, id, { flag: "wx" });
+    }
+    catch {
+        throw new Problem("CONFLICT", "Another authoring operation is active");
+    }
+    const written = [];
+    try {
+        check(revision(root) === proposal.revision, "STALE", "Project changed while waiting for write access");
+        for (const change of proposal.changes) {
+            const file = fence(root, change.path);
+            check((existsSync(file) ? readFileSync(file, "utf8") : null) ===
+                change.before, "STALE", `File changed: ${change.path}`);
+        }
+        for (const change of proposal.changes) {
+            const file = fence(root, change.path);
+            mkdirSync(dirname(file), { recursive: true });
+            const temp = file + `.edit-${process.pid}`;
+            writeFileSync(temp, change.after, { flag: "wx" });
+            try {
+                renameSync(temp, file);
+                written.push(change);
+            }
+            finally {
+                rmSync(temp, { force: true });
+            }
+        }
+    }
+    catch (error) {
+        for (const change of written.reverse()) {
+            const file = fence(root, change.path);
+            check(readFileSync(file, "utf8") === change.after, "CONFLICT", `Rollback stopped because ${change.path} changed externally`);
+            if (change.before === null)
+                rmSync(file);
+            else
+                writeFileSync(file, change.before);
+        }
+        throw error;
+    }
+    finally {
+        rmSync(guard, { force: true });
+    }
+    return { applied: true, proposalId: id, files: written.map((c) => c.path) };
+}
+export function initialise(root, options) {
+    check(/^[A-Za-z_][\w-]*$/.test(options.id), "PROJECT", "Invalid project ID");
+    const environments = options.environments ?? ["dev", "test", "prod"];
+    check(environments.length > 0 &&
+        new Set(environments).size === environments.length &&
+        environments.every((e) => /^[A-Za-z_][\w-]*$/.test(e)), "ENVIRONMENT", "Use distinct environment identifiers");
+    mkdirSync(root, { recursive: true });
+    if (!options.provider) {
+        const files = {
+            "project.yaml": stringify({
+                apiVersion: "ingestron.project/v1",
+                id: options.id,
+                providers: { packages: {}, configurations: {} },
+                defaults: {},
+                environments: Object.fromEntries(environments.map((name) => [
+                    name,
+                    { $resolve: `./environments/${name}.yaml` },
+                ])),
+                flows: [],
+            }),
+            ".gitignore": "build/\n.ingestron/\n.local/\n",
+        };
+        for (const name of environments)
+            files[`environments/${name}.yaml`] = stringify({
+                apiVersion: "ingestron.environment/v1",
+                environment: name,
+                values: {},
+                bindings: {},
+            });
+        for (const name of Object.keys(files))
+            check(!existsSync(resolve(root, name)), "OWNER", `Initialisation would replace existing ${name}`);
+        return preview(root, files);
+    }
+    let reference = options.provider;
+    if (!reference.includes("@")) {
+        const source = canonicalPackageReference(`${reference}@0.0.0`).split("@")[0];
+        const matches = installedProviders(root).filter((p) => p.reference.split("@")[0] === source);
+        check(matches.length > 0, "PACKAGE", `No installed provider ${reference}; use plugin install ${reference} first`);
+        check(matches.length === 1, "PACKAGE", `Multiple installed versions of ${reference}; use an exact reference: ${matches.map((p) => friendlyReference(p.reference)).join(", ")}`);
+        reference = matches[0].reference;
+    }
+    const files = providerAuthor(root, reference, { operation: "initialise", options: { ...options, environments } }, (name) => name === "project.yaml" ||
+        name === "README.md" ||
+        name === ".gitignore" ||
+        /^environments\/[\w-]+\.yaml$/.test(name));
+    check(files["project.yaml"], "PROVIDER", "Provider must author a project");
+    // Providers may return JSON (valid YAML); editable scaffolds use block YAML.
+    for (const [name, text] of Object.entries(files)) {
+        if (name.endsWith(".yaml"))
+            files[name] = stringify(yaml(text, name).toJS());
+    }
+    for (const name of Object.keys(files))
+        check(!existsSync(resolve(root, name)), "OWNER", `Initialisation would replace existing ${name}`);
+    return preview(root, files);
+}
+export function migrateProvider(root, options) {
+    const reader = new Configuration(root), doc = yaml(reader.text("project.yaml"), "project.yaml");
+    check(doc.hasIn(["providers", "packages", options.package]), "PACKAGE", "Unknown project package");
+    const selected = providerReference(root, options.to);
+    doc.setIn(["providers", "packages", options.package], {
+        source: selected.source,
+        version: selected.version,
+    });
+    return preview(root, { "project.yaml": doc.toString() });
+}
+function flowFile(root, id) {
+    const projectFile = resolve(root, "project.yaml"), project = yaml(readFileSync(projectFile, "utf8"), projectFile).toJS();
+    const reader = new Configuration(root);
+    for (const reference of project.flows ?? []) {
+        check(reference.$resolve, "AUTHORING", "Editable flows must be in their own referenced flow.yaml");
+        const file = reader.path(reference.$resolve);
+        const doc = yaml(reader.text(file), file);
+        if (doc.get("id") === id)
+            return { file, doc, projectFile, project };
+    }
+    throw new Problem("FLOW", `Unknown flow ${id}`);
+}
+export function addFlow(root, options) {
+    const reader = new Configuration(root), project = yaml(reader.text("project.yaml"), "project.yaml"), raw = project.toJS(), resolved = reader.load();
+    check(/^[A-Za-z_][\w-]*$/.test(options.id), "FLOW", "Invalid flow ID");
+    check(!resolved.flows.some((f) => f.id === options.id), "OWNER", `Flow ${options.id} already exists`);
+    const configuration = options.provider ?? resolved.defaults.provider;
+    const config = resolved.providers.configurations[configuration];
+    check(config, "PROVIDER", "Select a provider configuration for this flow");
+    const pkg = resolved.providers.packages[config.package];
+    const environments = Object.values(raw.environments).map((ref) => {
+        check(ref.$resolve, "AUTHORING", "Keep editable environments in referenced files");
+        const file = reader.path(ref.$resolve);
+        return {
+            path: relative(reader.root, file),
+            text: reader.text(file),
+            value: yaml(reader.text(file), file).toJS(),
+        };
+    });
+    const files = providerAuthor(root, `${pkg.source}@${pkg.version}`, {
+        operation: "flow",
+        options,
+        configuration,
+        project: resolved,
+        environments,
+    }, (name) => name.startsWith(`flows/${options.id}/`) ||
+        environments.some((e) => e.path === name));
+    const file = `flows/${options.id}/flow.yaml`;
+    check(files[file], "PROVIDER", "Provider must author the requested flow");
+    check(!existsSync(resolve(root, file)), "OWNER", `Existing flow file ${file}`);
+    project.set("flows", [...raw.flows, { $resolve: "./" + file }]);
+    files["project.yaml"] = project.toString();
+    return preview(root, files);
+}
+export function addTable(root, options) {
+    const { file, doc } = flowFile(root, options.flow);
+    check(doc.get("kind") === "ingestion", "FLOW", "table add requires an ingestion flow");
+    check(/^[A-Za-z_][\w-]*$/.test(options.id), "TABLE", "Invalid table ID");
+    check(!doc.hasIn(["tables", options.id]), "OWNER", `Table ${options.id} already exists`);
+    const reader = new Configuration(root), contract = reader.load(options.contract), target = `flows/${options.flow}/01-ingest/contracts/${options.id}.odcs.yaml`;
+    contractColumns(contract);
+    const table = {
+        contract: { $resolve: `./01-ingest/contracts/${options.id}.odcs.yaml` },
+    };
+    doc.setIn(["tables", options.id], table);
+    return preview(root, {
+        [relative(realpathSync(root), file)]: doc.toString(),
+        [target]: stringify(contract),
+    });
+}
+export function configureTable(root, flow, id, patch) {
+    const { file, doc } = flowFile(root, flow);
+    check(doc.hasIn(["tables", id]), "TABLE", `Unknown table ${id}`);
+    check(!("id" in patch) && !("contract" in patch), "AUTHORING", "Identity/contract changes require an explicit file edit");
+    doc.setIn(["tables", id], merge(doc.toJS().tables[id], patch));
+    return preview(root, {
+        [relative(realpathSync(root), file)]: doc.toString(),
+    });
+}
+export function addDataset(root, options) {
+    const { file, doc } = flowFile(root, options.flow);
+    check(doc.get("kind") === "transformation", "FLOW", "dataset add requires a transformation flow");
+    check(!doc.hasIn(["publishes", options.id]), "OWNER", "Dataset already exists");
+    const reader = new Configuration(root), contract = reader.load(options.contract);
+    contractColumns(contract);
+    const target = `flows/${options.flow}/contracts/${options.id}.odcs.yaml`;
+    doc.setIn(["publishes", options.id], {
+        from: options.from,
+        contract: { $resolve: `./contracts/${options.id}.odcs.yaml` },
+    });
+    return preview(root, {
+        [relative(realpathSync(root), file)]: doc.toString(),
+        [target]: stringify(contract),
+    });
+}
+export function addEnvironment(root, options) {
+    check(/^[A-Za-z_][\w-]*$/.test(options.name) &&
+        !["__proto__", "constructor", "prototype"].includes(options.name), "ENVIRONMENT", "Invalid environment identifier");
+    const reader = new Configuration(root);
+    const project = yaml(reader.text("project.yaml"), "project.yaml");
+    const raw = project.toJS();
+    check(raw.environments && !Object.hasOwn(raw.environments, options.name), "OWNER", `Environment ${options.name} already exists`);
+    check(Object.hasOwn(raw.environments, options.from), "ENVIRONMENT", `Unknown source environment ${options.from}`);
+    const source = raw.environments[options.from];
+    check(typeof source?.$resolve === "string", "ENVIRONMENT", "The source environment must be in a referenced file");
+    // Copy beside the source so every relative reference keeps its meaning.
+    const sourceFile = reader.path(source.$resolve);
+    const destination = resolve(dirname(sourceFile), `${options.name}.yaml`);
+    const target = relative(reader.root, destination);
+    fence(reader.root, target);
+    check(!existsSync(destination), "OWNER", `Existing environment file ${target}`);
+    const profile = yaml(reader.text(sourceFile), sourceFile);
+    check(profile.toJS()?.apiVersion === "ingestron.environment/v1", "ENVIRONMENT", "Expected an environment document");
+    profile.set("environment", options.name);
+    project.setIn(["environments", options.name], { $resolve: "./" + target });
+    return preview(root, {
+        [target]: profile.toString(),
+        "project.yaml": project.toString(),
+    });
+}
+export function editValue(root, environment, pointer, value) {
+    const reader = new Configuration(root), project = yaml(reader.text("project.yaml"), "project.yaml").toJS(), selected = project.environments[environment];
+    check(selected?.$resolve, "ENVIRONMENT", "Environment values must be in a referenced environment file for editing");
+    const file = reader.path(selected.$resolve), doc = yaml(reader.text(file), file);
+    const keys = pointer.split(".");
+    check(keys.length &&
+        ["values", "bindings"].includes(keys[0]) &&
+        keys.every((k) => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(k)), "CONFIG", "Use a values.* or bindings.* field path");
+    doc.setIn(keys, value);
+    return preview(root, { [relative(reader.root, file)]: doc.toString() });
+}
+export function configureFlow(root, flow, patch) {
+    const { file, doc } = flowFile(root, flow);
+    check(!["apiVersion", "id", "kind", "tables", "steps"].some((k) => k in patch), "AUTHORING", "Use dedicated table/step commands for structural changes");
+    return preview(root, {
+        [relative(realpathSync(root), file)]: stringify(merge(doc.toJS(), patch)),
+    });
+}
+export function addStep(root, flow, step, after) {
+    const { file, doc } = flowFile(root, flow);
+    const value = step;
+    check(doc.toJS().kind === "transformation", "FLOW", "Ingestion steps are owned by the standard; use a transformation flow");
+    {
+        const steps = doc.toJS().steps ?? [];
+        check(!steps.some((s) => s.id === value.id), "OWNER", "Step already exists");
+        const at = after
+            ? steps.findIndex((s) => s.id === after)
+            : steps.length - 1;
+        check(!after || at >= 0, "STEP", `Unknown predecessor ${after}`);
+        steps.splice(at + 1, 0, step);
+        doc.set("steps", steps);
+    }
+    return preview(root, {
+        [relative(realpathSync(root), file)]: doc.toString(),
+    });
+}

package/dist/core/config.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export type Location = {
+    file: string;
+    pointer: string;
+    line: number;
+    column: number;
+};
+export declare class Configuration {
+    readonly environmentVariables: Record<string, string | undefined>;
+    readonly root: string;
+    readonly files: Record<string, string>;
+    readonly locations: WeakMap<object, Location>;
+    readonly inputs: Record<string, string>;
+    readonly pending: {
+        name: string;
+        file?: string;
+        pointer?: string;
+    }[];
+    private bytes;
+    private nodes;
+    private documents;
+    constructor(root: string, environmentVariables?: Record<string, string | undefined>);
+    path(name: string, from?: string): string;
+    text(name: string, from?: string): string;
+    private document;
+    load(name?: string, from?: string, stack?: string[], depth?: number): any;
+    private walk;
+    parse<T>(schema: z.ZodType<T>, value: unknown): T;
+    values(value: any, context: Record<string, any>, options?: {
+        draft?: boolean;
+        table?: boolean;
+        runtime?: boolean;
+    }): any;
+}