akeso-check 0.1.0 → 0.1.3

package/bin/akeso-check.mjs

@@ -84,7 +84,7 @@ if (base) {
      up. Removal happens no matter how the run ends. */
   let probeUrl = null;
   let installed = null;
-  for (const candidate of [`${base}/api/__akeso_probe`, `${base}/__akeso_probe`]) {
+  for (const candidate of [`${base}/api/akeso-probe`, `${base}/akeso-probe`, `${base}/api/__akeso_probe`, `${base}/__akeso_probe`]) {
     if (await probeAnswers(candidate)) { probeUrl = candidate; break; }
   }
   if (!probeUrl) {

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "akeso-check",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Prove whether your app grants and revokes paid access correctly. Runs on your machine; nothing leaves it.",
   "type": "module",
-  "bin": { "akeso-check": "bin/akeso-check.mjs" },
+  "bin": {
+    "akeso-check": "bin/akeso-check.mjs"
+  },
   "license": "MIT",
-  "keywords": ["stripe", "billing", "webhooks", "subscriptions", "entitlement", "saas", "testing"],
-  "engines": { "node": ">=20" },
+  "keywords": [
+    "stripe",
+    "billing",
+    "webhooks",
+    "subscriptions",
+    "entitlement",
+    "saas",
+    "testing"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "check": "node bin/akeso-check.mjs",
     "test": "node --test tests/*.test.mjs"

package/src/probe.mjs

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 /* The access probe: a temporary route the Check adds to the founder's app so
@@ -79,9 +79,14 @@ export async function chooseProbeTarget(root, accessDecisionSites) {
   };
 }
 
+/* No path segment may start with an underscore. Next.js treats an
+   underscore-prefixed folder as a PRIVATE folder and excludes it from routing
+   entirely, so the old `__akeso_probe` route silently never existed on any
+   real Next.js app. The fixtures are plain Node servers, which is why the
+   tests never caught it; a real user's run did. */
 function probeRoutePath(root, framework) {
-  if (framework === "next-pages") return path.join(root, "pages", "api", "__akeso_probe.ts");
-  return path.join(root, "app", "api", "__akeso_probe", "route.ts");
+  if (framework === "next-pages") return path.join(root, "pages", "api", "akeso-probe.ts");
+  return path.join(root, "app", "api", "akeso-probe", "route.ts");
 }
 
 /* Relative import from the generated route file to the access module, with the
@@ -146,7 +151,7 @@ export async function installProbe(root, detection) {
   await writeFile(routeFile, content);
   return {
     routeFile,
-    urlPath: "/api/__akeso_probe",
+    urlPath: "/api/akeso-probe",
     wired: Boolean(target.chosen),
     reason: target.reason,
     target: target.chosen || null,
@@ -162,6 +167,9 @@ export async function removeProbe(routeFile) {
   await rm(routeFile);
   /* tidy the wrapper dir Next requires, only if we created it and it is now empty */
   const dir = path.dirname(routeFile);
-  if (path.basename(dir) === "__akeso_probe") await rm(dir, { recursive: false }).catch(() => {});
+  /* rmdir, not rm: it removes the folder only when it is empty, so a folder
+     holding anything of the founder's is never touched. (rm without recursive
+     throws on a directory, which silently left an empty folder in their repo.) */
+  if (["akeso-probe", "__akeso_probe"].includes(path.basename(dir))) await rmdir(dir).catch(() => {});
   return { removed: true };
 }

package/src/report.mjs

@@ -21,7 +21,12 @@ const GRADE_COPY = {
 };
 
 export function renderReport({ detection, lifecycle, generatedAt = new Date() }) {
-  const grade = lifecycle?.grade ?? { letter: "?", reason: "The lifecycle test did not run." };
+  /* Static-only is a normal, successful outcome, not a broken run. Saying "the
+     run had problems" over a clean code read was the first thing a real user
+     hit, and it also let the page claim scenarios were acted out when nothing
+     had executed. Nothing on this page may describe work that did not happen. */
+  const staticOnly = !lifecycle;
+  const grade = lifecycle?.grade ?? null;
   const handler = detection.webhookHandlers?.[0] || null;
 
   const staticFindings = [];
@@ -36,6 +41,12 @@ export function renderReport({ detection, lifecycle, generatedAt = new Date() })
   const clientGate = (detection.accessDecisionSites || []).find((site) => site.clientSideOnly);
   if (clientGate) staticFindings.push({ tone: "warn", text: `Paid access appears to be checked in the browser (${clientGate.file}), a gate anyone can step around with devtools.` });
 
+  const edgeFunction = handler?.file?.startsWith("supabase/functions/");
+  const staticHeadline = !handler ? "No Stripe webhook handler was found."
+    : !handler.verifiesSignature ? "Your webhook does not verify Stripe's signature."
+    : handler.missingEvents?.length ? `Your webhook ignores ${handler.missingEvents.length} of the 7 billing events.`
+    : "Your billing code reads clean.";
+
   const scenarioRows = (lifecycle?.results || []).map((result) => {
     const mark = result.outcome === "pass" ? "✓"
       : result.outcome === "fail" ? "✗"
@@ -56,8 +67,12 @@ export function renderReport({ detection, lifecycle, generatedAt = new Date() })
   ).join("\n");
 
   const limits = [
-    "Only the billing lifecycle was tested. Not login, checkout UI, or anything else.",
-    "Events were delivered locally with your app's own webhook secret. If your handler re-fetches objects from Stripe's API, run the sandbox mode with your Stripe test key for full fidelity.",
+    staticOnly
+      ? "Nothing was executed. This is a read of your code, so it cannot tell you what your app really does when a customer cancels."
+      : "Only the billing lifecycle was tested. Not login, checkout UI, or anything else.",
+    staticOnly
+      ? null
+      : "Events were delivered locally with your app's own webhook secret. If your handler re-fetches objects from Stripe's API, run the sandbox mode with your Stripe test key for full fidelity.",
     detection.capabilities?.blockers?.length ? `Not possible on this project yet: ${detection.capabilities.blockers.join(" ")}` : null,
   ].filter(Boolean).map((limit) => `<li>${escapeHtml(limit)}</li>`).join("\n");
 
@@ -95,13 +110,18 @@ export function renderReport({ detection, lifecycle, generatedAt = new Date() })
   .cta h3 { margin:0 0 6px; font-size:17px; } .cta p { margin:0 0 14px; color:var(--ink2); font-size:14.5px; }
   .cta a { display:inline-block; background:var(--ink); color:var(--bg); text-decoration:none; border-radius:7px; padding:10px 18px; font-size:15px; font-weight:500; }
   footer { margin-top:44px; font-size:12.5px; color:var(--ink3); }
+  pre.cmd { background:var(--line); border-radius:8px; padding:13px 15px; overflow-x:auto;
+    font:13.5px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace; margin:0; }
+  code.inline { font:13px ui-monospace,SFMono-Regular,Menlo,monospace; }
 </style></head><body><div class="shell">
   <div class="local">This report is a file on your computer. Nothing was sent anywhere.</div>
   <div class="gradeCard">
-    <div class="gradeLetter g-${escapeHtml(grade.letter)}">${escapeHtml(grade.letter)}</div>
+    ${staticOnly ? "" : `<div class="gradeLetter g-${escapeHtml(grade.letter)}">${escapeHtml(grade.letter)}</div>`}
     <div>
-      <h1>${escapeHtml(GRADE_COPY[grade.letter] || grade.reason)}</h1>
-      <p>${escapeHtml(grade.letter === "F" ? "This leaks money every day until it is fixed." : grade.reason)}</p>
+      <h1>${escapeHtml(staticOnly ? staticHeadline : (GRADE_COPY[grade.letter] || grade.reason))}</h1>
+      <p>${escapeHtml(staticOnly
+        ? "This is a read of your code. The live test, where a pretend customer pays and cancels, has not run yet."
+        : grade.letter === "F" ? "This leaks money every day until it is fixed." : grade.reason)}</p>
       <div class="app">${escapeHtml([
         detection.framework?.packageName || detection.root,
         { "next-app-router": "a Next.js app", "next-pages": "a Next.js app", express: "an Express app", "supabase-edge": "a Supabase Edge app", "node-other": "a Node app" }[detection.framework?.framework] || null,
@@ -111,12 +131,17 @@ export function renderReport({ detection, lifecycle, generatedAt = new Date() })
     </div>
   </div>
 
-  <h2>What we tested</h2>
+  ${staticOnly ? `<h2>The live test has not run yet</h2>
+  <p class="intro">Reading code can only tell you what your app is supposed to do. To see what it actually does when a customer cancels, Akeso needs to run against your app while it is running.</p>
+  ${edgeFunction
+    ? `<p class="intro">Your webhook is a Supabase Edge Function. The live test does not support that shape yet, so this code read is everything Akeso can prove about this project today.</p>`
+    : `<p class="intro">Start your app the way you normally do (often <code class="inline">npm run dev</code>), then run this in the same folder:</p>
+  <pre class="cmd">npx akeso-check --lifecycle-url http://localhost:3000</pre>`}` : `<h2>What we tested</h2>
   <p class="intro">Akeso acted out ten billing situations against your app: paying, canceling, a failing card, a refund. After each one it asked your app the same question: does this customer still have paid access?</p>
-  <div class="rows">${scenarioRows || '<div class="row mute"><span class="mark">?</span><span class="name">The lifecycle test did not run on this project.</span></div>'}</div>
+  <div class="rows">${scenarioRows}</div>`}
 
   <h2>What your code shows</h2>
-  <p class="intro">Read from your webhook handler and access checks, before anything ran.</p>
+  <p class="intro">Read from your webhook handler and access checks. Nothing was executed to produce this.</p>
   <div class="rows">${findingRows}</div>
 
   <h2>What this did not check</h2>

package/tests/probe.test.mjs

@@ -82,3 +82,40 @@ test("removal refuses a file that lost the Akeso marker", async () => {
   const { rm } = await import("node:fs/promises");
   await rm(path.dirname(file), { recursive: true });
 });
+
+/* Next.js treats any folder starting with "_" as a private folder and excludes
+   it from routing, so the probe's original `__akeso_probe` path silently never
+   existed on a real Next.js app. Proven against a live `next dev`: the
+   underscore path 404s, the hyphen path returns the entitlement. The fixtures
+   are plain Node servers, which is why only a real user's run caught it. */
+test("no probe path segment may start with an underscore", async () => {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const os = await import("node:os");
+  for (const framework of ["next-app-router", "next-pages", "node-other"]) {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akeso-probe-path-"));
+    try {
+      const installed = await installProbe(root, { framework: { framework }, accessDecisionSites: [] });
+      const segments = path.relative(root, installed.routeFile).split(path.sep);
+      for (const segment of segments) {
+        assert.ok(!segment.startsWith("_"), `${framework}: "${segment}" would be invisible to Next.js routing`);
+      }
+      assert.ok(!installed.urlPath.split("/").some((s) => s.startsWith("_")), `${framework}: url path must not be private`);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+});
+
+test("removal leaves nothing behind, not even the folder", async () => {
+  const { mkdtemp, rm, stat } = await import("node:fs/promises");
+  const os = await import("node:os");
+  const root = await mkdtemp(path.join(os.tmpdir(), "akeso-probe-clean-"));
+  try {
+    const installed = await installProbe(root, { framework: { framework: "next-app-router" }, accessDecisionSites: [] });
+    await removeProbe(installed.routeFile);
+    const dir = path.dirname(installed.routeFile);
+    await assert.rejects(() => stat(dir), "the probe folder must be gone, not left empty in their repo");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/tests/report.test.mjs

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { renderReport } from "../src/report.mjs";
+
+/* The report may never describe work that did not happen. A real user ran the
+   default static pass and was told "the run itself had problems" over a clean
+   code read, on a page claiming Akeso had acted out ten billing situations.
+   Nothing had executed. These tests exist so that cannot come back. */
+
+const detection = {
+  root: "/tmp/app",
+  framework: { packageName: "watch-this", framework: "next-app-router" },
+  database: { kind: "supabase" },
+  stripe: { secretKey: { mode: "TEST", lastFour: "1234" } },
+  webhookHandlers: [{ file: "app/api/stripe/webhook/route.ts", verifiesSignature: true, rawBodySeen: true, handledEvents: ["checkout.session.completed"], missingEvents: [] }],
+  accessDecisionSites: [],
+  capabilities: { blockers: [] },
+};
+
+test("a static-only run never claims the lifecycle was acted out", () => {
+  const html = renderReport({ detection, lifecycle: null });
+  assert.ok(!html.includes("acted out ten"), "must not claim ten situations were run");
+  assert.ok(!html.includes("run itself had problems"), "a clean code read is not a broken run");
+  assert.ok(html.includes("has not run yet"), "must say the live test has not run");
+  assert.ok(html.includes("--lifecycle-url"), "must show how to run the real test");
+});
+
+test("a static-only run leads with what the code actually showed", () => {
+  const clean = renderReport({ detection, lifecycle: null });
+  assert.match(clean, /<h1>Your billing code reads clean\./);
+
+  const broken = renderReport({
+    detection: { ...detection, webhookHandlers: [{ ...detection.webhookHandlers[0], missingEvents: ["invoice.paid", "customer.subscription.deleted"] }] },
+    lifecycle: null,
+  });
+  assert.match(broken, /<h1>Your webhook ignores 2 of the 7 billing events\./);
+});
+
+test("a graded run still shows its grade and scenarios", () => {
+  const html = renderReport({
+    detection,
+    lifecycle: {
+      scenarioCount: 1,
+      grade: { letter: "F", reason: "Customers who cancel keep their paid access." },
+      results: [{ id: "cancel", name: "Customer cancels", expected: false, observed: true, outcome: "fail", critical: true }],
+    },
+  });
+  assert.ok(html.includes(">F<"), "grade letter shown");
+  assert.ok(html.includes("acted out ten"), "the real run may describe itself");
+  assert.ok(html.includes("Customer cancels"), "scenario rows shown");
+});