@soloworks/smking-next 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @soloworks/smking-next
 
+## 0.12.2 — 2026-05-21
+
+**Fix: `doctor` now auto-loads `.env.local` + `.env` matching Next.js convention.**
+
+### Fixed
+
+- `npx @soloworks/smking-next doctor` was reporting `SMKING_API_KEY not set` even when the wizard had just written keys to `.env.local`. Cause: standalone Node bin script doesn't get Next.js framework env loading — only `next dev` / `next build` parse `.env.local`. Customer mental model expected doctor to mirror `next dev`.
+- `runDoctor` now calls `process.loadEnvFile()` (Node 20.6+ native, zero deps) for `.env` then `.env.local`. Existing shell env wins (Next.js precedence). Falls through silently if files don't exist or Node is too old — doctor still reports `not set` as it would have anyway.
+
+## 0.12.1 — 2026-05-21
+
+**Fix: `npx @soloworks/smking-next doctor` failed for all customers.**
+
+### Fixed
+
+- `bin/install.ts` shipped as raw TypeScript on the assumption that Node 22+'s `--experimental-strip-types` would handle it. It doesn't — by design, Node excludes files under `node_modules/` from type-stripping (packages should ship compiled JS). Every `npx @soloworks/smking-next install|doctor` invocation failed with "Type-Stripping is not supported for files under node_modules" the moment a customer's install reached the doctor check. smking-wizard reproduced the bug 3× and filed ticket `dr_e0b7d8e924cd`.
+- Renamed to `bin/install.mjs` with TypeScript syntax stripped (JSDoc type hints retained for editor / dev ergonomics). Pure ESM, no build step, no runtime type stripping needed.
+- Source modules (`src/*.ts`) unchanged — Next.js's bundler handles them at customer build time. Only the standalone-executable bin script needed JS form.
+
 ## 0.12.0 — 2026-05-15
 
 **AI crawler + AI referral telemetry — `smkingProxy` Next.js middleware.**

package/README.md

@@ -84,6 +84,71 @@ Content-Type: application/json
 
 Response: `{ revalidated: number, errors: number }`. `errors > 0` means some tags couldn't be revalidated (others still succeeded — partial-success delivery).
 
+## CMS rendering (optional, v0.11.0+)
+
+The base install only wires AEO. If you author content in the smking dashboard's CMS and want to render it on your Next.js site, use the `<SmkingCms slug="…" />` Server Component.
+
+The SDK **does not have a "CMS root" config** — you choose any URL prefix (`/blog`, `/knowledge`, `/shop/articles`) and wire your own route. The component takes a `slug` prop, fetches the published page from `${SMKING_BASE_URL}/api/v1/public/page?slug=…`, and renders the Tiptap ProseMirror JSON as `<article class="smk-cms">…</article>` via `@tiptap/static-renderer/pm/react`. SEO `<title>` / `<meta>` / `og:*` / canonical hoist into `<head>` automatically via React 19.
+
+### Catch-all route (handles flat + nested slugs)
+
+smking CMS slugs can be nested — e.g. `blog/123`, `blog/seo/intro`. Use Next.js catch-all `[...slug]` (three dots, not single `[slug]`) so one route handles every depth:
+
+```tsx
+// app/blog/[...slug]/page.tsx
+import { SmkingCms } from "@soloworks/smking-next/cms";
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>;
+}) {
+  const { slug } = await params;
+  return (
+    <SmkingCms
+      apiKey={process.env.SMKING_API_KEY!}
+      slug={slug.join("/")}  // ← array → "blog/seo/intro" matches dashboard slug format
+    />
+  );
+}
+```
+
+`[...slug]` accepts both flat (`/blog/hello` → `["hello"]`) and nested (`/blog/seo/intro` → `["seo", "intro"]`). The `.join("/")` reconstructs the dashboard slug string.
+
+Single-bracket `[slug]` (without the three dots) **only matches one segment** — pick this if you know your slugs are always flat.
+
+### Markup contract for CSS
+
+```html
+<article class="smk-cms" data-smking="cms">
+  <h1 class="smk-cms__title">…</h1>
+  <p>standard prose</p>
+  <h2>headings</h2>
+  <ul><li>lists</li></ul>
+  <blockquote>…</blockquote>
+  <pre><code>code blocks</code></pre>
+  <a href="…">links</a>
+  <img src="…" alt="…">
+  <div data-type="gallery"
+       data-layout="grid"
+       data-columns="3"
+       class="smk-gallery smk-gallery--grid">
+    <figure class="smk-gallery__item">
+      <img src="…" alt="…" loading="lazy">
+      <figcaption>optional</figcaption>
+    </figure>
+  </div>
+</article>
+```
+
+Standard nodes inherit your site's prose styling. Gallery is the only opinionated structure — provide CSS for `.smk-gallery` (typically a grid with `grid-template-columns: repeat(var(--smk-gallery-cols, 3), 1fr)` since the SDK injects `--smk-gallery-cols` inline).
+
+### Cache invalidation
+
+CMS responses cache for 5 minutes by default via Next.js data cache (`tags: ["smking:cms_page:<slug>"]`). When you publish, rename, or archive a page in the dashboard, smking SaaS POSTs a signed webhook to `https://<your-site>/api/smking/webhook` (mount with one-line re-export — see Install). The handler verifies HMAC against `SMKING_WEBHOOK_SECRET` and calls `revalidateTag` so the next visitor reads fresh content.
+
+If `SMKING_WEBHOOK_SECRET` is unset, the webhook route returns 503 and cache invalidation falls back to TTL-based expiry.
+
 ## Versions
 
 See [CHANGELOG.md](./CHANGELOG.md). Aligned with `smking/laravel` for SaaS-side parity.

package/bin/{install.ts → install.mjs}

@@ -2,8 +2,14 @@
 /**
  * `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):
+ * Two subcommands share this entry point. The file ships as plain ESM
+ * (`.mjs`) since Node's `--experimental-strip-types` is excluded from
+ * files under `node_modules` by design — so `bin/install.ts` (the
+ * previous v0.12.0 layout) fails with "Type-Stripping is not supported
+ * for files under node_modules" the moment a customer runs `npx
+ * @soloworks/smking-next`. Source modules (`src/*.ts`) are still TS —
+ * Next.js's bundler handles them at customer build time. Only this
+ * standalone-executable bin script needed to drop TS.
  *
  * - **install** (default) — One-shot scaffold for the three takeover
  *   drop-in files (sitemap.ts / robots.ts / llms.txt route). Idempotent:
@@ -19,36 +25,32 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-// ── install (既有功能) ──────────────────────────────────────────
+// ── install (file scaffold) ─────────────────────────────────────
 
-interface FileSpec {
-  path: string; // relative to detected app root
-  content: string;
-  label: string;
-}
+/**
+ * @typedef {{ path: string, content: string, label: string }} FileSpec
+ */
 
-const FILES: FileSpec[] = [
+/** @type {FileSpec[]} */
+const FILES = [
   {
     path: "sitemap.ts",
     label: "sitemap.ts → /sitemap.xml",
-    content:
-      'export { default } from "@soloworks/smking-next/sitemap";\n',
+    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',
+    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',
+    content: 'export { GET } from "@soloworks/smking-next/llms-txt";\n',
   },
 ];
 
-function detectAppDir(): string | null {
+function detectAppDir() {
   const candidates = ["app", "src/app"];
   for (const c of candidates) {
     if (existsSync(c)) return c;
@@ -56,7 +58,7 @@ function detectAppDir(): string | null {
   return null;
 }
 
-function runInstall(): number {
+function runInstall() {
   const appDir = detectAppDir();
   if (!appDir) {
     console.error(
@@ -90,15 +92,49 @@ function runInstall(): number {
   return 0;
 }
 
-// ── doctor (新增) ──────────────────────────────────────────────
+// ── doctor (self-check) ─────────────────────────────────────────
 
-interface DoctorCheck {
-  name: string;
-  status: "pass" | "fail" | "info";
-  detail: string;
+/**
+ * Load `.env.local` + `.env` from cwd into `process.env`, matching the
+ * Next.js convention so `npx @soloworks/smking-next doctor` sees the same
+ * env vars the customer's `next dev` / `next build` would. Standalone
+ * Node bin scripts don't get framework env loading for free — without
+ * this, doctor would fail "SMKING_API_KEY not set" on every install where
+ * the wizard wrote to `.env.local` instead of shell env.
+ *
+ * `process.loadEnvFile` is available Node 20.6+ (experimental → stable
+ * in 21.7+). Next.js 16 requires Node 20+ so the customer environment is
+ * guaranteed to have it. Existing process env wins (we don't overwrite —
+ * matches Next.js precedence: shell env > .env.local > .env).
+ *
+ * Files load in reverse-precedence order (lowest first) so later files
+ * win when both define the same key. Next.js's actual order: .env.local
+ * > .env.development.local > .env.development > .env. We do the minimal
+ * pair customers actually use.
+ */
+function loadEnvFiles() {
+  for (const file of [".env", ".env.local"]) {
+    if (!existsSync(file)) continue;
+    try {
+      process.loadEnvFile(file);
+    } catch {
+      // Older Node fallback or unreadable file — silently skip; doctor
+      // will report SMKING_API_KEY not set as it would have anyway.
+    }
+  }
 }
 
-function checkEnv(name: string, prefix?: string): DoctorCheck {
+
+/**
+ * @typedef {{ name: string, status: "pass" | "fail" | "info", detail: string }} DoctorCheck
+ */
+
+/**
+ * @param {string} name
+ * @param {string} [prefix]
+ * @returns {DoctorCheck}
+ */
+function checkEnv(name, prefix) {
   const value = process.env[name];
   if (!value) {
     return {
@@ -121,7 +157,11 @@ function checkEnv(name: string, prefix?: string): DoctorCheck {
   };
 }
 
-function checkLayoutUsage(appDir: string): DoctorCheck {
+/**
+ * @param {string} appDir
+ * @returns {DoctorCheck}
+ */
+function checkLayoutUsage(appDir) {
   // Mirror Next.js's layout file resolution. Order matters — TS > JS to
   // match what Next.js itself would pick.
   const candidates = [
@@ -140,9 +180,6 @@ function checkLayoutUsage(appDir: string): DoctorCheck {
   }
 
   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",
@@ -157,7 +194,10 @@ function checkLayoutUsage(appDir: string): DoctorCheck {
   };
 }
 
-async function checkApiReachable(): Promise<DoctorCheck> {
+/**
+ * @returns {Promise<DoctorCheck>}
+ */
+async function checkApiReachable() {
   const apiKey = process.env.SMKING_API_KEY;
   const baseUrl = process.env.SMKING_BASE_URL;
   if (!apiKey || !baseUrl) {
@@ -222,16 +262,26 @@ async function checkApiReachable(): Promise<DoctorCheck> {
   }
 }
 
-async function runDoctor(jsonOutput: boolean): Promise<number> {
+/**
+ * @param {boolean} jsonOutput
+ * @returns {Promise<number>}
+ */
+async function runDoctor(jsonOutput) {
+  // Mirror Next.js env loading so doctor sees what `next dev` would.
+  // Customers run this from project root; .env.local is the wizard's
+  // write target for SMKING_API_KEY + SMKING_BASE_URL.
+  loadEnvFiles();
+
   const appDir = detectAppDir();
-  const checks: DoctorCheck[] = [
+  /** @type {DoctorCheck[]} */
+  const checks = [
     checkEnv("SMKING_API_KEY", "pk_"),
     checkEnv("SMKING_BASE_URL", "http"),
     appDir
       ? checkLayoutUsage(appDir)
       : {
           name: "<SmkingAEO /> in root layout",
-          status: "info" as const,
+          status: "info",
           detail: "no app/ or src/app/ directory found — skipped",
         },
     await checkApiReachable(),
@@ -272,7 +322,7 @@ async function runDoctor(jsonOutput: boolean): Promise<number> {
 
 // ── Entry dispatcher ────────────────────────────────────────────
 
-async function main(): Promise<number> {
+async function main() {
   const subcommand = process.argv[2];
   const jsonOutput = process.argv.includes("--json");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "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",
@@ -41,7 +41,7 @@
     }
   },
   "bin": {
-    "smking-next": "./bin/install.ts"
+    "smking-next": "./bin/install.mjs"
   },
   "files": [
     "src",