pi-lean-dimension 0.5.0 → 0.6.0

package/node_modules/pi-lean-host/__tests__/tools.test.ts

@@ -4,9 +4,9 @@
  * Covers:
  *  - Full write→verify→fix loop against local test server.
  *  - api-guide({}) catalog and api-guide({domain}) detail shapes.
- *  - api-learn validate-before-write (no half-write on invalid recipe).
  *  - api-fetch execute-fail message points at remediation paths.
- *  - api-learn prepends the authoring manual to template/fetch-recipe pulls.
+ *
+ *  (api-learn write-path tests live in api-learn-fetch-recipe.test.ts.)
  */
 
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
@@ -35,7 +35,6 @@ import { apiLearnTool } from "../tools/api-learn.js";
 import { setStagingRoot } from "../core/staging.js";
 import { setUserGuidesDir, invalidateCache } from "../core/guide-store.js";
 import { writeSecret, setSecretsDir } from "../core/secrets-store.js";
-import { parseApiGuide } from "../core/parse-api-guide.js";
 import { selectGuideByShortName } from "../core/guide-catalog.js";
 
 // ═══════════════════════════════════════════════════════════════════
@@ -595,19 +594,6 @@ Op-collide guide.
 `;
 }
 
-/** An invalid recipe (missing leading / in path). */
-const INVALID_RECIPE = `---
-schemaVersion: 1
-domains: [example.com]
-apiHost: https://api.example.com
-operations:
-  - name: get
-    via: restGet
-    path: things/{id}
----
-body
-`;
-
 // ═══════════════════════════════════════════════════════════════════
 // Setup
 // ═══════════════════════════════════════════════════════════════════
@@ -691,11 +677,6 @@ function callLearn(
 	return apiLearnTool.execute("test", p, undefined, undefined, undefined as any);
 }
 
-/** Staged guide.md path for a domain (mirrors api-learn's staging). */
-function stagedPath(domain: string): string {
-	return join(tmpStagingRoot, domain, "guide.md");
-}
-
 // ═══════════════════════════════════════════════════════════════════
 // api-guide — catalog & detail
 // ═══════════════════════════════════════════════════════════════════
@@ -816,502 +797,6 @@ describe("api-guide", () => {
 	});
 });
 
-// ═══════════════════════════════════════════════════════════════════
-// api-learn — validate, write, no-half-write, example
-// ═══════════════════════════════════════════════════════════════════
-
-describe("api-learn", () => {
-	it("prepends the authoring manual to template and fetch-recipe pulls", async () => {
-		// Template path ({domain, new: true}) — the manual travels with the
-		// staged draft.
-		const templateText = contentText(
-			await callLearn("example.com", undefined, { new: true }),
-		);
-		// Fetch-existing path ({domain}, no dir) — the manual travels
-		// with the staged raw recipe.
-		await callLearn("boe.es", boeRecipe(ctx.serverUrl));
-		invalidateCache();
-		const fetchText = contentText(await callLearn("boe.es"));
-		for (const text of [templateText, fetchText]) {
-			expect(text).toContain("authoring manual");
-			// Field reference + defaults + semantics stay.
-			expect(text).toContain("Required fields");
-			expect(text).toContain("a LIST of operation mappings");
-			expect(text).toContain("Key defaults");
-			expect(text).toContain("Executor semantics");
-			expect(text).toContain("joinUrl` strips a leading `/");
-			expect(text).toContain("pagination.base` seeds the page param");
-			expect(text).toContain("Page-size resolution (offset-limit/page)");
-			expect(text).toContain("→ omit (server default applies)");
-			expect(text).toContain("optional: true` on a ref");
-			// Guide-prose (agent-instructions) ability is taught, not lost.
-			expect(text).toContain("Guide prose");
-			expect(text).toContain("Guide notes");
-			// Points at the template entry point; no recipe body.
-			expect(text).toContain("new: true");
-			expect(text).not.toContain("searchDiary");
-			expect(text).not.toContain("```yaml");
-		}
-	});
-
-	// The template is a placeholder skeleton, not a worked example. It
-	// must fail closed (placeholder apiHost rejected) and carry no foreign API
-	// literals.
-	it("template is a placeholder skeleton that fails closed", async () => {
-		const text = contentText(
-			await callLearn("example.com", undefined, { new: true }),
-		);
-		// Result surfaces the staged path, not an inline yaml block.
-		expect(text).toContain(stagedPath("example.com"));
-		const template = readFileSync(stagedPath("example.com"), "utf-8");
-		expect(template).toContain("domains: [example.com]");
-		expect(template).toContain("<base url>");
-		expect(template).toContain("<short>");
-		expect(template).toContain("<emoji>");
-		expect(template).not.toMatch(
-			/apidatos|boe\.es|BOE|searchDiary|listConsolidada/,
-		);
-		// The prose-body (agent-instructions) ability is surfaced, not lost.
-		expect(template).toContain("agent-instruction prose");
-		expect(template).toContain("the closing ---");
-		// Fail-closed: the as-is template cannot save (placeholder apiHost
-		// is rejected by requireHttpUrl).
-		expect(parseApiGuide(template, { filename: "example.com" }).ok).toBe(false);
-	});
-
-	it("validates and writes a valid recipe", async () => {
-		const text = contentText(await callLearn("boe.es", boeRecipe(ctx.serverUrl)));
-		expect(text).toContain("Guide saved");
-		expect(text).toContain("boe.es");
-		expect(text).toContain("searchDiary");
-		expect(text).toContain("api-fetch");
-
-		const filepath = join(tmpGuidesDir, "boe", "guide.md");
-		const content = readFileSync(filepath, "utf-8");
-		expect(content).toContain("apiHost:");
-	});
-
-	// Companion — save summary echoes the resolved auth mapping (names only,
-	// never values): wrong-shape is loud, right-shape-but-wrong-name
-	// is eyeballable at save.
-	it("save summary names the auth header→secret mapping, never values", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const recipe = `---\nkind: api\ndomains: [authmap.example]\nshortName: AuthMap\napiHost: ${ctx.serverUrl}\nauth:\n  kind: static-key\n  secretRefs:\n    Authorization:\n      secret: apiKey\n      prefix: "Bearer "\n    X-Example-Pro-Key:\n      secret: example_key\n      prefix: ""\noperations:\n  - name: get\n    via: restGet\n    path: /x\n    accept: json\n---\n`;
-		const text = contentText(await callLearn("authmap.example", recipe));
-		expect(text).toContain("Auth: static-key");
-		expect(text).toContain("Authorization ← secret apiKey (Bearer )");
-		expect(text).toContain("X-Example-Pro-Key ← secret example_key");
-		// Empty prefix (bare-key header) renders without an empty paren.
-		expect(text).not.toContain("example_key ()");
-		// Names only — never the store values.
-		expect(text).not.toContain("s3cr3t");
-	});
-
-	it("rejects an invalid recipe without writing", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		const text = contentText(await callLearn("broken", INVALID_RECIPE));
-		expect(text).toContain("Validation error");
-		expect(text).toContain("operations[0].path");
-		expect(text).toContain("NOT saved");
-
-		const filepath = join(tmpGuidesDir, "broken", "guide.md");
-		expect(() => readFileSync(filepath, "utf-8")).toThrow();
-	});
-
-	// A validation failure names the failing field with expected/found and
-	// never writes. The manual-pointer tail is gone — the author already saw
-	// the manual on the pull that staged the draft.
-	it("reports validation failures with field/expected/found and does not save", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-
-		// Wrong-auth shape: name/secret fields instead of secretRefs/headerPrefixes.
-		const authText = contentText(
-			await callLearn(
-				"authbad.example",
-				`---
-schemaVersion: 1
-domains: [authbad.example]
-apiHost: https://api.example.com
-auth:
-  kind: static-key
-  name: X-EXAMPLE_PRO_API_KEY
-  secret: api_key
-operations:
-  - name: get
-    via: restGet
-    path: /things
----
-`,
-			),
-		);
-		expect(authText).toContain("auth.name");
-		expect(authText).toContain("NOT saved");
-
-		// Bad via.
-		const viaText = contentText(
-			await callLearn(
-				"viabad.example",
-				`---
-schemaVersion: 1
-domains: [viabad.example]
-apiHost: https://api.example.com
-operations:
-  - name: get
-    via: post
-    path: /things
----
-`,
-			),
-		);
-		expect(viaText).toContain("operations[0].via");
-		expect(viaText).toContain("NOT saved");
-
-		// Unmapped field (frontmatter).
-		const fmText = contentText(await callLearn("fmbad.example", "just prose"));
-		expect(fmText).toContain("frontmatter");
-		expect(fmText).toContain("NOT saved");
-	});
-
-	it("returns a domain template when no recipe and no guide exists", async () => {
-		const text = contentText(await callLearn("somedomain.com"));
-		expect(text).toContain(stagedPath("somedomain.com"));
-		// The authoring manual travels with the staged template.
-		expect(text).toContain("authoring manual");
-		const draft = readFileSync(stagedPath("somedomain.com"), "utf-8");
-		expect(draft).toContain("domains: [somedomain.com]");
-	});
-
-	it("rejects a path-traversal domain without writing", async () => {
-		// Guards assertSafeDomain at the api-learn write boundary.
-		setUserGuidesDir(tmpGuidesDir);
-		const result = await apiLearnTool.execute(
-			"test",
-			{
-				domain: "../../escape",
-				// assertSafeDomain rejects before this path is ever read.
-				dir: join(tmpStagingRoot, "escape"),
-			},
-			undefined,
-			undefined,
-			undefined as any,
-		);
-		const text = contentText(result);
-		expect(text).toContain("Invalid domain");
-		expect(result.details).toMatchObject({
-			error: "invalid_domain",
-			domain: "../../escape",
-		});
-		// Nothing written outside the guides dir.
-		expect(() =>
-			readFileSync(join(tmpGuidesDir, "..", "..", "escape", "guide.md"), "utf-8"),
-		).toThrow();
-	});
-
-	it("rejects a description over 200 chars without writing", async () => {
-		// Strict-on-write: the parser accepts any length (lenient-on-read),
-		// but api-learn rejects >200 before writing.
-		setUserGuidesDir(tmpGuidesDir);
-		const longDesc = "x".repeat(201);
-		const recipe = `---
-schemaVersion: 1
-kind: api
-domains: [toolong.example]
-description: ${longDesc}
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: get
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const result = await callLearn("toolong.example", recipe);
-		const text = contentText(result);
-		expect(text).toContain("NOT saved");
-		expect(text).toContain("description");
-		expect(text).toContain("201");
-		expect(result.details).toMatchObject({ error: "description_too_long" });
-		expect(() =>
-			readFileSync(join(tmpGuidesDir, "toolong-example", "guide.md"), "utf-8"),
-		).toThrow();
-	});
-
-	it("accepts a description at exactly 200 chars", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		const desc = "x".repeat(200);
-		const recipe = `---
-schemaVersion: 1
-kind: api
-domains: [boundary.example]
-description: ${desc}
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: get
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const text = contentText(await callLearn("boundary.example", recipe));
-		expect(text).toContain("Guide saved");
-	});
-
-	it("warns (does not reject) when domains collide with another guide", async () => {
-		// Two guides, same `domains:` key, different directories. Valid — that's
-		// the multi-recipe point. The write succeeds with a warning.
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const first = `---
-schemaVersion: 1
-kind: api
-domains: [collide.example]
-organization: collide.org
-description: First surface.
-shortName: First
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: getFirst
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const second = `---
-schemaVersion: 1
-kind: api
-domains: [collide.example]
-organization: collide.org
-description: Second surface.
-shortName: Second
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: getSecond
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const firstText = contentText(await callLearn("collide-first", first));
-		expect(firstText).toContain("Guide saved");
-		expect(firstText).not.toContain("Multi-recipe");
-		invalidateCache();
-		const secondText = contentText(await callLearn("collide-second", second));
-		expect(secondText).toContain("Guide saved");
-		expect(secondText).toContain("Multi-recipe");
-		// The collision warning renders the slug (slug("Second") = "second"),
-		// not the `domain` arg "collide-second".
-		expect(secondText).toContain("writing to directory `second`");
-		expect(secondText).toContain("collide.example");
-	});
-
-	it("warns about a missing description when colliding", async () => {
-		// When the second guide collides and omits description:, api-learn
-		// recommends adding one (the primary disambiguation signal).
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const first = `---
-schemaVersion: 1
-kind: api
-domains: [nodesc.example]
-organization: nodesc.org
-description: First surface.
-shortName: First
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: getFirst
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const second = `---
-schemaVersion: 1
-kind: api
-domains: [nodesc.example]
-organization: nodesc.org
-shortName: Second
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: getSecond
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		await callLearn("nodesc-first", first);
-		invalidateCache();
-		const text = contentText(await callLearn("nodesc-second", second));
-		expect(text).toContain("Guide saved");
-		expect(text).toContain("Multi-recipe");
-		expect(text).toContain("description");
-		expect(text).toContain("recommended");
-	});
-
-	it("collision warning names /api delete as the recovery gesture", async () => {
-		// The agent has no delete tool — when an existing guide is wrong, the
-		// collision warning must point at the human-typed /api delete command,
-		// naming the colliding directory (the one to remove).
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const first = `---
-schemaVersion: 1
-kind: api
-domains: [recover.example]
-organization: recover.org
-shortName: First
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: getFirst
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const second = `---
-schemaVersion: 1
-kind: api
-domains: [recover.example]
-organization: recover.org
-shortName: Second
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: getSecond
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		await callLearn("recover-first", first);
-		invalidateCache();
-		const text = contentText(await callLearn("recover-second", second));
-		expect(text).toContain("Multi-recipe");
-		// The existing guide's dirName is slug(shortName) = "first".
-		expect(text).toContain("/api delete first");
-		expect(text).toContain("the agent has no delete tool");
-	});
-
-	it("does not warn when updating the same guide's own directory", async () => {
-		// Updating `foo.example` when `foo.example` already claims the domain is
-		// not a collision — same dirName. No warning.
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const r1 = `---
-schemaVersion: 1
-kind: api
-domains: [solo.example]
-shortName: Solo
-apiHost: ${ctx.serverUrl}
-operations:
-  - name: get
-    via: restGet
-    path: /x
-    accept: json
----
-`;
-		const r2 = r1.replace("name: get\n", "name: getMore\n");
-		await callLearn("solo.example", r1);
-		invalidateCache();
-		const text = contentText(await callLearn("solo.example", r2));
-		expect(text).toContain("Guide saved");
-		expect(text).not.toContain("Multi-recipe");
-	});
-
-	// The template is the docs-side discoverability: no hardcoded
-	// updated/verified dates (the tool stamps them when omitted) and a
-	// static-key auth block to crib from.
-	it("template has no hardcoded updated/verified dates", async () => {
-		const text = contentText(
-			await callLearn("example.com", undefined, { new: true }),
-		);
-		expect(text).toContain(stagedPath("example.com"));
-		const example = readFileSync(stagedPath("example.com"), "utf-8");
-		expect(example).not.toMatch(/^updated:/m);
-		expect(example).not.toMatch(/^verified:/m);
-		expect(example).toContain("stamped by the tool when omitted");
-	});
-
-	it("template documents the static-key auth block", async () => {
-		const text = contentText(
-			await callLearn("example.com", undefined, { new: true }),
-		);
-		expect(text).toContain(stagedPath("example.com"));
-		const example = readFileSync(stagedPath("example.com"), "utf-8");
-		expect(example).toContain("kind: static-key");
-		expect(example).toContain("secret: <secret-name>");
-		expect(example).toContain("secretRefs:");
-		expect(example).toContain('prefix: "Bearer "');
-	});
-
-	// Write path — api-learn stamps schemaVersion on save.
-	it("stamps schemaVersion on save when the recipe omits it", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const recipe = `---\nkind: api\ndomains: [stamp-absent.example]\nshortName: StampAbsent\napiHost: ${ctx.serverUrl}\noperations:\n  - name: get\n    via: restGet\n    path: /x\n    accept: json\n---\nProse body.\n`;
-		await callLearn("stamp-absent.example", recipe);
-		const raw = readFileSync(
-			join(tmpGuidesDir, "stampabsent", "guide.md"),
-			"utf-8",
-		);
-		expect(raw).toMatch(/^schemaVersion: 1$/m);
-		// Prose body untouched.
-		expect(raw).toContain("Prose body.");
-	});
-
-	it("replaces an explicit divergent schemaVersion on save", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const recipe = `---\nkind: api\nschemaVersion: 5\ndomains: [stamp-replace.example]\nshortName: StampReplace\napiHost: ${ctx.serverUrl}\noperations:\n  - name: get\n    via: restGet\n    path: /x\n    accept: json\n---\n`;
-		await callLearn("stamp-replace.example", recipe);
-		const raw = readFileSync(
-			join(tmpGuidesDir, "stampreplace", "guide.md"),
-			"utf-8",
-		);
-		expect(raw).toMatch(/^schemaVersion: 1$/m);
-		expect(raw).not.toMatch(/^schemaVersion: 5$/m);
-	});
-
-	it("never touches a schemaVersion string in the prose body", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const recipe = `---\nkind: api\ndomains: [stamp-prose.example]\nshortName: StampProse\napiHost: ${ctx.serverUrl}\noperations:\n  - name: get\n    via: restGet\n    path: /x\n    accept: json\n---\nThe schemaVersion: 5 in this prose must stay untouched.\n`;
-		await callLearn("stamp-prose.example", recipe);
-		const raw = readFileSync(
-			join(tmpGuidesDir, "stampprose", "guide.md"),
-			"utf-8",
-		);
-		// Frontmatter got the stamp...
-		expect(raw).toMatch(/^schemaVersion: 1$/m);
-		// ...and the prose line is untouched (still schemaVersion: 5).
-		expect(raw).toContain(
-			"The schemaVersion: 5 in this prose must stay untouched.",
-		);
-	});
-
-	it("preserves comments and key order when stamping", async () => {
-		setUserGuidesDir(tmpGuidesDir);
-		invalidateCache();
-		const recipe = `---\nkind: api\ndomains: [stamp-order.example]\n# a comment that must survive\nshortName: StampOrder\napiHost: ${ctx.serverUrl}\noperations:\n  - name: get\n    via: restGet\n    path: /x\n    accept: json\n---\n`;
-		await callLearn("stamp-order.example", recipe);
-		const raw = readFileSync(
-			join(tmpGuidesDir, "stamporder", "guide.md"),
-			"utf-8",
-		);
-		expect(raw).toContain("# a comment that must survive");
-		// Key order preserved; schemaVersion inserted after operations, before
-		// the closing --- (no YAML round-trip).
-		const idxDomains = raw.indexOf("domains:");
-		const idxShort = raw.indexOf("shortName:");
-		const idxApi = raw.indexOf("apiHost:");
-		const idxOps = raw.indexOf("operations:");
-		const idxSV = raw.indexOf("schemaVersion: 1");
-		expect(idxDomains).toBeLessThan(idxShort);
-		expect(idxShort).toBeLessThan(idxApi);
-		expect(idxApi).toBeLessThan(idxOps);
-		expect(idxOps).toBeLessThan(idxSV);
-	});
-});
-
 /** A recipe for the large-response endpoint (spill truncation). */
 function largeResponseRecipe(apiHost: string): string {
 	return `---
@@ -1597,7 +1082,6 @@ describe("api-fetch", () => {
 			parsed = JSON.parse(fileContent);
 		} catch {
 			expect.fail("Spill file contains invalid JSON");
-			return;
 		}
 		expect(Array.isArray((parsed as Record<string, unknown>).results)).toBe(true);
 		expect(