diff --git a/CLAUDE.md b/CLAUDE.md index bf808b3..b2009ca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,11 +38,11 @@ Direct. TypeSafe publishes an OpenAPI 3.1.0 document at `https://api.typesafe.ai - **Engine typing** - UPDATE marshals every SET value as a string; INSERT and EXEC send typed JSON; EXEC cannot carry a boolean. Documented for completeness; no method here uses those verbs. - **Content unions** - the vendor's `string | object | array (| null)` unions on `state`, `instructions`, criteria descriptions and the score legend are lowered to `string` in `pre_normalize.mjs` (9 sites) before provider-utils normalize, which would otherwise leave `additionalProperties: true` and `items: {}` on a `type: string` property. On the SQL surface those values are always strings. - **Docs examples** - three-statement agent-loop blocks (context, decision, action) against verified sibling-provider surfaces, plus a few plain SELECTs and a shell quick start. Facts a routine can compute stay in SQL; Jev is asked the judgment, one atomic question at a time, with the policy in `criteria` (finding 13). `bin/validate-docs-examples.sh` runs every block before a docs publish: typesafe live, the other providers routed with dummy credentials through a registry clone (finding 12). Known provider facts the examples depend on: aws `cidr_ipv_4`, aws list params as JSON arrays, k8s needs `KUBE_HOST`. -- **Docgen** - `bin/patch-provider-utils.mjs` (npm `postinstall`) adds `select` to docgen's required-body-params allowlist and lists a SELECT method's naive body properties in the Parameters table, so the `evaluate` page documents `state`, `model`, `questions` as required and its SELECT example routes (provider-utils 0.7.10 still lacks it; the first two edits are carried from the anthropic and gemini builds). `sanitize-docs.mjs` keeps `
` line breaks in description cells. +- **Docgen** - `bin/patch-provider-utils.mjs` (npm `postinstall`) adds `select` to docgen's required-body-params allowlist and lists a SELECT method's naive body properties in the Parameters table, so the `evaluate` page documents `state`, `model`, `questions` as required and its SELECT example routes (provider-utils 0.7.11 still lacks it; the first two edits are carried from the anthropic and gemini builds). `sanitize-docs.mjs` keeps `
` line breaks in description cells. ## Toolchain rules -- Latest `@stackql/provider-utils` (0.7.10), `@stackql/pgwire-lite` (1.0.2) and `@apidevtools/swagger-parser` (13.1.0) at build time (check npm before starting: `npm view @stackql/provider-utils version`); Docusaurus `^3.10.x`. Node >= 22.19 (Node 20 reached end of life in April 2026; swagger-parser 13 needs 22.19), `type: module`. `js-yaml` stays on 4.x: provider-utils emits with js-yaml 4, and v5 drops the default export, removes the `quotingType` dump option and changes scalar quoting, so that bump is a coordinated change with provider-utils. `package-lock.json` pins what CI installs; a toolchain bump is an explicit commit that regenerates the artifacts and re-checks `bin/patch-provider-utils.mjs` (it prints PATTERN NOT FOUND when upstream moves). +- Latest `@stackql/provider-utils` (0.7.11), `@stackql/pgwire-lite` (1.0.2) and `@apidevtools/swagger-parser` (13.1.0) at build time (check npm before starting: `npm view @stackql/provider-utils version`); Docusaurus `^3.10.x`. Node >= 22.19 (Node 20 reached end of life in April 2026; swagger-parser 13 needs 22.19), `type: module`. `js-yaml` stays on 4.x: provider-utils emits with js-yaml 4, and v5 drops the default export, removes the `quotingType` dump option and changes scalar quoting, so that bump is a coordinated change with provider-utils. `package-lock.json` pins what CI installs; a toolchain bump is an explicit commit that regenerates the artifacts and re-checks `bin/patch-provider-utils.mjs` (it prints PATTERN NOT FOUND when upstream moves). - Linux, macOS or WSL: GNU make + bash, a `stackql` binary (`$STACKQL`, `./stackql`, then PATH; `bin/start-server.sh` downloads one if none is found), Python 3 and yarn. The Makefile is the operator surface (`make help`). Engine facts in NOTES.md were verified against stackql v0.12.732 (any-sdk v0.6.0-alpha01). - The two provider-utils CLI entry points are npm scripts invoked through `node` (never `.bin` shims); flags go after `--`. @@ -91,7 +91,7 @@ Never run tests against a production account. ## Docs and publish -`make docs` (generate with `--snake-case-aliases`, then `sanitize-docs`) and `make website`; `website/docs` is committed after every regeneration so pages stamp with their regeneration date. Publishing to the registry is a separate, human-in-the-loop step (push the generated provider dir to `providers/src` in a feature branch of `stackql-provider-registry`, follow the release flow, verify with `make smoke-live`). +`make docs` (generate with `--snake-case-aliases` and `--source-project`, the repository URL in the Makefile variable `SOURCE_PROJECT`, then `sanitize-docs`) and `make website`; `website/docs` is committed after every regeneration so pages stamp with their regeneration date. Publishing to the registry is a separate, human-in-the-loop step (push the generated provider dir to `providers/src` in a feature branch of `stackql-provider-registry`, follow the release flow, verify with `make smoke-live`). ## Writing conventions diff --git a/Makefile b/Makefile index 70b9933..dad3a9c 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,7 @@ VERSION := v00.00.00000 OPENAPI_DIR := provider-dev/openapi SERVICES_DIR := $(OPENAPI_DIR)/src/$(PROVIDER) PROVIDER_DIR := $(SERVICES_DIR)/$(VERSION) +SOURCE_PROJECT ?= https://github.com/stackql-registry/stackql-provider-$(PROVIDER) SOURCE_DIR := provider-dev/source CONFIG_DIR := provider-dev/config GRAPHQL_DIR := provider-dev/source-graphql @@ -153,13 +154,17 @@ smoke-read-only: venv ## live catalog read only - no evaluation is billed # -------------------------------------------------------------------- docs -docs: ## generate the website docs (snake_case surface), then sanitize for MDX +# --source-project (provider-utils >= 0.7.11) adds a "source project" row to the +# Provider Summary admonition on the landing page, linking the repository name +# to SOURCE_PROJECT (override it on the command line for a fork). +docs: ## generate the website docs (snake_case surface, source project link), then sanitize for MDX npm run generate-docs -- \ --provider-name $(PROVIDER) \ --provider-dir ./$(PROVIDER_DIR) \ --output-dir ./website \ --provider-data-dir ./provider-dev/docgen/provider-data \ - --snake-case-aliases + --snake-case-aliases \ + --source-project $(SOURCE_PROJECT) npm run sanitize-docs website: ## build the docusaurus microsite (vendors the shared stackql config first) diff --git a/NOTES.md b/NOTES.md index 8ccd40c..bd7510e 100644 --- a/NOTES.md +++ b/NOTES.md @@ -2,7 +2,7 @@ The memory of the build: numbered findings with evidence (what was measured, against what, what was decided and why), the blockers only a live run can resolve, and the testing requirements. A future refresh reads this before touching a rule. Cross-build findings from the sibling providers (see the skill's reference-repos.md) are reused, not re-derived - cited by repo rather than restated. -Sources: the pinned spec snapshot (`provider-dev/downloaded/typesafe-v1.json`, upstream sha256 `a191f8a7df6b...`, fetched 2026-10-02), the vendor documentation (`https://docs.typesafe.ai/llms.txt` is the index; every page serves markdown at its `.md` URL), unauthenticated probes of `api.typesafe.ai` (2026-10-02, before an account existed), the first live run against a dev account with purchased credits (2026-10-05, finding 12), the mock API in `tests/integration/`, stackql v0.12.732 (any-sdk v0.6.0-alpha01) under WSL, `@stackql/provider-utils` 0.7.10, and the anthropic, gemini, openai and supabase sibling builds. +Sources: the pinned spec snapshot (`provider-dev/downloaded/typesafe-v1.json`, upstream sha256 `a191f8a7df6b...`, fetched 2026-10-02), the vendor documentation (`https://docs.typesafe.ai/llms.txt` is the index; every page serves markdown at its `.md` URL), unauthenticated probes of `api.typesafe.ai` (2026-10-02, before an account existed), the first live run against a dev account with purchased credits (2026-10-05, finding 12), the mock API in `tests/integration/`, stackql v0.12.732 (any-sdk v0.6.0-alpha01) under WSL, `@stackql/provider-utils` 0.7.11, and the anthropic, gemini, openai and supabase sibling builds. ## Findings @@ -93,7 +93,7 @@ So at this engine version the provider-level block is not consulted (the provide **Question.** Does the generated documentation show `state`, `model` and `questions` as required for `evaluate`? -**Evidence.** provider-utils 0.7.10 `src/docgen/resource/methods.js getRequiredBodyParams` builds required params from `requestBody.required` only for insert / update / replace / exec access types, and `examples/select-example.js` builds the SELECT example's WHERE from `parameters` only. The anthropic build (`factory/patch-provider-utils.mjs`) and the gemini build hit the same gap on 0.7.7 and 0.7.9 and carry a two-edit patch; the anchors are unchanged in 0.7.10. +**Evidence.** provider-utils 0.7.10 `src/docgen/resource/methods.js getRequiredBodyParams` builds required params from `requestBody.required` only for insert / update / replace / exec access types, and `examples/select-example.js` builds the SELECT example's WHERE from `parameters` only. The anthropic build (`factory/patch-provider-utils.mjs`) and the gemini build hit the same gap on 0.7.7 and 0.7.9 and carry a two-edit patch; the anchors are unchanged in 0.7.10 and 0.7.11. 0.7.11 (bumped 2026-10-06) changes docgen only: a `--source-project` flag adds a `source project` row to the landing page's Provider Summary admonition, linking the repository name to the URL; `make docs` passes it from the Makefile variable `SOURCE_PROJECT`. **Decision.** `bin/patch-provider-utils.mjs`, run as the npm `postinstall` hook, applies the same two edits plus a third of its own in `parameters.js` (the body properties of a SELECT-routed naive method are listed in the Parameters table, where the Methods table's required-param links point); all three are idempotent and the script exits non-zero with PATTERN NOT FOUND when upstream moves. With it the `evaluate` page documents `model`, `questions` and `state` as required parameters with the vendor's descriptions, and its generated SELECT example carries them in the WHERE clause. `sanitize-docs.mjs` additionally keeps docgen's `
` line breaks in description cells as tags instead of escaping them to text (the two multi-paragraph operation descriptions would otherwise show literal `
`). Remove the hook once a provider-utils release includes `select` in the allowlist. diff --git a/README.md b/README.md index 9b0d44e..ae2f01e 100644 --- a/README.md +++ b/README.md @@ -131,12 +131,12 @@ The smoke suite (`tests/smoke_test.py`, pystackql) mirrors the vendor's quick-st ## 6. Docs ```bash -make docs # generate website/docs (snake_case surface) and sanitize for MDX +make docs # generate website/docs (snake_case surface, source project link) and sanitize for MDX make website # yarn install && yarn build (vendors the shared stackql/docusaurus-config) make website-start ``` -`provider-dev/docgen/provider-data/headerContent1.txt` is the landing-page front matter and pitch; `headerContent2.txt` is the getting-started page (installation, scope, authentication, evaluations as SELECT, models and aliases, rate limit and retries, example queries). `bin/patch-provider-utils.mjs` (npm `postinstall`) patches provider-utils' docgen so the `evaluate` method documents its three required body fields (in the Methods and Parameters tables) and its SELECT example routes. `website/provider.js` carries the site identity; `website/static/CNAME` the hostname `typesafe-provider.stackql.io`. Commit `website/docs` after every regeneration. +`provider-dev/docgen/provider-data/headerContent1.txt` is the landing-page front matter and pitch; `headerContent2.txt` is the getting-started page (installation, scope, authentication, evaluations as SELECT, models and aliases, rate limit and retries, example queries). `bin/patch-provider-utils.mjs` (npm `postinstall`) patches provider-utils' docgen so the `evaluate` method documents its three required body fields (in the Methods and Parameters tables) and its SELECT example routes. `website/provider.js` carries the site identity; `website/static/CNAME` the hostname `typesafe-provider.stackql.io`. Commit `website/docs` after every regeneration. The Makefile variable `SOURCE_PROJECT` (default: this repository's GitHub URL) is passed to docgen as `--source-project` and becomes the `source project` link in the landing page's Provider Summary; override it on the `make` command line for a fork. To publish the site: rename `.github/workflows/prod-web-deploy.yml.disabled` and `test-web-deploy.yml.disabled`, enable GitHub Pages (source: GitHub Actions) and add the DNS record: diff --git a/bin/patch-provider-utils.mjs b/bin/patch-provider-utils.mjs index 412c3b4..7b98e62 100644 --- a/bin/patch-provider-utils.mjs +++ b/bin/patch-provider-utils.mjs @@ -4,7 +4,7 @@ // hook so a fresh `npm install` / `npm ci` is always patched before // `make docs`. // -// Upstream gap (provider-utils 0.7.10, the same in 0.7.7 and 0.7.9): docgen +// Upstream gap (provider-utils 0.7.11, the same in 0.7.7, 0.7.9 and 0.7.10): docgen // builds a method's "Required Params" from `parameters` plus // requestBody.required, but ONLY for insert / update / replace / exec access // types (src/docgen/resource/methods.js getRequiredBodyParams), and the diff --git a/package-lock.json b/package-lock.json index a091507..b2c2f4d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "dependencies": { "@apidevtools/swagger-parser": "^13.1.0", "@stackql/pgwire-lite": "^1.0.2", - "@stackql/provider-utils": "^0.7.10", + "@stackql/provider-utils": "^0.7.11", "js-yaml": "^4.1.0", "pluralize": "^8.0.0" }, @@ -173,9 +173,9 @@ } }, "node_modules/@stackql/provider-utils": { - "version": "0.7.10", - "resolved": "https://registry.npmjs.org/@stackql/provider-utils/-/provider-utils-0.7.10.tgz", - "integrity": "sha512-3hlaKT2ce8IaFx0E99ksW0uvmBcQgtfzWAAJz24oSM7bX++6ZrLe87j6CAUyRszowP4FLaO6UMOlHNQzibnViw==", + "version": "0.7.11", + "resolved": "https://registry.npmjs.org/@stackql/provider-utils/-/provider-utils-0.7.11.tgz", + "integrity": "sha512-yRy0nbWzI8IkAZlN2WCMxz/9pdD11EXTx85U+e6pQzIq61CtUpVLklW70Z4fMTTGwLa9nzLqWCNPS5+LBBY0+g==", "license": "MIT", "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", diff --git a/package.json b/package.json index 9533860..cb6db52 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,7 @@ "dependencies": { "@apidevtools/swagger-parser": "^13.1.0", "@stackql/pgwire-lite": "^1.0.2", - "@stackql/provider-utils": "^0.7.10", + "@stackql/provider-utils": "^0.7.11", "js-yaml": "^4.1.0", "pluralize": "^8.0.0" }, diff --git a/website/docs/index.md b/website/docs/index.md index 1127154..4f90c90 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -27,6 +27,7 @@ The `typesafe` provider maps the TypeSafe AI API (`https://api.typesafe.ai`) to total services: __2__ total resources: __2__ +source project: __[stackql-provider-typesafe](https://github.com/stackql-registry/stackql-provider-typesafe)__ :::