plain-forge - npm Package Compare versions

Comparing version

1.0.7

1.0.8

+6

-0

forge/rules/integrations.md

		@@ -47,2 +47,7 @@ ---

		- Always `fetch` the provider's documentation — even if you already "know" the API. Training-data memory of any third-party REST API is, by definition, stale: endpoints get renamed, fields get added or deprecated, auth flows change, error envelopes shift, and rate-limit headers are renamed between releases. The only acceptable source of truth for what the API looks like today is the provider's own live documentation, retrieved with `fetch` at spec-authoring time. This applies without exception — there is no API well-known enough to skip this step, and a spec authored from memory is a spec authored against the wrong contract. Concretely:
		- Before authoring any endpoint, auth, error, pagination, or webhook concept, `fetch` the relevant documentation page(s) and quote concrete details (status codes, field names, header names, error formats) directly from the fetched content into the resources under `resources/`. Never paraphrase from memory.
		- Save the fetched documentation snapshot under `resources/docs/<provider>/<page>.md` (or `.html` if structure matters) so the spec has a stable doc artifact the renderer and reviewers can consult, independent of the live URL changing or going behind auth.
		- If a documentation page is unreachable (paywall, login wall, JS-only render that `fetch` can't see), say so explicitly and ask the user for the canonical content rather than filling the gap from memory.
		- The fetched documentation is then cross-checked against the live API — see the rest of this section. Memory is not part of the loop at any point.
		- Validate credentials against the live API before authoring downstream specs. A 2xx on a low-risk read-only endpoint (`/v1/me`, `/account`, `/whoami`, `/health`) is the gate. On 401/403, stop and resolve before continuing.
		@@ -126,1 +131,2 @@ - Issue the minimum cross-check coverage with `fetch`: one discovery / schema endpoint if available, one list endpoint per primary entity in scope, one single-object retrieval per primary entity, one empty/boundary response, one 404, one 400/422, and one deliberate 401.
		- Authoring Phase 1 specs from the docs first and "reconciling" with the live API later. Probe the API as you reach each topic; the live response is the source of truth from the moment it's captured
		- Writing any integration spec from memory of the provider's API instead of `fetch`-ing its documentation first. No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the documentation must be retrieved with `fetch` at spec-authoring time and saved under `resources/docs/<provider>/` — see Live API must be cross-checked against the documentation. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call

+1

-1

package.json

		{
		"name": "plain-forge",
		"version": "1.0.7",
		"version": "1.0.8",
		"description": "Conversational spec-writing tool for ***plain specification language",
		@@ -5,0 +5,0 @@ "type": "module",

		@@ -47,2 +47,7 @@ ---

		- Always `fetch` the provider's documentation — even if you already "know" the API. Training-data memory of any third-party REST API is, by definition, stale: endpoints get renamed, fields get added or deprecated, auth flows change, error envelopes shift, and rate-limit headers are renamed between releases. The only acceptable source of truth for what the API looks like today is the provider's own live documentation, retrieved with `fetch` at spec-authoring time. This applies without exception — there is no API well-known enough to skip this step, and a spec authored from memory is a spec authored against the wrong contract. Concretely:
		- Before authoring any endpoint, auth, error, pagination, or webhook concept, `fetch` the relevant documentation page(s) and quote concrete details (status codes, field names, header names, error formats) directly from the fetched content into the resources under `resources/`. Never paraphrase from memory.
		- Save the fetched documentation snapshot under `resources/docs/<provider>/<page>.md` (or `.html` if structure matters) so the spec has a stable doc artifact the renderer and reviewers can consult, independent of the live URL changing or going behind auth.
		- If a documentation page is unreachable (paywall, login wall, JS-only render that `fetch` can't see), say so explicitly and ask the user for the canonical content rather than filling the gap from memory.
		- The fetched documentation is then cross-checked against the live API — see the rest of this section. Memory is not part of the loop at any point.
		- Validate credentials against the live API before authoring downstream specs. A 2xx on a low-risk read-only endpoint (`/v1/me`, `/account`, `/whoami`, `/health`) is the gate. On 401/403, stop and resolve before continuing.
		@@ -126,1 +131,2 @@ - Issue the minimum cross-check coverage with `fetch`: one discovery / schema endpoint if available, one list endpoint per primary entity in scope, one single-object retrieval per primary entity, one empty/boundary response, one 404, one 400/422, and one deliberate 401.
		- Authoring Phase 1 specs from the docs first and "reconciling" with the live API later. Probe the API as you reach each topic; the live response is the source of truth from the moment it's captured
		- Writing any integration spec from memory of the provider's API instead of `fetch`-ing its documentation first. No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the documentation must be retrieved with `fetch` at spec-authoring time and saved under `resources/docs/<provider>/` — see Live API must be cross-checked against the documentation. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call

plain-forge - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics