Merge pull request #117 from speakeasy-api/walker/gram-redirect-url-go-sdk

Add Guide.Render to substitute the OAuth callback URL [minor]

Author: walker-tx

go/README.md

@@ -34,6 +34,32 @@ func main() {
 }
 ```
 
+## Rendering the callback URL
+
+Guide content ships with the template key `{{ gram.oauth.callback_url }}`
+in place. Pass your own value on every lookup to substitute it:
+
+```go
+g, _ := guides.Lookup("intercom")
+
+g = g.Render(guides.Vars{
+	OAuthCallbackURL: "https://app.example.com/oauth/callback",
+})
+os.Stdout.Write(g.External)
+```
+
+- `Render` returns a **copy**. It never changes the embedded content, so a
+  server may render per request with a different value each time.
+- The callback URL is a property of your deployment, not of the guide, so
+  there is nothing to look up first. A guide that never references the key
+  comes back unchanged.
+- An empty `Vars` field leaves its key in place, so a missing value degrades
+  to the unrendered guide instead of a blank.
+- `Render` substitutes `External` and `Speakeasy` only. No template key
+  reaches `Meta` or an asset — the generator fails if one ever does.
+- `{{ gram.oauth.callback_url }}` is the only supported key. Add a field to
+  `Vars` to support another; existing callers keep compiling.
+
 ## Identifiers
 
 - **Canonical:** `ServerRef{Guide, Remote}` text form `slug/remote-id`

go/doc.go

@@ -6,6 +6,12 @@
 // secondary indexes that may return zero, one, or many matches; they never
 // invent a default remote.
 //
+// Guide content ships with the template key {{ gram.oauth.callback_url }}
+// in place. Guide.Render(Vars) returns a copy with a caller-supplied value
+// substituted. Supply the value on every call: it is a property of the
+// deployment, not of the guide, and a guide that never references the key
+// comes back unchanged.
+//
 // Module path: github.com/speakeasy-api/mcp-setup-docs/go
 // Version tags: go/vX.Y.Z
 package guides

go/guides_test.go

@@ -1,6 +1,7 @@
 package guides_test
 
 import (
+	"bytes"
 	"io/fs"
 	"os"
 	"path/filepath"
@@ -10,6 +11,9 @@ import (
 	guides "github.com/speakeasy-api/mcp-setup-docs/go"
 )
 
+// canonicalCallbackKey is the one template key the generator admits.
+const canonicalCallbackKey = "{{ gram.oauth.callback_url }}"
+
 func TestSlugsMatchDisk(t *testing.T) {
 	disk, err := onDiskGuideSlugs()
 	if err != nil {
@@ -429,6 +433,75 @@ func TestQueryMechanisms(t *testing.T) {
 	})
 }
 
+// A caller supplies the callback URL on every Render, so run the whole
+// corpus through one call: no guide may keep the key, and a guide that
+// never carried it must come back byte-identical.
+func TestRenderSubstitutesEveryKey(t *testing.T) {
+	const callback = "https://app.example.com/oauth/callback"
+	key := []byte(canonicalCallbackKey)
+	substituted := 0
+	for _, g := range guides.Guides() {
+		hadKey := bytes.Contains(g.External, key) || bytes.Contains(g.Speakeasy, key)
+		out := g.Render(guides.Vars{OAuthCallbackURL: callback})
+
+		if bytes.Contains(out.External, key) || bytes.Contains(out.Speakeasy, key) {
+			t.Errorf("%s: content still carries the key after Render", g.Slug)
+		}
+		if !bytes.Equal(out.Meta, g.Meta) {
+			t.Errorf("%s: Render must not touch Meta", g.Slug)
+		}
+
+		if !hadKey {
+			if !bytes.Equal(out.External, g.External) || !bytes.Equal(out.Speakeasy, g.Speakeasy) {
+				t.Errorf("%s: Render changed a guide that carries no key", g.Slug)
+			}
+			continue
+		}
+		substituted++
+		if !bytes.Contains(out.External, []byte(callback)) &&
+			!bytes.Contains(out.Speakeasy, []byte(callback)) {
+			t.Errorf("%s: Render substituted nothing", g.Slug)
+		}
+	}
+	if substituted == 0 {
+		t.Fatal("no guide carries the key; the matrix would be vacuous")
+	}
+}
+
+// A missing value must degrade to the unrendered guide, never to a blank
+// where the URL belongs.
+func TestRenderLeavesKeyWhenValueEmpty(t *testing.T) {
+	g, ok := guides.Lookup("intercom")
+	if !ok {
+		t.Fatal("intercom missing")
+	}
+	out := g.Render(guides.Vars{})
+	if !bytes.Contains(out.External, []byte(canonicalCallbackKey)) {
+		t.Error("empty Vars must leave the template key in place")
+	}
+}
+
+// The embedded bytes back every future Lookup, so rendering one copy must
+// not reach them. A caller that renders per request depends on this.
+func TestRenderDoesNotDisturbEmbeddedContent(t *testing.T) {
+	g, ok := guides.Lookup("intercom")
+	if !ok {
+		t.Fatal("intercom missing")
+	}
+	before := string(g.External)
+	_ = g.Render(guides.Vars{OAuthCallbackURL: "https://app.example.com/cb"})
+	if string(g.External) != before {
+		t.Error("Render mutated the Guide it was called on")
+	}
+	again, ok := guides.Lookup("intercom")
+	if !ok {
+		t.Fatal("intercom missing on second lookup")
+	}
+	if !bytes.Contains(again.External, []byte(canonicalCallbackKey)) {
+		t.Error("a later Lookup returned already-rendered content")
+	}
+}
+
 func hasKind(ms []guides.Match, kind guides.MatchKind) bool {
 	for _, m := range ms {
 		if m.Kind == kind {

go/internal/gen/main.go

@@ -21,6 +21,17 @@ import (
 
 var kebab = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
 
+// canonicalCallbackKey is the only template key a guide may carry, in the
+// only spelling it may use. doctrine/constitution.md pins the rule; this
+// generator enforces it so package guides can substitute the key with a
+// literal byte replacement.
+const canonicalCallbackKey = "{{ gram.oauth.callback_url }}"
+
+// templateKeyPattern finds every "{{ … }}" span, including malformed
+// spacing, so a non-canonical key fails generation instead of shipping
+// unrendered. This check is what lets Render match one exact byte string.
+var templateKeyPattern = regexp.MustCompile(`\{\{[^{}]*\}\}`)
+
 type assetMeta struct {
 	Path        string `yaml:"path"`
 	ContentHash string `yaml:"content_hash"`
@@ -200,6 +211,10 @@ func run() error {
 			}
 		}
 
+		if err := scanTemplateKeys(slug, srcDir, raw); err != nil {
+			return err
+		}
+
 		// Rebuild each guide dir from scratch so deleted assets/files cannot linger.
 		dstDir := filepath.Join(outGuides, slug)
 		if err := os.RemoveAll(dstDir); err != nil {
@@ -401,6 +416,33 @@ func run() error {
 	return nil
 }
 
+// scanTemplateKeys enforces the single-template-key rule. One canonical
+// spelling is what lets Guide.Render substitute with a plain byte replace
+// instead of a regexp. metaRaw must carry no key at all: Render substitutes
+// only External and Speakeasy, so a key in meta.yaml would ship to a reader
+// unrendered.
+func scanTemplateKeys(slug, srcDir string, metaRaw []byte) error {
+	if key := templateKeyPattern.Find(metaRaw); key != nil {
+		return fmt.Errorf(
+			"%s: meta.yaml carries template key %s; keys belong in external.md or speakeasy.md only",
+			slug, key)
+	}
+	for _, name := range []string{"external.md", "speakeasy.md"} {
+		data, err := os.ReadFile(filepath.Join(srcDir, name))
+		if err != nil {
+			return fmt.Errorf("%s: read %s: %w", slug, name, err)
+		}
+		for _, key := range templateKeyPattern.FindAllString(string(data), -1) {
+			if key != canonicalCallbackKey {
+				return fmt.Errorf(
+					"%s: %s carries template key %s; %s is the only supported key",
+					slug, name, key, canonicalCallbackKey)
+			}
+		}
+	}
+	return nil
+}
+
 func pruneStaleGuideDirs(outGuides string, slugs []string) error {
 	keep := map[string]struct{}{}
 	for _, s := range slugs {

go/internal/gen/main_test.go

@@ -3,10 +3,18 @@ package main
 import (
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"testing"
 )
 
+// fieldSet reports whether the generated index sets field to value. It
+// ignores the column alignment gofmt applies, which shifts whenever a new
+// field lengthens the struct literal.
+func fieldSet(s, field, value string) bool {
+	return regexp.MustCompile(regexp.QuoteMeta(field) + `:\s+` + regexp.QuoteMeta(value) + `,`).MatchString(s)
+}
+
 func TestNormalizeURLMatchesRuntimeRules(t *testing.T) {
 	cases := map[string]string{
 		"https://mcp.box.com":               "https://mcp.box.com",
@@ -125,8 +133,10 @@ remotes:
     transport: streamable-http
 `
 	for name, body := range map[string]string{
-		"meta.yaml":    meta,
-		"external.md":  "# external\n",
+		"meta.yaml": meta,
+		// The canonical callback key here takes run() through the accept
+		// path of the template scan, not only the rejections below.
+		"external.md":  "# external\n\nEnter {{ gram.oauth.callback_url }} in the field.\n",
 		"speakeasy.md": "# speakeasy\n",
 	} {
 		if err := os.WriteFile(filepath.Join(guidesDir, name), []byte(body), 0o644); err != nil {
@@ -215,17 +225,22 @@ remotes:
 	}
 	for _, want := range []string{
 		"Summary:", "SpeakeasyAddServer:", "https://mcp.example.com/demo", "com.example/demo",
-		"SetupRequired:      true,",
 		`{ID: "oauth-app", Kind: "oauth", ClientRegistration: "manual", UpstreamSetup: "provider-steps", SpeakeasySetup: "manual-oauth"},`,
 	} {
 		if !strings.Contains(string(idx), want) {
 			t.Errorf("index_gen.go missing %q", want)
 		}
 	}
 
+	_, afterDemo, _ := strings.Cut(string(idx), `"demo": {`)
+	demoEntry, _, _ := strings.Cut(afterDemo, "\n\t},")
+	if !fieldSet(demoEntry, "SetupRequired", "true") {
+		t.Errorf("demo should need setup, got:\n%s", demoEntry)
+	}
+
 	_, afterTenant, _ := strings.Cut(string(idx), `"tenant": {`)
 	tenantEntry, _, _ := strings.Cut(afterTenant, "\n\t},")
-	if !strings.Contains(tenantEntry, "SetupRequired:      true,") {
+	if !fieldSet(tenantEntry, "SetupRequired", "true") {
 		t.Errorf("tenanted remote must force SetupRequired=true, got:\n%s", tenantEntry)
 	}
 	// Guards the fixture itself: if its option ever needs setup, the
@@ -235,6 +250,70 @@ remotes:
 	}
 }
 
+// The generator is the only place that enforces the one-key rule, so the
+// rejections matter as much as the happy path: Render substitutes with a
+// literal byte replacement on the strength of this check.
+func TestScanTemplateKeys(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		external  string
+		speakeasy string
+		meta      string
+		errText   string
+	}{
+		{name: "no keys", external: "# external\n", speakeasy: "# speakeasy\n"},
+		{
+			name:     "canonical key in external",
+			external: "Enter " + canonicalCallbackKey + " here.\n",
+		},
+		{
+			name:      "canonical key in speakeasy",
+			speakeasy: "Confirm " + canonicalCallbackKey + " matches.\n",
+		},
+		{
+			name:     "non-canonical spacing",
+			external: "Enter {{gram.oauth.callback_url}} here.\n",
+			errText:  "only supported key",
+		},
+		{
+			name:     "unknown key",
+			external: "Enter {{ gram.server.redirect_uri }} here.\n",
+			errText:  "only supported key",
+		},
+		{
+			name:    "key in meta",
+			meta:    "callback: \"" + canonicalCallbackKey + "\"\n",
+			errText: "meta.yaml carries template key",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			files := map[string]string{
+				"external.md":  "# external\n" + tc.external,
+				"speakeasy.md": "# speakeasy\n" + tc.speakeasy,
+			}
+			for name, body := range files {
+				if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			}
+			err := scanTemplateKeys("demo", dir, []byte("slug: demo\n"+tc.meta))
+			if tc.errText != "" {
+				if err == nil {
+					t.Fatalf("expected an error mentioning %q, got nil", tc.errText)
+				}
+				if !strings.Contains(err.Error(), tc.errText) {
+					t.Fatalf("error %v should mention %q", err, tc.errText)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
 func TestDeriveSpeakeasySetup(t *testing.T) {
 	for _, tc := range []struct {
 		name string

go/render.go

@@ -0,0 +1,39 @@
+package guides
+
+import "bytes"
+
+// callbackURLKey is the one template key the guide corpus uses. The
+// generator rejects every other key, and every other spelling of this one,
+// so a plain byte substitution is enough.
+var callbackURLKey = []byte("{{ gram.oauth.callback_url }}")
+
+// Vars carries the values a consumer substitutes into guide content.
+type Vars struct {
+	// OAuthCallbackURL replaces {{ gram.oauth.callback_url }} — the
+	// Speakeasy AI Control Plane callback URL that the reader registers
+	// in the provider's redirect field.
+	//
+	// Supply it on every Render call. It is a property of the deployment,
+	// not of the guide, so there is nothing to look up first: guides that
+	// never reference it come back unchanged.
+	//
+	// An empty value leaves the key in the content rather than blanking
+	// it, so a missing value degrades to the unrendered guide.
+	OAuthCallbackURL string
+}
+
+// Render returns a copy of g whose External and Speakeasy content has the
+// template keys replaced by the values in v. Meta, Assets, and every
+// identity field are unchanged — no template key appears in meta.yaml or
+// in an asset, and the generator fails if one ever does.
+//
+// Render never changes the embedded content. Each Lookup starts from the
+// unrendered bytes, and rendering one copy does not affect another.
+func (g Guide) Render(v Vars) Guide {
+	if v.OAuthCallbackURL != "" {
+		value := []byte(v.OAuthCallbackURL)
+		g.External = bytes.ReplaceAll(g.External, callbackURLKey, value)
+		g.Speakeasy = bytes.ReplaceAll(g.Speakeasy, callbackURLKey, value)
+	}
+	return g
+}