@soloworks/smking-next 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @soloworks/smking-next
 
+## 0.9.1 — 2026-05-13
+
+**`smking-next doctor` subcommand for self-check + machine-readable output.** The CLI bin now accepts two subcommands: `install` (existing one-shot scaffold) and the new `doctor` (self-check). With `--json`, doctor emits structured output for the new `@smking/wizard` install agent's `run_doctor` tool.
+
+### What's new
+
+`npx @soloworks/smking-next doctor` runs four checks:
+
+- `SMKING_API_KEY` set (and starts with `pk_`)
+- `SMKING_BASE_URL` set (and starts with `http`)
+- `<SmkingAEO />` imported in the root `app/layout.{tsx,jsx,ts,js}`
+- Live probe of `${SMKING_BASE_URL}/api/v1/public/aeo` (3s timeout)
+
+Exit code is `0` when every required check passes, `1` otherwise. Identical between pretty and JSON modes.
+
+### `--json` shape
+
+```json
+{
+  "checks": [
+    { "name": "...", "status": "pass" | "fail" | "info", "detail": "..." }
+  ],
+  "summary": { "passed": N, "failed": N, "info": N, "ok": <bool> }
+}
+```
+
+`summary.ok` is the short-circuit boolean for agentic consumers. The shape is a stable wizard contract — schema changes will bump wizard version.
+
+### Why
+
+Mirrors `smking/laravel`'s `php artisan smking:doctor --json` (v0.10.1). The `@smking/wizard` CLI now runs the same install verification step for both stacks without needing to scrape ANSI-coloured terminal output.
+
+Pure addition — existing `npx @soloworks/smking-next install` calls are unchanged, default behaviour preserved.
+
+## 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,291 @@
+#!/usr/bin/env node
+/**
+ * `npx @soloworks/smking-next [install|doctor] [--json]`
+ *
+ * Two subcommands share this entry point (Node 22+ strips TS at runtime, so
+ * the package ships .ts source directly — no build step):
+ *
+ * - **install** (default) — One-shot scaffold for the three takeover
+ *   drop-in files (sitemap.ts / robots.ts / llms.txt route). Idempotent:
+ *   already-existing files are skipped, never overwritten.
+ *
+ * - **doctor** — Self-check (env presence + <SmkingAEO /> usage + API
+ *   reachable). `--json` flag emits structured output for the
+ *   @smking/wizard install agent's `run_doctor` MCP tool.
+ *
+ * Conventional Next.js layout assumed: `app/` at repo root (or under
+ * `src/app/` — detected). Both subcommands exit 1 on missing app/.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ── install (既有功能) ──────────────────────────────────────────
+
+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 runInstall(): 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;
+}
+
+// ── doctor (新增) ──────────────────────────────────────────────
+
+interface DoctorCheck {
+  name: string;
+  status: "pass" | "fail" | "info";
+  detail: string;
+}
+
+function checkEnv(name: string, prefix?: string): DoctorCheck {
+  const value = process.env[name];
+  if (!value) {
+    return {
+      name: `${name} set`,
+      status: "fail",
+      detail: `not set; add ${name}=... to .env.local`,
+    };
+  }
+  if (prefix && !value.startsWith(prefix)) {
+    return {
+      name: `${name} set`,
+      status: "fail",
+      detail: `value must start with \`${prefix}\``,
+    };
+  }
+  return {
+    name: `${name} set`,
+    status: "pass",
+    detail: `${value.slice(0, 8)}…`,
+  };
+}
+
+function checkLayoutUsage(appDir: string): DoctorCheck {
+  // Mirror Next.js's layout file resolution. Order matters — TS > JS to
+  // match what Next.js itself would pick.
+  const candidates = [
+    join(appDir, "layout.tsx"),
+    join(appDir, "layout.jsx"),
+    join(appDir, "layout.ts"),
+    join(appDir, "layout.js"),
+  ];
+  const layoutPath = candidates.find((p) => existsSync(p));
+  if (!layoutPath) {
+    return {
+      name: "<SmkingAEO /> in root layout",
+      status: "info",
+      detail: `no layout file found under ${appDir}/ — skipped`,
+    };
+  }
+
+  const content = readFileSync(layoutPath, "utf-8");
+  // Substring check is intentional rather than AST parsing. A customer
+  // commenting it out or aliasing the import shows up as fail/info either
+  // way, and AST adds a TypeScript parser dependency for trivial value.
+  if (!content.includes("SmkingAEO")) {
+    return {
+      name: "<SmkingAEO /> in root layout",
+      status: "fail",
+      detail: `${layoutPath} does not import SmkingAEO. Add: import { SmkingAEO } from "@soloworks/smking-next"; then render <SmkingAEO apiKey={process.env.SMKING_API_KEY!} /> inside <body>.`,
+    };
+  }
+  return {
+    name: "<SmkingAEO /> in root layout",
+    status: "pass",
+    detail: layoutPath,
+  };
+}
+
+async function checkApiReachable(): Promise<DoctorCheck> {
+  const apiKey = process.env.SMKING_API_KEY;
+  const baseUrl = process.env.SMKING_BASE_URL;
+  if (!apiKey || !baseUrl) {
+    return {
+      name: "API reachable",
+      status: "info",
+      detail: "skipped — SMKING_API_KEY or SMKING_BASE_URL not set",
+    };
+  }
+
+  // Probe the actual AEO endpoint, not the base URL root. Hitting root
+  // would pass for any live host (a typo'd domain, google.com); the
+  // endpoint either returns the AEO payload or a known auth/validation
+  // status — both confirm the route exists.
+  const url = `${baseUrl.replace(/\/$/, "")}/api/v1/public/aeo?path=%2F`;
+  try {
+    const res = await fetch(url, {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(3000),
+    });
+
+    if (res.ok) {
+      return {
+        name: "API reachable",
+        status: "pass",
+        detail: `${url} → HTTP ${res.status}`,
+      };
+    }
+    if (res.status === 401) {
+      return {
+        name: "API reachable",
+        status: "fail",
+        detail: `HTTP 401 from ${url} — SMKING_API_KEY rejected`,
+      };
+    }
+    if (res.status === 404) {
+      return {
+        name: "API reachable",
+        status: "fail",
+        detail: `HTTP 404 from ${url} — base_url likely points at the wrong host`,
+      };
+    }
+    if (res.status >= 500) {
+      return {
+        name: "API reachable",
+        status: "fail",
+        detail: `upstream HTTP ${res.status} from ${url}`,
+      };
+    }
+    // 4xx (other than 401/404) — likely validation error, endpoint exists
+    return {
+      name: "API reachable",
+      status: "info",
+      detail: `${url} → HTTP ${res.status} (endpoint exists)`,
+    };
+  } catch (err) {
+    return {
+      name: "API reachable",
+      status: "fail",
+      detail: `connection failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+async function runDoctor(jsonOutput: boolean): Promise<number> {
+  const appDir = detectAppDir();
+  const checks: DoctorCheck[] = [
+    checkEnv("SMKING_API_KEY", "pk_"),
+    checkEnv("SMKING_BASE_URL", "http"),
+    appDir
+      ? checkLayoutUsage(appDir)
+      : {
+          name: "<SmkingAEO /> in root layout",
+          status: "info" as const,
+          detail: "no app/ or src/app/ directory found — skipped",
+        },
+    await checkApiReachable(),
+  ];
+
+  const hasFailure = checks.some((c) => c.status === "fail");
+
+  // JSON mode: parseable structured output for @smking/wizard's run_doctor
+  // tool. Stable shape — do not break without bumping wizard version.
+  if (jsonOutput) {
+    const summary = {
+      passed: checks.filter((c) => c.status === "pass").length,
+      failed: checks.filter((c) => c.status === "fail").length,
+      info: checks.filter((c) => c.status === "info").length,
+      ok: !hasFailure,
+    };
+    console.log(JSON.stringify({ checks, summary }));
+    return hasFailure ? 1 : 0;
+  }
+
+  for (const check of checks) {
+    const icon =
+      check.status === "pass"
+        ? "✅"
+        : check.status === "fail"
+          ? "❌"
+          : "ℹ️ ";
+    console.log(`${icon} ${check.name} — ${check.detail}`);
+  }
+  console.log();
+  if (hasFailure) {
+    console.log("❌ smking: install incomplete — fix the items above.");
+    return 1;
+  }
+  console.log("✅ smking: install OK.");
+  return 0;
+}
+
+// ── Entry dispatcher ────────────────────────────────────────────
+
+async function main(): Promise<number> {
+  const subcommand = process.argv[2];
+  const jsonOutput = process.argv.includes("--json");
+
+  if (subcommand === "doctor") {
+    return runDoctor(jsonOutput);
+  }
+  if (subcommand === "install" || subcommand === undefined) {
+    return runInstall();
+  }
+  console.error(
+    `Unknown subcommand: ${subcommand}. Available: install (default), doctor.`,
+  );
+  return 1;
+}
+
+main().then((code) => process.exit(code));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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, "'");
+}