@soloworks/smking-next 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @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.

package/bin/install.ts

@@ -1,18 +1,26 @@
 #!/usr/bin/env node
 /**
- * `npx @soloworks/smking-next install`
+ * `npx @soloworks/smking-next [install|doctor] [--json]`
  *
- * 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.
+ * 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). The CLI exits 1 if neither exists.
+ * `src/app/` — detected). Both subcommands exit 1 on missing app/.
  */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+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;
@@ -48,7 +56,7 @@ function detectAppDir(): string | null {
   return null;
 }
 
-function main(): number {
+function runInstall(): number {
   const appDir = detectAppDir();
   if (!appDir) {
     console.error(
@@ -82,4 +90,202 @@ function main(): number {
   return 0;
 }
 
-process.exit(main());
+// ── 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.9.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",