@soloworks/smking-next 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @soloworks/smking-next
 
+## 0.9.0 — 2026-05-12
+
+**Drop-in takeover for `/sitemap.xml`, `/robots.txt`, and `/llms.txt` plus a one-shot install CLI.** Customers with no sitemap (or a broken one), no `robots.txt`, or no `llms.txt` for AI agents previously had to write all three themselves. With v0.9.0 the SDK serves them from the smking SaaS — one line of customer code per file, scaffolded automatically.
+
+### New exports
+
+- `@soloworks/smking-next/sitemap` — `default` export for `app/sitemap.ts`. Fetches `/api/v1/public/sitemap.xml`, returns Next.js `MetadataRoute.Sitemap` shape.
+- `@soloworks/smking-next/robots` — gains a new `default` export for `app/robots.ts` (returns `Response` with `Content-Type: text/plain`, since `MetadataRoute.Robots` can't carry the `Content-Signal:` directive). Existing named exports (`smkingRobotsRules`, `smkingRobotsTxt`) are unchanged — no breaking change.
+- `@soloworks/smking-next/llms-txt` — `GET` export for `app/llms.txt/route.ts`. Proxies `/api/v1/public/llms-txt`.
+
+All three carry an `X-Smking-Takeover: <kind>` response header so audits can confirm the SDK is the one serving.
+
+### One-shot install CLI
+
+```bash
+npx @soloworks/smking-next install
+```
+
+Scaffolds `app/sitemap.ts`, `app/robots.ts`, and `app/llms.txt/route.ts` with one-line re-exports pointing at the SDK helpers. Idempotent — skips any file that already exists, never overwrites customer code. Reports created vs skipped counts.
+
+### Customer-side usage (after running the CLI, the files are these single lines)
+
+```ts
+// app/sitemap.ts
+export { default } from "@soloworks/smking-next/sitemap";
+
+// app/robots.ts
+export { default } from "@soloworks/smking-next/robots";
+
+// app/llms.txt/route.ts
+export { GET } from "@soloworks/smking-next/llms-txt";
+```
+
+### Opt-out
+
+Set any of these env vars to `1` to disable takeover for that file (helper falls back to a permissive default or a 404 — your build won't break):
+
+```dotenv
+SMKING_DISABLE_TAKEOVER_SITEMAP=1
+SMKING_DISABLE_TAKEOVER_ROBOTS=1
+SMKING_DISABLE_TAKEOVER_LLMS_TXT=1
+```
+
+### Why this matters
+
+Aligns Next.js parity with `smking/laravel` v0.9.0's path-takeover middleware: both stacks now have a "set and forget" story for the three canonical AEO/SEO infrastructure files. Sites that fail `sitemap_xml` / `robots_txt` in `auditAgentReadiness` will start passing automatically after the install CLI runs once.
+
 ## 0.8.0 — 2026-05-05
 
 **Renamed from `@smking/next` → `@soloworks/smking-next`.** First-time npm publish discovered the `smking` scope was already taken on the registry; rather than build a new brand around a different scope, we kept the product name `smking-next` in the package name and shipped under the existing `@soloworks` org. No prior version was ever published on npm under `@smking/next`, so no downstream upgrade pain — first install everywhere is `pnpm add @soloworks/smking-next`.

package/bin/install.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * `npx @soloworks/smking-next install`
+ *
+ * One-shot scaffold for the three takeover drop-in files. Idempotent: if a
+ * file already exists, we leave it alone and tell the user — never
+ * overwrite customer code. Each generated file is one line of re-export
+ * pointing at the SDK helper that does the real work.
+ *
+ * Conventional Next.js layout assumed: `app/` at repo root (or under
+ * `src/app/` — detected). The CLI exits 1 if neither exists.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+interface FileSpec {
+  path: string; // relative to detected app root
+  content: string;
+  label: string;
+}
+
+const FILES: FileSpec[] = [
+  {
+    path: "sitemap.ts",
+    label: "sitemap.ts → /sitemap.xml",
+    content:
+      'export { default } from "@soloworks/smking-next/sitemap";\n',
+  },
+  {
+    path: "robots.ts",
+    label: "robots.ts → /robots.txt",
+    content:
+      'export { default } from "@soloworks/smking-next/robots";\n',
+  },
+  {
+    path: "llms.txt/route.ts",
+    label: "llms.txt/route.ts → /llms.txt",
+    content:
+      'export { GET } from "@soloworks/smking-next/llms-txt";\n',
+  },
+];
+
+function detectAppDir(): string | null {
+  const candidates = ["app", "src/app"];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+function main(): number {
+  const appDir = detectAppDir();
+  if (!appDir) {
+    console.error(
+      "❌ No app/ or src/app/ directory found. Run this from your Next.js project root.",
+    );
+    return 1;
+  }
+  console.log(`📂 Using app directory: ${appDir}/\n`);
+
+  let created = 0;
+  let skipped = 0;
+  for (const file of FILES) {
+    const fullPath = join(appDir, file.path);
+    if (existsSync(fullPath)) {
+      console.log(`⊝  skip:    ${file.label} (already exists)`);
+      skipped += 1;
+      continue;
+    }
+    const dir = fullPath.includes("/")
+      ? fullPath.substring(0, fullPath.lastIndexOf("/"))
+      : appDir;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(fullPath, file.content, "utf-8");
+    console.log(`✓  created: ${file.label}`);
+    created += 1;
+  }
+
+  console.log(
+    `\n${created} created, ${skipped} skipped. Set SMKING_API_KEY and SMKING_BASE_URL in your environment.`,
+  );
+  return 0;
+}
+
+process.exit(main());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",
@@ -22,10 +22,22 @@
     "./robots": {
       "types": "./src/lib/robots.ts",
       "default": "./src/lib/robots.ts"
+    },
+    "./sitemap": {
+      "types": "./src/lib/sitemap.ts",
+      "default": "./src/lib/sitemap.ts"
+    },
+    "./llms-txt": {
+      "types": "./src/lib/llms-txt-route.ts",
+      "default": "./src/lib/llms-txt-route.ts"
     }
   },
+  "bin": {
+    "smking-next": "./bin/install.ts"
+  },
   "files": [
     "src",
+    "bin",
     "README.md",
     "CHANGELOG.md"
   ],

package/src/lib/llms-txt-route.ts

@@ -0,0 +1,48 @@
+/**
+ * Drop-in `app/llms.txt/route.ts` GET handler. Proxies the canonical
+ * llms.txt served by the smking SaaS at `/api/v1/public/llms-txt?key=...`.
+ *
+ *   ```ts
+ *   // app/llms.txt/route.ts
+ *   export { GET } from "@soloworks/smking-next/llms-txt";
+ *   ```
+ *
+ * The SaaS endpoint generates the markdown index from
+ * `product_content where status = 'ready'`, so as soon as the customer
+ * approves any new content via the dashboard / chat agent, this file
+ * reflects it on the next request (subject to Next.js cache TTL).
+ *
+ * Opt out: `SMKING_DISABLE_TAKEOVER_LLMS_TXT=1` → 404.
+ */
+export async function GET(): Promise<Response> {
+  if (process.env.SMKING_DISABLE_TAKEOVER_LLMS_TXT === "1") {
+    return new Response("Not found", { status: 404 });
+  }
+  const apiKey = process.env.SMKING_API_KEY;
+  if (!apiKey) {
+    return new Response("Not found", { status: 404 });
+  }
+  const baseUrl = process.env.SMKING_BASE_URL ?? "https://saas.smking.com";
+
+  try {
+    const res = await fetch(
+      `${baseUrl}/api/v1/public/llms-txt?key=${encodeURIComponent(apiKey)}`,
+      {
+        next: { revalidate: 3600 },
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    if (!res.ok) {
+      return new Response("Not found", { status: 404 });
+    }
+    const body = await res.text();
+    return new Response(body, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "X-Smking-Takeover": "llms_txt",
+      },
+    });
+  } catch {
+    return new Response("Not found", { status: 404 });
+  }
+}

package/src/lib/robots.ts

@@ -166,3 +166,60 @@ function toArray<T>(value: T | T[] | undefined): T[] {
   if (value === undefined) return [];
   return Array.isArray(value) ? value : [value];
 }
+
+/**
+ * Drop-in `app/robots.ts` default export. Fetches the canonical robots.txt
+ * served by the smking SaaS at `/api/v1/public/robots.txt?key=...` and
+ * returns a `Response` with `text/plain`. Customer code stays one line:
+ *
+ *   ```ts
+ *   // app/robots.ts
+ *   export { default } from "@soloworks/smking-next/robots";
+ *   ```
+ *
+ * Next.js detects an `app/robots.ts` default export with a Response return
+ * and treats the file as a route handler for `/robots.txt`. This bypasses
+ * the `MetadataRoute.Robots` type, which can't carry `Content-Signal:`.
+ *
+ * Customers who prefer the per-rule helper API (because they want to mix
+ * smking's AI bot block with their own rules in a typed `MetadataRoute.Robots`)
+ * can still import `smkingRobotsRules` / `smkingRobotsTxt` by name — those
+ * named exports remain available from this same module.
+ *
+ * Opt out: `SMKING_DISABLE_TAKEOVER_ROBOTS=1` returns a permissive
+ * `User-agent: *  Allow: /` body (build doesn't break). Same for missing
+ * `SMKING_API_KEY` — fail-open with the safe default.
+ */
+export default async function smkingRobotsRoute(): Promise<Response> {
+  const permissiveFallback = () =>
+    new Response("User-agent: *\nAllow: /\n", {
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+
+  if (process.env.SMKING_DISABLE_TAKEOVER_ROBOTS === "1") {
+    return permissiveFallback();
+  }
+  const apiKey = process.env.SMKING_API_KEY;
+  if (!apiKey) return permissiveFallback();
+  const baseUrl = process.env.SMKING_BASE_URL ?? "https://saas.smking.com";
+
+  try {
+    const res = await fetch(
+      `${baseUrl}/api/v1/public/robots.txt?key=${encodeURIComponent(apiKey)}`,
+      {
+        next: { revalidate: 86_400 },
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    if (!res.ok) return permissiveFallback();
+    const body = await res.text();
+    return new Response(body, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "X-Smking-Takeover": "robots",
+      },
+    });
+  } catch {
+    return permissiveFallback();
+  }
+}

package/src/lib/sitemap.ts

@@ -0,0 +1,87 @@
+import type { MetadataRoute } from "next";
+
+/**
+ * Drop-in `app/sitemap.ts` default export. Fetches the canonical sitemap
+ * served by the smking SaaS at `/api/v1/public/sitemap.xml?key=...`, parses
+ * the XML, and returns Next.js's `MetadataRoute.Sitemap` shape so the
+ * framework can build the static sitemap at request time.
+ *
+ *   ```ts
+ *   // app/sitemap.ts
+ *   export { default } from "@soloworks/smking-next/sitemap";
+ *   ```
+ *
+ * One line of customer code; everything else lives here. The SaaS endpoint
+ * derives URLs from `site_pages` (sitemap → wc_api → homepage_crawl →
+ * product_content → manual → sdk_traffic discovery tiers) so even sites
+ * with no upstream sitemap end up with a complete inventory.
+ *
+ * Customer can opt out by setting `SMKING_DISABLE_TAKEOVER_SITEMAP=1` —
+ * the helper returns an empty array, letting any subsequent sitemap
+ * source (e.g. next-sitemap) take over without crashing the build.
+ *
+ * Required env:
+ *   - `SMKING_API_KEY`        (publishable, the `pk_…` key)
+ *   - `SMKING_BASE_URL`       (defaults to https://saas.smking.com)
+ */
+export default async function smkingSitemap(): Promise<MetadataRoute.Sitemap> {
+  if (process.env.SMKING_DISABLE_TAKEOVER_SITEMAP === "1") return [];
+  const apiKey = process.env.SMKING_API_KEY;
+  if (!apiKey) return [];
+  const baseUrl = process.env.SMKING_BASE_URL ?? "https://saas.smking.com";
+
+  let body: string;
+  try {
+    const res = await fetch(
+      `${baseUrl}/api/v1/public/sitemap.xml?key=${encodeURIComponent(apiKey)}`,
+      {
+        // Daily revalidation — sitemap doesn't change second-to-second.
+        // Customer can override via env if their build cadence differs.
+        next: { revalidate: 86_400 },
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    if (!res.ok) return [];
+    body = await res.text();
+  } catch {
+    return [];
+  }
+
+  return parseSitemapEntries(body);
+}
+
+/**
+ * Pure XML → MetadataRoute.Sitemap conversion. Lives outside the default
+ * export so the unit test can drive it without a fetch mock.
+ */
+export function parseSitemapEntries(xml: string): MetadataRoute.Sitemap {
+  const entries: MetadataRoute.Sitemap = [];
+  const urlBlockRe = /<url>([\s\S]*?)<\/url>/g;
+  const locRe = /<loc>([^<]+)<\/loc>/;
+  const lastmodRe = /<lastmod>([^<]+)<\/lastmod>/;
+
+  let match: RegExpExecArray | null;
+  while ((match = urlBlockRe.exec(xml)) !== null) {
+    const block = match[1];
+    const loc = block.match(locRe)?.[1]?.trim();
+    if (!loc) continue;
+    const lastmodStr = block.match(lastmodRe)?.[1]?.trim();
+    const lastModified = lastmodStr ? new Date(lastmodStr) : undefined;
+    entries.push({
+      url: decodeXmlEntities(loc),
+      ...(lastModified && !Number.isNaN(lastModified.getTime())
+        ? { lastModified }
+        : {}),
+    });
+  }
+  return entries;
+}
+
+function decodeXmlEntities(s: string): string {
+  return s
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'");
+}