run402 2.22.0 → 2.24.0

package/lib/init-astro.mjs

@@ -21,14 +21,19 @@ import { fail } from "./sdk-errors.mjs";
 const HELP = `run402 init astro — Scaffold a deployable Astro project
 
 Usage:
-  run402 init astro [<dir>] [--force] [--json]
+  run402 init astro [<dir>] [--force]
 
 Arguments:
   <dir>        Target directory (default: current directory)
 
 Options:
   --force      Overwrite a non-empty directory
-  --json       Emit a structured JSON summary on stdout
+
+Output:
+  Stdout is a JSON summary { dir, files_created, created, next_steps }.
+  Progress lines ("Scaffolded ...", "Files created:", "Next steps:") go to
+  stderr so a human re-running interactively sees what's happening while
+  a script piping stdout to jq stays clean.
 
 The scaffolded project includes:
   - package.json (with 'dev' / 'deploy' scripts)
@@ -53,7 +58,6 @@ export async function runInitAstro(args = []) {
     return;
   }
   const force = args.includes("--force");
-  const json = args.includes("--json");
   const positionals = args.filter((a) => !a.startsWith("--"));
   const targetDir = resolve(positionals[0] ?? ".");
 
@@ -155,7 +159,7 @@ import Layout from "../layouts/Layout.astro";
 // SSR time. The first request renders + caches; subsequent requests
 // HIT the cache. When an admin edits the row, call cache.invalidate()
 // from your save handler for sub-second freshness.
-import { db, getUser, cache } from "@run402/functions";
+import { db } from "@run402/functions";
 import Layout from "../layouts/Layout.astro";
 
 const { slug } = Astro.params;
@@ -215,11 +219,10 @@ const { title, ogImage, canonical } = Astro.props;
 //   2. DB update.
 //   3. cache.invalidate() so the public URL re-renders fresh on next visit.
 import type { APIRoute } from "astro";
-import { db, getUser, cache } from "@run402/functions";
+import { db, auth, cache } from "@run402/functions";
 
 export const POST: APIRoute = async ({ request }) => {
-  const user = await getUser();
-  if (!user) return new Response("Unauthorized", { status: 401 });
+  const user = await auth.requireUser();
 
   const body = (await request.json()) as { slug: string; title: string; html: string };
   if (!body?.slug) return new Response("Missing slug", { status: 400 });
@@ -236,6 +239,96 @@ export const POST: APIRoute = async ({ request }) => {
     headers: { "content-type": "application/json" },
   });
 };
+`,
+    },
+    {
+      path: "AGENTS.md",
+      content: `# AGENTS.md
+
+This file documents the brutally-small Run402 surface this Astro project
+uses. Coding agents: read this first. The platform is intentionally small —
+there are no other auth helpers, no other client surfaces, and no other
+hidden APIs.
+
+## The auth surface
+
+\`auth\` is the entire user-auth surface. Import from \`@run402/functions\`:
+
+\`\`\`ts
+import { auth } from "@run402/functions";
+
+// In SSR pages and API routes:
+const user = await auth.user();             // Actor | null
+const user = await auth.requireUser();      // Actor; throws R402_AUTH_REQUIRED
+const { user, role } = await auth.requireRole("admin");
+const { user, membership } = await auth.requireMembership("member");
+await auth.requireFresh({ maxAge: "10m", amr: ["passkey"] });
+
+// CSRF for hosted forms (server-side, in <form> rendering):
+const field = auth.csrfField();
+// → <input type="hidden" name="_csrf" value="..." />
+
+// Cross-origin-safe fetch (auto-forwards actor context to same-origin):
+const res = await auth.fetch("/api/internal");  // relative URLs only
+\`\`\`
+
+## The four Never rules
+
+1. **Never \`try\`/\`catch\` auth errors.** Let them bubble. The platform turns
+   \`R402_AUTH_REQUIRED\` into a 303 to \`/auth/sign-in?return_to=…\` and
+   \`R402_AUTH_INSUFFICIENT_ROLE\` into 403 with a fix-it response. Catching
+   them creates silent-null bugs.
+
+2. **Never \`.eq("user_id", user.id)\`.** \`db()\` propagates the actor to
+   PostgREST so RLS enforces ownership server-side. The redundant filter is
+   a code smell that \`run402 doctor\` flags as
+   \`R402_AUTH_REDUNDANT_USER_FILTER\`.
+
+3. **Never set client-supplied actor headers.** \`x-run402-actor-*\`,
+   \`run402.actor.*\`, \`x-r402-actor-*\` are platform-owned channel headers.
+   The gateway strips inbound spoofing attempts and emits
+   \`R402_AUTH_ACTOR_HEADER_SPOOF\` in strict mode.
+
+4. **Never mint a session from a raw \`userId\`.** Use
+   \`auth.sessions.createResponseFromIdentity({ provider, subject, proof, amr })\`
+   with a verified identity proof. No \`createSessionForUserId(uuid)\` API exists.
+
+## Hosted UI components
+
+For sign-in, sign-up, and sign-out chrome, use the platform's
+\`@run402/astro\` components — they emit forms posting to platform hosted
+routes (\`/auth/v1/sign-in\` etc.) with the CSRF token already wired:
+
+\`\`\`astro
+---
+import { SignIn, SignUp, UserButton, SignedIn, SignedOut } from "@run402/astro";
+---
+
+<SignedIn>
+  <UserButton />
+</SignedIn>
+<SignedOut>
+  <SignIn returnTo="/dashboard" />
+</SignedOut>
+\`\`\`
+
+Do NOT roll your own sign-in form. The hosted routes handle CSRF, returnTo
+validation, OAuth provider bridges, and passkey ceremonies.
+
+## Rendering-mode quick map
+
+\`auth.*\` calls run at request time, so the page must be SSR or a
+server-island. Calling \`auth.user()\` from a prerendered page throws
+\`R402_AUTH_PRERENDERED\`.
+
+| Mode                          | When                                | Auth-aware              |
+| ----------------------------- | ----------------------------------- | ----------------------- |
+| SSR (default)                 | Personalized pages                  | \`auth.user()\` works   |
+| Prerendered                   | Marketing pages, never sees actor   | \`auth.*\` throws       |
+| Server island                 | Prerendered page + personalized slot| \`auth.*\` in the island|
+| Client hydrate                | Visibility-only, no SSR pass        | Component hits session  |
+
+For error-code reference: https://run402.com/errors/#R402_AUTH_REQUIRED
 `,
     },
   ];
@@ -246,32 +339,31 @@ export const POST: APIRoute = async ({ request }) => {
     writeFileSync(fullPath, file.content, "utf-8");
   }
 
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          dir: targetDir,
-          files_created: files.map((f) => f.path),
-          created: true,
-          next_steps: [
-            `cd ${positionals[0] ?? "."}`,
-            "npm install",
-            "run402 deploy",
-          ],
-        },
-        null,
-        2,
-      ),
-    );
-  } else {
-    console.log(`Scaffolded Astro project at ${targetDir}`);
-    console.log("");
-    console.log("Files created:");
-    for (const f of files) console.log(`  - ${f.path}`);
-    console.log("");
-    console.log("Next steps:");
-    if (positionals[0]) console.log(`  cd ${positionals[0]}`);
-    console.log("  npm install");
-    console.log("  run402 deploy");
-  }
+  // Human-readable progress goes to stderr; stdout stays JSON-clean.
+  console.error(`Scaffolded Astro project at ${targetDir}`);
+  console.error("");
+  console.error("Files created:");
+  for (const f of files) console.error(`  - ${f.path}`);
+  console.error("");
+  console.error("Next steps:");
+  if (positionals[0]) console.error(`  cd ${positionals[0]}`);
+  console.error("  npm install");
+  console.error("  run402 deploy");
+
+  console.log(
+    JSON.stringify(
+      {
+        dir: targetDir,
+        files_created: files.map((f) => f.path),
+        created: true,
+        next_steps: [
+          `cd ${positionals[0] ?? "."}`,
+          "npm install",
+          "run402 deploy",
+        ],
+      },
+      null,
+      2,
+    ),
+  );
 }

package/lib/init.mjs

@@ -18,14 +18,17 @@ Usage:
                              Required when an allowance already exists on
                              the other rail; protects scripted re-runs from
                              silently flipping billing networks.
-  run402 init --json         Same as init, but emit a JSON summary on stdout
-                             (human lines go to stderr — for agent automation)
 
 Options:
   --switch-rail   Confirm switching the persisted payment rail. Re-running
                   init with the SAME rail as the existing allowance is always
                   idempotent and does not need this flag.
-  --json          Emit a structured JSON summary on stdout.
+
+Output:
+  Stdout is a JSON summary { config_dir, allowance, rail, network, balance,
+  tier, projects_saved, next_step }. Progress lines (Config / Allowance /
+  Balance / Tier / Next) go to stderr so a human re-running interactively
+  sees what's happening while a script piping stdout to jq stays clean.
 
 Steps (idempotent when re-run with the same rail; pass --switch-rail to change rails):
   1. Creates config directory (~/.config/run402)
@@ -61,7 +64,6 @@ export async function run(args = []) {
 
   if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
 
-  const jsonMode = args.includes("--json");
   const isMpp = args[0] === "mpp";
   const requestedRail = isMpp ? "mpp" : "x402";
   const switchRailConfirmed = args.includes("--switch-rail");
@@ -75,9 +77,9 @@ export async function run(args = []) {
     });
   }
 
-  // In --json mode, human-readable lines go to stderr so stdout stays clean for
-  // agents. We also collect structured data for the final JSON emit.
-  const write = jsonMode ? (s) => console.error(s) : (s) => console.log(s);
+  // Human-readable progress lines go to stderr so stdout stays JSON-clean for
+  // agents. Final structured summary emits to stdout at the end.
+  const write = (s) => console.error(s);
   const line = (label, value) => write(`  ${label.padEnd(10)} ${value}`);
   const summary = {
     config_dir: CONFIG_DIR,
@@ -265,7 +267,5 @@ export async function run(args = []) {
   write("");
   summary.next_step = nextStep;
 
-  if (jsonMode) {
-    console.log(JSON.stringify(summary, null, 2));
-  }
+  console.log(JSON.stringify(summary, null, 2));
 }

package/lib/logs.mjs

@@ -21,7 +21,7 @@ import { reportSdkError, fail } from "./sdk-errors.mjs";
 const HELP = `run402 logs — Fetch function logs by request id
 
 Usage:
-  run402 logs --request-id <req_id> [--function <name>] [--project <id>] [--json] [--tail <n>]
+  run402 logs --request-id <req_id> [--function <name>] [--project <id>] [--tail <n>]
 
 Required:
   --request-id <req_id>   The req_... id (from x-run402-request-id header)
@@ -30,12 +30,14 @@ Optional:
   --function <name>       Limit to one function (default: scan all functions in the project)
   --project <id>          Project id (default: \$RUN402_PROJECT_ID)
   --tail <n>              Max entries per function (default 100)
-  --json                  Machine-readable output
+
+Output:
+  Stdout is JSON { ok, request_id, project_id, scanned, entries, errors? }.
 
 Examples:
   run402 logs --request-id req_abc123
   run402 logs --request-id req_abc123 --function ssr
-  run402 logs --request-id req_abc123 --project prj_xyz --json
+  run402 logs --request-id req_abc123 --project prj_xyz
 
 Tip: the request id appears in:
   - The 'x-run402-request-id' response header on every SSR response
@@ -50,7 +52,6 @@ export async function run(sub, args = []) {
     return;
   }
 
-  const json = all.includes("--json");
   const requestId = pickFlagValue(all, "--request-id");
   const fnName = pickFlagValue(all, "--function");
   const projectIdArg = pickFlagValue(all, "--project");
@@ -98,18 +99,19 @@ export async function run(sub, args = []) {
       const list = await sdk.functions.list(projectId);
       fnNames = (list?.functions ?? []).map((f) => f.name);
       if (fnNames.length === 0) {
-        if (json) console.log(JSON.stringify({ ok: true, entries: [], scanned: [] }));
-        else console.log("No functions in project " + projectId);
+        console.log(JSON.stringify({ ok: true, request_id: requestId, project_id: projectId, entries: [], scanned: [] }, null, 2));
         return;
       }
     }
 
-    // Query each function in parallel; aggregate entries.
+    // Query each function in parallel; aggregate entries. SDK returns
+    // FunctionLogsResult = { logs: FunctionLogEntry[] }; unwrap to the array
+    // so the aggregated JSON has a flat entries[] field.
     const results = await Promise.allSettled(
       fnNames.map((name) =>
         sdk.functions
           .logs(projectId, name, { requestId, tail })
-          .then((entries) => ({ name, entries: entries ?? [] })),
+          .then((result) => ({ name, entries: result?.logs ?? [] })),
       ),
     );
 
@@ -127,35 +129,28 @@ export async function run(sub, args = []) {
       }
     }
 
-    // Sort by timestamp ascending.
-    allEntries.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
-
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            ok: errors.length === 0,
-            request_id: requestId,
-            project_id: projectId,
-            scanned,
-            entries: allEntries,
-            ...(errors.length > 0 && { errors }),
-          },
-          null,
-          2,
-        ),
-      );
-    } else {
-      if (allEntries.length === 0) {
-        console.log(`No log entries found for ${requestId} across ${scanned.length} function(s).`);
-      } else {
-        for (const e of allEntries) {
-          const t = e.ts ? new Date(e.ts).toISOString() : "";
-          console.log(`[${t}] [${e.function}] ${e.message ?? ""}`);
-        }
-        console.log(`\n${allEntries.length} entries across ${scanned.length} function(s) for ${requestId}.`);
-      }
-    }
+    // Sort by timestamp ascending. FunctionLogEntry.timestamp is an ISO 8601
+    // string; convert to epoch ms for comparison.
+    allEntries.sort((a, b) => {
+      const ta = a.timestamp ? Date.parse(a.timestamp) : 0;
+      const tb = b.timestamp ? Date.parse(b.timestamp) : 0;
+      return ta - tb;
+    });
+
+    console.log(
+      JSON.stringify(
+        {
+          ok: errors.length === 0,
+          request_id: requestId,
+          project_id: projectId,
+          scanned,
+          entries: allEntries,
+          ...(errors.length > 0 && { errors }),
+        },
+        null,
+        2,
+      ),
+    );
   } catch (err) {
     reportSdkError(err);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {