@ingestron/cli 0.0.0-stage → 1.0.0

package/dist/sources.js

@@ -0,0 +1,103 @@
+// Where templates and standards come from: a built-in name, a folder, or a
+// Git URL cloned with the user's own git. Nothing from a source is run.
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+import { builtInTemplates, readTemplate } from "./templates.js";
+/** The URL without `user:password@`, for messages and the standard's "From" line. */
+export function withoutCredentials(text) {
+    return text.replace(/(\/\/)[^/@\s]+@/g, "$1");
+}
+/** Sources come from the user's command line; one starting with "-" could pass for a git option. */
+function refuseOption(spec) {
+    if (spec.startsWith("-"))
+        throw new Error(`A template or standard cannot start with "-": ${spec}.`);
+}
+/** A Git URL rather than a path or a name. */
+export function isGitUrl(spec) {
+    return (/^(https?|ssh|file|git):\/\//.test(spec) ||
+        /^[\w.-]+@[\w.-]+:/.test(spec) ||
+        /\.git(#|$)/.test(spec));
+}
+/** A template from a built-in name, a folder or a Git URL (`#` names a sub-folder). Call `done()` when finished. */
+export function templateSource(spec, cwd) {
+    refuseOption(spec);
+    if (isGitUrl(spec)) {
+        const { path, done } = cloned(spec, "folder");
+        try {
+            return { template: readTemplate(path, basename(path)), done };
+        }
+        catch (error) {
+            done();
+            throw error;
+        }
+    }
+    const folder = resolve(cwd, spec);
+    if (spec.includes("/") || spec.startsWith(".")) {
+        if (!existsSync(folder))
+            throw new Error(`No template folder ${spec}.`);
+        return { template: readTemplate(folder, basename(folder)), done: () => undefined };
+    }
+    const builtIns = builtInTemplates();
+    const template = builtIns.find((item) => item.name === spec);
+    if (!template) {
+        const names = builtIns.map((item) => item.name).join(", ");
+        throw new Error(`No template "${spec}". Built-in templates: ${names}.`);
+    }
+    return { template, done: () => undefined };
+}
+/** A standard file from a path or a Git URL with `#path/to/standard.yaml`. */
+export function standardSource(spec, cwd) {
+    if (!isGitUrl(spec)) {
+        const file = resolve(cwd, spec);
+        if (!existsSync(file))
+            throw new Error(`No standard file ${spec}.`);
+        return { file, source: spec, done: () => undefined };
+    }
+    const { path, done } = cloned(spec, "file");
+    return { file: path, source: withoutCredentials(spec), done };
+}
+/**
+ * Clones the URL before `#` into a temporary folder and returns the entry
+ * after `#`, which must really be inside the clone (no links) and be a
+ * regular file or folder as asked.
+ */
+function cloned(spec, kind) {
+    const [url = "", inside = ""] = spec.split("#");
+    if (inside.split("/").includes("..") || inside.startsWith("/"))
+        throw new Error(`The part after "#" must stay inside the repository: ${inside}.`);
+    const folder = mkdtempSync(join(tmpdir(), "ingestron-template-"));
+    const done = () => rmSync(folder, { recursive: true, force: true });
+    try {
+        clone(url, folder);
+        return { path: checkedEntry(folder, inside, kind), done };
+    }
+    catch (error) {
+        done();
+        throw error;
+    }
+}
+function clone(url, folder) {
+    // No hooks, no submodules; "--" so the URL can never be read as an option.
+    const args = ["-c", "core.hooksPath=/dev/null", "clone", "--depth", "1", "--quiet"];
+    try {
+        execFileSync("git", [...args, "--no-recurse-submodules", "--", url, folder], { stdio: "pipe" });
+    }
+    catch (error) {
+        const reason = error.stderr?.toString().trim() ?? String(error);
+        throw new Error(withoutCredentials(`Could not clone ${url}: ${reason}`));
+    }
+}
+function checkedEntry(folder, inside, kind) {
+    const path = join(folder, inside);
+    const stat = lstatSync(path, { throwIfNoEntry: false });
+    if (!stat)
+        throw new Error(`The repository has no "${inside}".`);
+    const real = relative(realpathSync(folder), realpathSync(path));
+    const isKind = kind === "file" ? stat.isFile() : stat.isDirectory();
+    if (!isKind || real.startsWith(".."))
+        throw new Error(`"${inside || "."}" in the repository is not a ${kind === "file" ? "regular file" : "folder"}.`);
+    return path;
+}
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

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

package/dist/templates.d.ts

@@ -0,0 +1,64 @@
+/** One question; the answer becomes `values.<value>` in project.yaml. */
+export interface Question {
+    value: string;
+    ask: string;
+    default: string;
+}
+/** A template folder and what it asks. */
+export interface Template {
+    name: string;
+    folder: string;
+    title: string;
+    summary: string;
+    questions: Question[];
+}
+/** template.yaml's schema, for editors; `readTemplate` checks the same rules. */
+export declare const templateSchema: {
+    title: string;
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        title: {
+            type: string;
+            description: string;
+        };
+        summary: {
+            type: string;
+            description: string;
+        };
+        questions: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    value: {
+                        type: string;
+                        pattern: string;
+                        description: string;
+                    };
+                    ask: {
+                        type: string;
+                        description: string;
+                    };
+                    default: {
+                        type: string;
+                        description: string;
+                    };
+                };
+            };
+        };
+    };
+};
+/** Where this package's built-ins are. */
+export declare const builtInFolder: string;
+/** Built-in templates: the starters, each named by its folder. */
+export declare function builtInTemplates(): Template[];
+/** Reads and checks `<folder>/template.yaml`; throws an Error with the reason. */
+export declare function readTemplate(folder: string, name: string): Template;
+/** Checks template.yaml's text; throws an Error with the reason. */
+export declare function parseTemplate(text: string, name: string, folder: string): Template;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAOA,yEAAyE;AACzE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B1B,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,aAAa,QAAkB,CAAC;AAE7C,kEAAkE;AAClE,wBAAgB,gBAAgB,IAAI,QAAQ,EAAE,CAM7C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAOnE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAalF"}

package/dist/templates.js

@@ -0,0 +1,88 @@
+// Project templates: an ordinary project folder plus template.yaml, which
+// says what to ask. Built-in templates are the samples' starters.
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { templatesFolder } from "./samples.js";
+/** template.yaml's schema, for editors; `readTemplate` checks the same rules. */
+export const templateSchema = {
+    title: "Ingestron template",
+    type: "object",
+    additionalProperties: false,
+    required: ["title", "summary"],
+    properties: {
+        title: { type: "string", description: "The template's name, as `ingestron init` lists it." },
+        summary: { type: "string", description: "One sentence on what the template sets up." },
+        questions: {
+            type: "array",
+            description: "What `ingestron init` asks; each answer becomes values.<value> in project.yaml.",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["value", "ask", "default"],
+                properties: {
+                    value: {
+                        type: "string",
+                        pattern: "^[a-z_][a-z0-9_]*$",
+                        description: "The key in project.yaml values.",
+                    },
+                    ask: { type: "string", description: "The question, as the user sees it." },
+                    default: {
+                        type: "string",
+                        description: "The answer used with --yes or an empty answer.",
+                    },
+                },
+            },
+        },
+    },
+};
+/** Where this package's built-ins are. */
+export const builtInFolder = templatesFolder;
+/** Built-in templates: the starters, each named by its folder. */
+export function builtInTemplates() {
+    return readdirSync(builtInFolder, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .filter((entry) => existsSync(join(builtInFolder, entry.name, "template.yaml")))
+        .map((entry) => readTemplate(join(builtInFolder, entry.name), entry.name))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Reads and checks `<folder>/template.yaml`; throws an Error with the reason. */
+export function readTemplate(folder, name) {
+    for (const required of ["template.yaml", "project.yaml"]) {
+        const stat = lstatSync(join(folder, required), { throwIfNoEntry: false });
+        if (!stat)
+            throw new Error(`Template "${name}" has no ${required}.`);
+        if (!stat.isFile())
+            throw new Error(`Template "${name}": ${required} is not a regular file.`);
+    }
+    return parseTemplate(readFileSync(join(folder, "template.yaml"), "utf8"), name, folder);
+}
+/** Checks template.yaml's text; throws an Error with the reason. */
+export function parseTemplate(text, name, folder) {
+    const data = parse(text);
+    const unknown = Object.keys(data ?? {}).find((key) => !["title", "summary", "questions"].includes(key));
+    if (unknown)
+        throw new Error(`template.yaml: unknown key "${unknown}".`);
+    return {
+        name,
+        folder,
+        title: String(data.title ?? name),
+        summary: String(data.summary ?? ""),
+        questions: questionsOf(data.questions),
+    };
+}
+function questionsOf(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("template.yaml: questions must be a list.");
+    return value.map((item, index) => {
+        const keys = ["value", "ask", "default"];
+        if (!keys.every((key) => typeof item?.[key] === "string"))
+            throw new Error(`template.yaml: question ${index + 1} needs "value", "ask" and "default".`);
+        if (!/^[a-z_][a-z0-9_]*$/.test(String(item.value)))
+            throw new Error(`template.yaml: question ${index + 1}'s value "${String(item.value)}" is not a valid name.`);
+        return { value: String(item.value), ask: String(item.ask), default: String(item.default) };
+    });
+}
+//# sourceMappingURL=templates.js.map

package/dist/templates.js.map

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

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@ingestron/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "ingestron plan | apply | check | schemas: generate platform assets from definitions.",
+  "license": "Apache-2.0",
+  "author": "IntentLabs <hello@ingestron.io>",
+  "homepage": "https://docs.ingestron.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ingestron/ingestron.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/ingestron/ingestron/issues",
+    "email": "hello@ingestron.io"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "ingestron": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "project-templates",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@ingestron/pack-adf": "^1.0.0",
+    "@ingestron/pack-databricks": "^1.0.0",
+    "yaml": "2.9.1",
+    "@ingestron/config": "1.0.0",
+    "@ingestron/definitions": "1.0.0",
+    "@ingestron/generate": "1.0.0"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "7.59.4",
+    "@types/node": "22.20.5",
+    "ajv": "8.20.0",
+    "eslint": "10.13.0",
+    "eslint-plugin-jsdoc": "65.4.2",
+    "tsx": "4.23.15",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.0",
+    "vitest": "5.0.5",
+    "vscode-languageserver-textdocument": "1.0.12",
+    "yaml-language-server": "1.25.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "pnpm build && tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "check:docs": "tsx scripts/check-docs.ts",
+    "validate": "pnpm lint && pnpm typecheck && pnpm test && pnpm check:docs && pnpm check:api",
+    "check:bundle": "tsx scripts/check-bundle-schema.ts",
+    "api": "api-extractor run --local",
+    "check:api": "api-extractor run"
+  }
 }

package/project-templates/kafka/README.md

@@ -0,0 +1,12 @@
+# Kafka
+
+Two topics of an Event Hubs namespace, read through its Kafka endpoint.
+[The ingestion pipeline](build/dev/resources/clickstream_events_ingestion.pipeline.yml)
+runs on the `PREVIEW` channel, appends every message, and parses JSON values
+with the contract's column types. In production it runs continuously; in
+`dev` it runs when started (`databricks bundle run`), which costs less. Set
+`continuous: true` to change that. The pack chose `mode: append`
+for Kafka by its own rule.
+
+Lakeflow Connect for Kafka is in Beta on Databricks (checked 2026-10-25); the
+generated file says so.

package/project-templates/kafka/connections/events.yaml

@@ -0,0 +1,8 @@
+apiVersion: ingestron.io/v1
+kind: Connection
+id: events
+description: Event Hubs namespace, used through its Kafka endpoint.
+connector: kafka
+connectivity: public
+settings:
+  uc_connection: web_events_kafka

package/project-templates/kafka/contracts/page_views.yaml

@@ -0,0 +1,13 @@
+apiVersion: v3.1.0
+kind: DataContract
+id: web.page_views
+version: 1.0.0
+status: active
+schema:
+  - name: page_views
+    logicalType: object
+    description: One event per page view.
+    properties:
+      - { name: session_id, logicalType: string, required: true }
+      - { name: url, logicalType: string }
+      - { name: viewed_at, logicalType: timestamp }

package/project-templates/kafka/contracts/purchases.yaml

@@ -0,0 +1,13 @@
+apiVersion: v3.1.0
+kind: DataContract
+id: web.purchases
+version: 1.0.0
+status: active
+schema:
+  - name: purchases
+    logicalType: object
+    description: One event per purchase.
+    properties:
+      - { name: order_id, logicalType: string, required: true }
+      - { name: amount, logicalType: number, physicalType: "DECIMAL(18,2)" }
+      - { name: purchased_at, logicalType: timestamp }

package/project-templates/kafka/flows/events.yaml

@@ -0,0 +1,10 @@
+apiVersion: ingestron.io/v1
+kind: Flow
+id: events
+source: events
+ingest:
+  # Keep append explicit when this flow is composed with a chosen ingestion method.
+  with: { starting_offset: earliest, mode: append }
+tables:
+  page_views: { object: web.page-views, contract: web.page_views }
+  purchases: { object: web.purchases, contract: web.purchases }

package/project-templates/kafka/project.yaml

@@ -0,0 +1,10 @@
+# Kafka topics streamed continuously with Lakeflow Connect (Beta), JSON
+# values parsed with the contract's types.
+id: clickstream
+environments:
+  dev: {}
+imports:
+  - standard.yaml
+  - connections/*.yaml
+  - flows/*.yaml
+  - contracts/*.yaml

package/project-templates/kafka/standard.yaml

@@ -0,0 +1,4 @@
+apiVersion: ingestron.io/v1
+kind: Standard
+id: web
+packs: [databricks@1]

package/project-templates/kafka/template.yaml

@@ -0,0 +1,3 @@
+# Used by `ingestron init --template kafka`.
+title: Kafka through Lakeflow Connect
+summary: Two Kafka topics appended and parsed with the contract's column types.

package/project-templates/minimal/README.md

@@ -0,0 +1,10 @@
+# Minimal
+
+The standard only names the pack, so every choice is a pack default.
+
+| Definition              | Becomes                                                                                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flows/orders.yaml`     | [a streaming table](build/dev/src/shop/bronze/orders.sql) reading new files once each                                                              |
+| `contracts/orders.yaml` | `schemaHints` from the column types, `COMMENT`, and a not-null check on the required `id`                                                          |
+| pack defaults           | catalog `dev` (the environment), schema `bronze` (the first layer), `CLUSTER BY AUTO`, parquet                                                     |
+| `project.yaml`          | [a bundle](build/dev/databricks.yml) with one `dev` target in development mode, and [a serverless pipeline](build/dev/resources/shop.pipeline.yml) |

package/project-templates/minimal/connections/shop.yaml

@@ -0,0 +1,7 @@
+apiVersion: ingestron.io/v1
+kind: Connection
+id: shop
+connector: files
+connectivity: public
+settings:
+  path: ${values.landing}

package/project-templates/minimal/contracts/orders.yaml

@@ -0,0 +1,14 @@
+apiVersion: v3.1.0
+kind: DataContract
+id: shop.orders
+version: 1.0.0
+status: active
+schema:
+  - name: orders
+    logicalType: object
+    description: One row per order.
+    properties:
+      - { name: id, logicalType: integer, required: true, primaryKey: true }
+      - { name: customer_id, logicalType: integer }
+      - { name: total, logicalType: number, physicalType: "DECIMAL(18,2)" }
+      - { name: ordered_at, logicalType: timestamp }

package/project-templates/minimal/flows/orders.yaml

@@ -0,0 +1,6 @@
+apiVersion: ingestron.io/v1
+kind: Flow
+id: orders
+source: shop
+tables:
+  orders: { object: orders, contract: shop.orders }

package/project-templates/minimal/project.yaml

@@ -0,0 +1,11 @@
+# The smallest project: everything not written here comes from the pack's defaults.
+id: shop
+values:
+  landing: /Volumes/dev/landing/shop
+environments:
+  dev: {}
+imports:
+  - standard.yaml
+  - connections/*.yaml
+  - flows/*.yaml
+  - contracts/*.yaml

package/project-templates/minimal/standard.yaml

@@ -0,0 +1,4 @@
+apiVersion: ingestron.io/v1
+kind: Standard
+id: defaults
+packs: [databricks@1]

package/project-templates/minimal/template.yaml

@@ -0,0 +1,7 @@
+# Used by `ingestron init --template minimal`.
+title: Minimal project
+summary: "Pack defaults only: an Auto Loader streaming table with schema hints and clustering."
+questions:
+  - value: landing
+    ask: "Where do the source files land?"
+    default: /Volumes/dev/landing/shop

package/project-templates/private-files/README.md

@@ -0,0 +1,29 @@
+# Private file share
+
+Each store exports its sales and stock as CSV files to a share inside the
+corporate network, `\\fs01\exports`, which the workspace cannot reach
+(`connectivity: private`). The standard uses two packs,
+`[databricks@1, adf@1]`. Databricks' `files` method cannot reach a private
+source, so the ADF pack's rule chooses `adf-files`:
+
+- **ADF** ([build/prod/adf](build/prod/adf/)), in the folder layout ADF
+  keeps in Git:
+  - a [file server linked service](build/prod/adf/linkedService/ls_stores_share.json)
+    through the self-hosted integration runtime `shir-stores`, with the
+    password from Key Vault;
+  - a [pipeline](build/prod/adf/pipeline/pl_stores_share.json) with one
+    binary copy per table: the files changed in the window, from
+    `\\fs01\exports\sales` to `<landing>/sales/`, keeping their names and
+    folders;
+  - an hourly [tumbling window trigger](build/prod/adf/trigger/tr_stores_share.json),
+    started in production and stopped elsewhere.
+- **Databricks** ([build/prod/databricks](build/prod/databricks/)): streaming
+  tables that read the landing folders with Auto Loader, as CSV with a
+  header, typed by the contracts' columns.
+
+The files are copied as they are, so the flow says their format
+(`format: csv`). To copy every file each window instead of the changed ones,
+set `mode: all`; to copy only some, set `files`, such as `"*.csv"`.
+
+The integration runtime and Key Vault are shared infrastructure: they must
+exist and are only referenced.

package/project-templates/private-files/connections/share.yaml

@@ -0,0 +1,10 @@
+apiVersion: ingestron.io/v1
+kind: Connection
+id: share
+description: The stores' export share, inside the corporate network only.
+connector: files
+connectivity: private
+settings:
+  path: '\\fs01\exports'
+  user: corp\ingest
+  password: ${secret:fs01-password} # a Key Vault secret name

package/project-templates/private-files/contracts/sales.yaml

@@ -0,0 +1,14 @@
+apiVersion: v3.1.0
+kind: DataContract
+id: stores.sales
+version: 1.0.0
+status: active
+schema:
+  - name: sales
+    logicalType: object
+    description: One row per sale, exported by each store every hour.
+    properties:
+      - { name: sale_id, logicalType: string, required: true, primaryKey: true }
+      - { name: store_id, logicalType: integer, required: true }
+      - { name: amount, logicalType: number, physicalType: "DECIMAL(18,2)" }
+      - { name: sold_at, logicalType: timestamp, required: true }

package/project-templates/private-files/contracts/stock.yaml

@@ -0,0 +1,14 @@
+apiVersion: v3.1.0
+kind: DataContract
+id: stores.stock
+version: 1.0.0
+status: active
+schema:
+  - name: stock
+    logicalType: object
+    description: Stock on hand per store and product, exported every hour.
+    properties:
+      - { name: store_id, logicalType: integer, required: true }
+      - { name: product_id, logicalType: integer, required: true }
+      - { name: on_hand, logicalType: integer }
+      - { name: counted_at, logicalType: timestamp, required: true }

package/project-templates/private-files/flows/stores.yaml

@@ -0,0 +1,9 @@
+apiVersion: ingestron.io/v1
+kind: Flow
+id: stores
+source: share
+ingest:
+  with: { format: csv, options: { header: true } } # the files' own format
+tables:
+  sales: { object: sales, contract: stores.sales }
+  stock: { object: stock, contract: stores.stock }

package/project-templates/private-files/platform.yaml

@@ -0,0 +1,11 @@
+apiVersion: ingestron.io/v1
+kind: Platform
+id: lakehouse
+schedule:
+  cron: 0 15 * * * ?
+  timezone: Pacific/Auckland
+settings:
+  adf-files: # shared infrastructure, referenced by name
+    landing: ${values.landing}
+    key_vault: ${values.key_vault}
+    integration_runtime: shir-stores

package/project-templates/private-files/project.yaml

@@ -0,0 +1,19 @@
+# Store exports on a file share inside the corporate network. ADF copies new
+# files through a self-hosted integration runtime into a landing folder as
+# they are; Databricks reads them there with Auto Loader.
+id: stores
+environments:
+  dev: {}
+  prod:
+    values:
+      landing: abfss://landing@storeslakeprod.dfs.core.windows.net/stores
+      key_vault: https://kv-stores-prod.vault.azure.net
+values:
+  landing: abfss://landing@storeslakedev.dfs.core.windows.net/stores
+  key_vault: https://kv-stores-dev.vault.azure.net
+imports:
+  - standard.yaml
+  - platform.yaml
+  - connections/*.yaml
+  - flows/*.yaml
+  - contracts/*.yaml

package/project-templates/private-files/standard.yaml

@@ -0,0 +1,11 @@
+apiVersion: ingestron.io/v1
+kind: Standard
+id: stores
+packs: [databricks@1, adf@1] # Databricks first: it provides the defaults
+naming:
+  catalog: stores_{{ environment }}
+ingest:
+  settings:
+    adf-files: # the schedule; where it lands is the platform's
+      every: { frequency: Hour, interval: 1 }
+      start: 2026-10-01T00:00:00Z