From cc205a0a260d2e39ae7a8c83f4079c09d507515b Mon Sep 17 00:00:00 2001 From: shrugs Date: Fri, 29 May 2026 16:02:33 -0500 Subject: [PATCH 1/7] checkpoint: un-version vendored docs --- .../fetch-omnigraph-example-responses.mts | 25 +- .../scripts/snapshot-omnigraph-version.mts | 35 +- .../molecules/HostedEnsNodeInstance.astro | 4 +- .../HostedInstanceSdkVersionWarning.astro | 10 +- .../organisms/OmnigraphSchemaDocExplorer.tsx | 17 +- .../{enskit/v1.15.0.mdx => enskit.mdx} | 6 +- .../walkthroughs/enskit/v1.13.1.mdx | 407 -- .../{enssdk/v1.15.0.mdx => enssdk.mdx} | 6 +- .../walkthroughs/enssdk/v1.13.1.mdx | 319 - .../v1.15.0.mdx => omnigraph-graphql-api.mdx} | 6 +- .../omnigraph-graphql-api/v1.13.1.mdx | 184 - .../v1.15.0.mdx => quickstart.mdx} | 4 + .../walkthroughs/quickstart/v1.13.1.mdx | 158 - .../src/content/docs/docs/integrate/index.mdx | 25 +- .../integration-options/enskit/index.mdx | 25 +- .../integration-options/enssdk/index.mdx | 25 +- .../omnigraph-graphql-api.mdx | 27 +- .../src/data/omnigraph-examples/active.ts | 14 - .../{versions/v1.15.1 => }/examples.json | 0 .../src/data/omnigraph-examples/examples.ts | 32 +- .../{versions/v1.15.1 => }/responses.json | 0 .../{versions/v1.15.0 => }/schema.graphql | 0 .../{versions/v1.15.1 => }/snapshot.json | 0 .../data/omnigraph-examples/snapshot.test.ts | 23 + .../src/data/omnigraph-examples/types.ts | 2 +- .../data/omnigraph-examples/versions.test.ts | 47 - .../versions/v1.13.1/examples.json | 99 - .../versions/v1.13.1/responses.json | 2691 -------- .../versions/v1.13.1/schema.graphql | 1882 ------ .../versions/v1.13.1/snapshot.json | 8 - .../versions/v1.15.0/examples.json | 138 - .../versions/v1.15.0/responses.json | 5467 ----------------- .../versions/v1.15.0/snapshot.json | 8 - .../versions/v1.15.1/schema.graphql | 1999 ------ .../build-integration-snippets.test.ts | 16 +- .../omnigraph/build-integration-snippets.ts | 4 +- 36 files changed, 103 insertions(+), 13610 deletions(-) rename docs/ensnode.io/src/components/walkthroughs/{enskit/v1.15.0.mdx => enskit.mdx} (96%) delete mode 100644 docs/ensnode.io/src/components/walkthroughs/enskit/v1.13.1.mdx rename docs/ensnode.io/src/components/walkthroughs/{enssdk/v1.15.0.mdx => enssdk.mdx} (95%) delete mode 100644 docs/ensnode.io/src/components/walkthroughs/enssdk/v1.13.1.mdx rename docs/ensnode.io/src/components/walkthroughs/{omnigraph-graphql-api/v1.15.0.mdx => omnigraph-graphql-api.mdx} (92%) delete mode 100644 docs/ensnode.io/src/components/walkthroughs/omnigraph-graphql-api/v1.13.1.mdx rename docs/ensnode.io/src/components/walkthroughs/{quickstart/v1.15.0.mdx => quickstart.mdx} (93%) delete mode 100644 docs/ensnode.io/src/components/walkthroughs/quickstart/v1.13.1.mdx delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/active.ts rename docs/ensnode.io/src/data/omnigraph-examples/{versions/v1.15.1 => }/examples.json (100%) rename docs/ensnode.io/src/data/omnigraph-examples/{versions/v1.15.1 => }/responses.json (100%) rename docs/ensnode.io/src/data/omnigraph-examples/{versions/v1.15.0 => }/schema.graphql (100%) rename docs/ensnode.io/src/data/omnigraph-examples/{versions/v1.15.1 => }/snapshot.json (100%) create mode 100644 docs/ensnode.io/src/data/omnigraph-examples/snapshot.test.ts delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions.test.ts delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.13.1/examples.json delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.13.1/responses.json delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.13.1/schema.graphql delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.13.1/snapshot.json delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.15.0/examples.json delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.15.0/responses.json delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.15.0/snapshot.json delete mode 100644 docs/ensnode.io/src/data/omnigraph-examples/versions/v1.15.1/schema.graphql diff --git a/docs/ensnode.io/scripts/fetch-omnigraph-example-responses.mts b/docs/ensnode.io/scripts/fetch-omnigraph-example-responses.mts index f35ce039d..5cb4de449 100644 --- a/docs/ensnode.io/scripts/fetch-omnigraph-example-responses.mts +++ b/docs/ensnode.io/scripts/fetch-omnigraph-example-responses.mts @@ -2,7 +2,6 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; -import { ACTIVE_OMNIGRAPH_VERSION } from "../src/data/omnigraph-examples/active.ts"; import { OMNIGRAPH_EXAMPLES_META } from "../src/data/omnigraph-examples/meta.ts"; import type { SnapshotExample } from "../src/data/omnigraph-examples/types.ts"; import { ENSNODE_URL } from "../src/lib/examples/omnigraph/constants.ts"; @@ -15,22 +14,12 @@ function logError(message: string, id?: string) { console.error(`[omnigraph-examples] ERROR: ${message} ${id ? `for example '${id}'` : ""}`); } -// Target version defaults to the active one; override to fill responses for a staged version. -const version = process.env.OMNIGRAPH_VERSION ?? ACTIVE_OMNIGRAPH_VERSION; -// Used as a directory name; reject anything that could escape the versions/ dir. -if (!/^[0-9A-Za-z._-]+$/.test(version) || version.includes("..")) { - logError(`Invalid version "${version}": use only letters, digits, '.', '_', '-'.`); - process.exit(1); -} -const versionDir = join( - dirname(fileURLToPath(import.meta.url)), - `../src/data/omnigraph-examples/versions/${version}`, -); -const examplesPath = join(versionDir, "examples.json"); -const outputPath = join(versionDir, "responses.json"); +const dataDir = join(dirname(fileURLToPath(import.meta.url)), "../src/data/omnigraph-examples"); +const examplesPath = join(dataDir, "examples.json"); +const outputPath = join(dataDir, "responses.json"); if (!existsSync(examplesPath)) { - logError(`No examples snapshot at ${examplesPath}. Snapshot version "${version}" first.`); + logError(`No examples snapshot at ${examplesPath}. Run pnpm omnigraph:snapshot first.`); process.exit(1); } @@ -38,7 +27,7 @@ const snapshotById = new Map( (JSON.parse(readFileSync(examplesPath, "utf8")) as SnapshotExample[]).map((e) => [e.id, e]), ); -// Only fetch responses for the rendered set: meta entries supported by this version's snapshot. +// Only fetch responses for the rendered set: meta entries supported by the vendored snapshot. const allExampleIds = (Object.keys(OMNIGRAPH_EXAMPLES_META) as string[]) .filter((id) => snapshotById.has(id)) .sort(); @@ -66,8 +55,8 @@ const url = new URL("/api/omnigraph", process.env.OMNIGRAPH_ENDPOINT ?? ENSNODE_ logStep( argIds.length > 0 - ? `Refreshing ${exampleIds.length} of ${allExampleIds.length} examples (${version}) from ${url}: ${exampleIds.join(", ")}` - : `Fetching all ${exampleIds.length} Omnigraph examples (${version}) from ${url}`, + ? `Refreshing ${exampleIds.length} of ${allExampleIds.length} examples from ${url}: ${exampleIds.join(", ")}` + : `Fetching all ${exampleIds.length} Omnigraph examples from ${url}`, ); // When refreshing a subset, load the existing responses so unaffected entries are preserved. diff --git a/docs/ensnode.io/scripts/snapshot-omnigraph-version.mts b/docs/ensnode.io/scripts/snapshot-omnigraph-version.mts index d6514e7f2..276a12cdb 100644 --- a/docs/ensnode.io/scripts/snapshot-omnigraph-version.mts +++ b/docs/ensnode.io/scripts/snapshot-omnigraph-version.mts @@ -1,5 +1,5 @@ import { execSync } from "node:child_process"; -import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { readFileSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; @@ -11,35 +11,29 @@ import { GRAPHQL_API_EXAMPLE_QUERIES } from "@ensnode/ensnode-sdk/internal"; import type { SnapshotExample } from "../src/data/omnigraph-examples/types.ts"; import { DOCS_OMNIGRAPH_NAMESPACE, ENSNODE_URL } from "../src/lib/examples/omnigraph/constants.ts"; -// Freeze the CURRENT workspace SDK omnigraph bundle (examples + schema) into a version -// snapshot. Run this on the release commit of , where the SDK's example set is -// — by construction — valid against that release's schema. Responses are filled separately +// Freeze the CURRENT workspace SDK omnigraph bundle (examples + schema) into the single +// vendored snapshot the docs render. Run this on the release commit of , where the +// SDK's example set is — by construction — valid against that release's schema. is +// recorded in snapshot.json for provenance. Responses are filled separately // (`pnpm omnigraph-examples:refresh-responses`) once the version is live in production. +// Overwrites the existing snapshot; new-version work happens on a separate branch. // -// Usage: pnpm omnigraph:snapshot e.g. pnpm omnigraph:snapshot v1.14.0 +// Usage: pnpm omnigraph:snapshot e.g. pnpm omnigraph:snapshot v1.16.0 const version = process.argv[2]; if (!version) { console.error("Usage: pnpm omnigraph:snapshot "); process.exit(1); } -// Used as a directory name; reject anything that could escape the versions/ dir. if (!/^[0-9A-Za-z._-]+$/.test(version) || version.includes("..")) { console.error(`Invalid version "${version}": use only letters, digits, '.', '_', '-'.`); process.exit(1); } const here = dirname(fileURLToPath(import.meta.url)); -const versionDir = join(here, `../src/data/omnigraph-examples/versions/${version}`); +const dataDir = join(here, "../src/data/omnigraph-examples"); const sdkSchemaPath = join(here, "../../../packages/enssdk/src/omnigraph/generated/schema.graphql"); -if (existsSync(versionDir)) { - console.error( - `Snapshot already exists: ${versionDir}. Snapshots are immutable; delete it first to re-cut.`, - ); - process.exit(1); -} - const sdl = readFileSync(sdkSchemaPath, "utf8"); const schema = buildSchema(sdl); @@ -72,20 +66,15 @@ try { // not in a git checkout; leave "unknown" } -mkdirSync(versionDir, { recursive: true }); -writeFileSync(join(versionDir, "schema.graphql"), sdl, "utf8"); -writeFileSync(join(versionDir, "examples.json"), `${JSON.stringify(examples, null, 2)}\n`, "utf8"); +writeFileSync(join(dataDir, "schema.graphql"), sdl, "utf8"); +writeFileSync(join(dataDir, "examples.json"), `${JSON.stringify(examples, null, 2)}\n`, "utf8"); writeFileSync( - join(versionDir, "snapshot.json"), + join(dataDir, "snapshot.json"), `${JSON.stringify({ version, commit, sdkVersion, schemaTag: version, endpoint: ENSNODE_URL, snapshottedAt: new Date().toISOString().slice(0, 10) }, null, 2)}\n`, "utf8", ); console.log(`Snapshotted ${examples.length} examples + schema for ${version} (commit ${commit}).`); -console.log("Next:"); -console.log( - ` 1. OMNIGRAPH_VERSION=${version} pnpm omnigraph-examples:refresh-responses # once ${version} is live`, -); console.log( - ` 2. set ACTIVE_OMNIGRAPH_VERSION = "${version}" in src/data/omnigraph-examples/active.ts`, + `Next: pnpm omnigraph-examples:refresh-responses # once ${version} is live in production`, ); diff --git a/docs/ensnode.io/src/components/molecules/HostedEnsNodeInstance.astro b/docs/ensnode.io/src/components/molecules/HostedEnsNodeInstance.astro index 01fb9211b..a5a06fc22 100644 --- a/docs/ensnode.io/src/components/molecules/HostedEnsNodeInstance.astro +++ b/docs/ensnode.io/src/components/molecules/HostedEnsNodeInstance.astro @@ -1,9 +1,9 @@ --- import ENSAdminCTAButton from "@components/atoms/ENSAdminCTAButton.astro"; -import { ACTIVE_OMNIGRAPH_VERSION } from "@data/omnigraph-examples/active"; +import snapshot from "@data/omnigraph-examples/snapshot.json"; const { instanceURL, connectWithENSAdminURL, namespace, ensVersions, plugins } = Astro.props; -const hostedEnsNodeVersion = ACTIVE_OMNIGRAPH_VERSION; +const hostedEnsNodeVersion = snapshot.version; --- diff --git a/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro b/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro index a9d9359bc..e76f944d0 100644 --- a/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro +++ b/docs/ensnode.io/src/components/molecules/HostedInstanceSdkVersionWarning.astro @@ -1,12 +1,12 @@ --- import { Aside } from "@astrojs/starlight/components"; -import { ACTIVE_OMNIGRAPH_VERSION } from "@data/omnigraph-examples/active"; +import snapshot from "@data/omnigraph-examples/snapshot.json"; -// The SDK version is locked to the production-deployed Omnigraph version (see -// `@data/omnigraph-examples/active`). The SDK bundles the Omnigraph schema, so pinning the matching -// version keeps gql.tada's generated types aligned with the deployed API. Updates on promotion. -const VERSION = ACTIVE_OMNIGRAPH_VERSION.replace(/^v/, ""); +// The SDK version is locked to the production-deployed Omnigraph version (see the vendored +// `@data/omnigraph-examples/snapshot.json`). The SDK bundles the Omnigraph schema, so pinning the +// matching version keeps gql.tada's generated types aligned with the deployed API. +const VERSION = snapshot.sdkVersion; ---