Publish integrations.sh discovery metadata

[rgarcia]

summary

• declare the justhtml.sh HTTP API and its bearer API-key authentication in /.well-known/integrations.json
• publish the generated OpenAPI 3.1 document at the canonical /openapi.json path
• expose the existing just-html skill through the Agent Skills well-known discovery format with a verified content digest
• keep generated JSON, YAML, and TypeScript OpenAPI artifacts covered by the existing drift check

The repository does not ship MCP, GraphQL, or product CLI surfaces, so no declarations were added for those formats. It also has one API surface, so an RFC 9727 API catalog does not apply.

tests

• npx tsc --noEmit
• npm test
• npm run spec:check
• npm run build
• npx --yes @redocly/cli lint lib/openapi/generated.json (valid; 3 existing warnings)
• local production-server curl checks for every discovery route, including Agent Skills digest verification

---

Note

Low Risk
New static read-only discovery routes and generated spec artifacts; no changes to auth, document APIs, or data handling.

Overview
Adds machine-readable discovery for agents and integration platforms: integrations.sh v3 at /.well-known/integrations.json (HTTP API surface, Bearer API key, links to llms.txt and openapi.json), canonical OpenAPI 3.1 JSON at GET /openapi.json (YAML remains at /api/spec.yaml), and Agent Skills discovery (index.json + served SKILL.md with a sha256 digest tied to the skill body).

The OpenAPI pipeline now emits a third committed artifact, lib/openapi/generated.json, alongside the existing YAML/TS outputs; spec-sync, spec:check, and docs/README/homepage/skill copy point at /openapi.json as the primary spec URL.

SKILL_MARKDOWN is centralized in lib/skill-content.ts (used by gen-skill and the well-known skill route). lib/discovery.test.ts asserts integrations shape, OpenAPI JSON headers/content, and digest consistency.

^{Reviewed by Cursor Bugbot for commit 805e270. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
justhtml	Ready	Preview, Comment	Jul 11, 2026 3:05pm

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: OpenAPI route bytes mismatch
  • The /openapi.json route now serializes with two-space indentation and a trailing newline so its response bytes match the committed lib/openapi/generated.json artifact.

Or push these changes by commenting:

@cursor push 3d87b82feb

Preview (3d87b82feb)

diff --git a/app/openapi.json/route.ts b/app/openapi.json/route.ts
--- a/app/openapi.json/route.ts
+++ b/app/openapi.json/route.ts
@@ -2,7 +2,7 @@
 
 export const dynamic = "force-static";
 
-const BODY = JSON.stringify(spec);
+const BODY = `${JSON.stringify(spec, null, 2)}\n`;
 
 export function GET(): Response {
   return new Response(BODY, {

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 805e270. Configure here.}

[cursor]

OpenAPI route bytes mismatch

Medium Severity

The GET /openapi.json endpoint re-serializes the imported generated.json using JSON.stringify(). This produces a compact response that differs byte-for-byte from the pretty-printed, committed lib/openapi/generated.json file. This means the served content doesn't match the canonical artifact validated by spec:check, unlike /api/spec.yaml.

 

^{Reviewed by Cursor Bugbot for commit 805e270. Configure here.}