2.2: @ingestron/core, ProjectSnapshot and ingestron@2.2.0

ci-templates/azure-devops/azure-pipelines.yml

@@ -33,7 +33,7 @@ stages:
               version: 22.x
           # An exact version: change it when you upgrade, as
           # https://docs.ingestron.io/docs/how-to/upgrade#choose-the-version-you-run says.
-          - script: npm install -g ingestron@2.1.0
+          - script: npm install -g ingestron@2.2.0
             displayName: Install Ingestron
           - script: ingestron check
             displayName: ingestron check

ci-templates/azure-devops/ingestron-check.yml

@@ -15,7 +15,7 @@ steps:
       version: 22.x
   # An exact version: change it when you upgrade, as
   # https://docs.ingestron.io/docs/how-to/upgrade#choose-the-version-you-run says.
-  - script: npm install -g ingestron@2.1.0
+  - script: npm install -g ingestron@2.2.0
     displayName: Install Ingestron
   - script: ingestron check
     displayName: ingestron check

ci-templates/github-actions/deploy.yml

@@ -29,7 +29,7 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
-      - run: npm install -g ingestron@2.1.0
+      - run: npm install -g ingestron@2.2.0
       - run: ingestron check
 
   build:

ci-templates/github-actions/ingestron-check.yml

@@ -18,5 +18,5 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
-      - run: npm install -g ingestron@2.1.0
+      - run: npm install -g ingestron@2.2.0
       - run: ingestron check

components/reference/built-in-templates.tsx

@@ -1,5 +1,5 @@
 // The templates `ingestron init` offers, from the CLI itself.
-import { builtInTemplates } from "@ingestron/cli";
+import { builtInTemplates } from "@ingestron/core";
 import { TableFrame } from "@/components/table-frame";
 
 /** One row per built-in template: its name and what it sets up. `init` asks none of them anything. */

components/reference/connector-facts.tsx

@@ -1,6 +1,6 @@
 // Routes stay in package metadata; the sections below them on the page give the detail.
 import { Fragment, type ReactNode } from "react";
-import { projectRoutes } from "@ingestron/cli";
+import { projectRoutes } from "@ingestron/core";
 import { ingestionRows } from "@/lib/connector-settings";
 import { listExamples } from "@/lib/examples";
 import { connectorEntries, packName, type ConnectorEntry } from "@/lib/reference";

components/reference/project-sources.tsx

@@ -1,6 +1,6 @@
 // Discovery uses the same metadata as the CLI and New project wizard. Headings
 // are MDX's own, so a jump to a category clears the sticky header.
-import { projectSources, projectRoutes } from "@ingestron/cli";
+import { projectSources, projectRoutes } from "@ingestron/core";
 import { Heading } from "fumadocs-ui/components/heading";
 import { categoryAnchor, sourceCategories } from "@/lib/connector-page";
 

components/reference/related-setup.tsx

@@ -1,5 +1,5 @@
 // The routes and their packs come from New project's metadata; link text is each page's title.
-import { projectRoutes } from "@ingestron/cli";
+import { projectRoutes } from "@ingestron/core";
 import { connectorEntries, packName, packs, pageTitle, routePacks } from "@/lib/reference";
 import { routeGuides } from "@/lib/routes";
 

components/reference/route-comparison.tsx

@@ -1,5 +1,5 @@
 // A compact comparison uses the same supported routes as New project.
-import { projectRoutes, projectSources } from "@ingestron/cli";
+import { projectRoutes, projectSources } from "@ingestron/core";
 import { allRoutes } from "@/lib/reference";
 import { TableFrame } from "@/components/table-frame";
 

components/reference/versions.tsx

@@ -30,6 +30,7 @@ function found(text: string, pattern: RegExp, what: string): string {
 export function PackageVersions() {
   const rows: [string, string][] = [
     ["@ingestron/cli", "the `ingestron` command"],
+    ["@ingestron/core", "the API the command is built on"],
     ["@ingestron/definitions", "loading and resolving definitions"],
     ["@ingestron/authoring", "editor features"],
     ...packs.map((pack): [string, string] => [

components/reference/vscode-extension.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.8.0"
+  "version": "2.1.4"
 }

content/docs/(reference)/reference/cli.mdx

@@ -59,10 +59,14 @@ as `databricks → build/databricks (dev, prod)`; see
 ## Use the command from code
 
 The CLI package is also a library: `run` takes the same arguments as the
-command, `generatedOutputs` gives every output folder's files as `plan` would
-write them, and `projectSources`, `projectRoutes` and `projectRecipe` return
-the sources, routes and recipes that `init` and **Ingestron: New project**
-offer.
+command. The
+[`@ingestron/cli` README](https://github.com/ingestron/ingestron/tree/main/packages/cli#in-code)
+describes it.
+
+The command is built on `@ingestron/core`, which your code can use too:
+`generatedOutputs` gives every output folder's files as `plan` would write
+them, and `projectSources`, `projectRoutes` and `projectRecipe` return the
+sources, routes and recipes that `init` and **Ingestron: New project** offer.
 The
-[`@ingestron/cli` README](https://github.com/ingestron/ingestron/tree/main/packages/cli#project-builder-api)
+[`@ingestron/core` README](https://github.com/ingestron/ingestron/tree/main/packages/core)
 describes them.

content/docs/(reference)/reference/versions.mdx

@@ -29,5 +29,5 @@ Connector maturity, such as Public Preview or Beta, is shown on each
 The [deployment templates](/docs/how-to/deploy-through-environments) pin the
 tools their stages run: `@microsoft/azure-data-factory-utilities` 1.0.3, the
 Databricks CLI v1.23.0, and sqlcmd (Go) v1.10.0. Their check stage installs
-`ingestron@2.1.0`, and each GitHub action is pinned to a commit, with its
+`ingestron@2.2.0`, and each GitHub action is pinned to a commit, with its
 version beside it.

content/docs/how-to/(build)/check-in-ci.mdx

@@ -8,7 +8,7 @@ from the definitions project folder on every pull request: it fails when
 someone changed the definitions without generating, so the files you deploy
 are always what the definitions say. It needs only Node.js 22.13 or later:
 each template installs an exact version of the command from npm,
-`npm install -g ingestron@2.1.0`, then runs it. Change the version when you
+`npm install -g ingestron@2.2.0`, then runs it. Change the version when you
 upgrade, as
 [Upgrade Ingestron and its packs](/docs/how-to/upgrade#choose-the-version-you-run)
 shows, so a new release never fails a pull request that changed nothing.

content/docs/how-to/(build)/deploy-through-environments.mdx

@@ -43,7 +43,7 @@ The tools are pinned: Microsoft's `@microsoft/azure-data-factory-utilities`
 1.0.3, the Databricks CLI v1.23.0 and sqlcmd (Go) v1.10.0, each download
 checked by its SHA-256 where the template downloads it. Each GitHub action is
 pinned to a full commit, with its version beside it, and the check installs an
-exact Ingestron, `ingestron@2.1.0`: change them when you upgrade. The ADF
+exact Ingestron, `ingestron@2.2.0`: change them when you upgrade. The ADF
 build fetches its build tool from `adf.azure.com`, so the build stage needs
 network access there.
 

content/docs/how-to/(standards)/upgrade.mdx

@@ -46,7 +46,7 @@ choose to upgrade. The [CI templates](/docs/how-to/check-in-ci) and the
 [deployment templates](/docs/how-to/deploy-through-environments) do:
 
 ```sh
-npm install -g ingestron@2.1.0
+npm install -g ingestron@2.2.0
 ```
 
 `npm ls -g ingestron` shows the version a computer has installed.
@@ -95,7 +95,7 @@ next; see [Deploy through environments](/docs/how-to/deploy-through-environments
 
 ### The standard and the folders
 
-1. Install `ingestron@2.1.0` and plan. Every pack is version 2, so a standard that
+1. Install `ingestron@2.2.0` and plan. Every pack is version 2, so a standard that
    names `databricks@1`, `adf@1`, `synapse@1` or `duckdb@1` stops with
    `PACK_VERSION`, once for all the environments that have it:
 
@@ -135,7 +135,7 @@ next; see [Deploy through environments](/docs/how-to/deploy-through-environments
    [`DEPLOY_VALUE`](/docs/reference/errors#DEPLOY_VALUE): write it in
    `project.yaml` for each environment. See
    [Supplied when deploying](/docs/concepts/yaml-references#supplied-when-deploying).
-5. Change CI: the check templates install `ingestron@2.1.0`, and the deploy
+5. Change CI: the check templates install `ingestron@2.2.0`, and the deploy
    pipelines deploy `build/<pack>/` by target, parameter file or script, as
    [Deploy through environments](/docs/how-to/deploy-through-environments)
    shows.
@@ -327,9 +327,29 @@ Factory:
   `ingestron plan` to see the linked service change.
 - For code that calls the packages: `@ingestron/definitions` 1.11 adds the
   `REPLACE_ME` code and the `replaceMe` resolve option, which `check` sets to
-  `error`; the CLI's `Io` gains an optional `now()`, the day `init` writes;
-  and the [`@ingestron/cli` README](https://github.com/ingestron/ingestron/tree/main/packages/cli)
-  describes `generatedOutputs`.
+  `error`; and the CLI's `Io` gains an optional `now()`, the day `init`
+  writes.
+
+## Upgrade to 2.2 [#upgrade-to-2-2]
+
+2.2 generates, prints and checks exactly what 2.1 does, and the VS Code
+extension works as before. Only code that calls the packages changes:
+
+- `@ingestron/core` 1.0 is the API the command is built on.
+  `@ingestron/cli` now exports only `run`, `commands` and `flags`. Import
+  everything else it exported in 2.1, such as `generatedOutputs`,
+  `projectRoutes`, `platformRequest` and `packs`, from `@ingestron/core`,
+  under the same names. The
+  [`@ingestron/core` README](https://github.com/ingestron/ingestron/tree/main/packages/core)
+  describes them.
+- In `@ingestron/authoring`, open a project with `ProjectSnapshot.open(folder)`
+  in place of `openProject`, and call the snapshot's methods. Each function
+  that took the project first is now a method with the same name:
+  `problems(project, "dev")` becomes `snapshot.problems("dev")`. Three are
+  renamed: `projectSymbols` is `symbols`, `compareEnvironments` is `compare`
+  and `platformRequest` is `request`. The
+  [`@ingestron/authoring` README](https://github.com/ingestron/ingestron/tree/main/packages/authoring)
+  shows an example.
 
 ## What changed in a release
 

lib/connector-page.ts

@@ -4,7 +4,7 @@
 // in one of the page's slots.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { projectRoutes, projectSources } from "@ingestron/cli";
+import { projectRoutes, projectSources } from "@ingestron/core";
 import type { TOCItemType } from "fumadocs-core/toc";
 import { parse } from "yaml";
 import { exampleFiles, listExamples, readExampleFile } from "./examples";

lib/examples.ts

@@ -7,14 +7,14 @@
 import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative, resolve } from "node:path";
+import { run } from "@ingestron/cli";
 import {
   listSamples,
   readSample,
-  run,
   sampleFacts,
   type Sample,
   type SampleFacts,
-} from "@ingestron/cli";
+} from "@ingestron/core";
 import { recipesFolder } from "@ingestron/pack-adf";
 import { parse } from "yaml";
 import { pickLines, pickPath } from "./extract";

lib/reference.ts

@@ -1,7 +1,7 @@
 // Reference data read from the packages at build time, so pages match the code.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { projectRecipe, projectRoutes, projectSources, type ProjectRoute } from "@ingestron/cli";
+import { projectRecipe, projectRoutes, projectSources, type ProjectRoute } from "@ingestron/core";
 import {
   documentReference,
   methodReference,

lib/routes.ts

@@ -2,7 +2,7 @@
 // project offers. Titles, `--via` values and packs come from the CLI; what
 // each route is for, and its guide, are written here, and a route the CLI
 // adds without them fails the build.
-import { builtInTemplates, sampleFacts } from "@ingestron/cli";
+import { builtInTemplates, sampleFacts } from "@ingestron/core";
 import { allRoutes, routePacks } from "@/lib/reference";
 
 /** One way to start a project, and what it gives you. */

lib/search.ts

@@ -1,6 +1,7 @@
 // Search entries for reference rendered from code, which the MDX indexer
 // cannot see: error codes, method settings, CLI commands and connector pages.
-import { commands, flags, projectSources } from "@ingestron/cli";
+import { commands, flags } from "@ingestron/cli";
+import { projectSources } from "@ingestron/core";
 import { codeHelp } from "@ingestron/definitions";
 import type { StructuredData } from "fumadocs-core/mdx-plugins";
 import { ingestionRows } from "./connector-settings";

package.json

@@ -23,8 +23,9 @@
     "sync:vscode": "node scripts/sync-vscode-commands.mjs"
   },
   "dependencies": {
-    "@ingestron/authoring": "^2.1.0",
-    "@ingestron/cli": "^2.1.0",
+    "@ingestron/authoring": "^2.2.0",
+    "@ingestron/cli": "^2.2.0",
+    "@ingestron/core": "^1.0.0",
     "@ingestron/definitions": "^1.11.0",
     "@ingestron/pack-adf": "^2.1.0",
     "@ingestron/pack-databricks": "^2.1.0",