@kedge/cli 0.0.0-stage → 0.10.0

package/src/check.ts

@@ -0,0 +1,45 @@
+// `kedge check` (docs/proposals/p0.8-cli-agent-kit.md §4.4): the guard an agent
+// runs before it stops, in order, stopping at the first failure. `--fast`
+// (the Stop hook's) needs no Cloudflare and finishes in seconds; the full one
+// adds the store's tests in workerd, with the invariant suite after each.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { childStdio } from "./output";
+
+export interface CheckInput {
+  cwd: string;
+  fast: boolean;
+  generate: (cwd: string) => Promise<number>;
+  doctor: (cwd: string) => Promise<number>;
+  /** Runs a tool from the store's node_modules/.bin; tests replace it. */
+  run?: (bin: string, args: string[], cwd: string) => number;
+}
+
+const runBin = (bin: string, args: string[], cwd: string): number => {
+  const path = join(cwd, "node_modules", ".bin", bin);
+  if (!existsSync(path)) {
+    console.error(`${bin} isn't installed in this store: run pnpm install`);
+    return 1;
+  }
+  return spawnSync(path, args, { cwd, stdio: childStdio() }).status ?? 1;
+};
+
+export async function check(input: CheckInput): Promise<number> {
+  const run = input.run ?? runBin;
+  const steps: [string, () => Promise<number> | number][] = [
+    ["typecheck", () => run("tsc", ["--noEmit", "-p", "."], input.cwd)],
+    ["kedge generate --check", () => input.generate(input.cwd)],
+    ["kedge doctor", () => input.doctor(input.cwd)],
+    ...(input.fast ? [] : ([["tests", () => run("vitest", ["run"], input.cwd)]] as [string, () => number][])),
+  ];
+  for (const [name, step] of steps) {
+    const code = await step();
+    if (code !== 0) {
+      console.error(`\nkedge check: ${name} failed. Fix it and run kedge check${input.fast ? " --fast" : ""} again.`);
+      return code;
+    }
+  }
+  console.log(`kedge check${input.fast ? " --fast" : ""} passed`);
+  return 0;
+}

package/src/cli-session.ts

@@ -0,0 +1,57 @@
+// A CLI session for one command (docs/proposals/p0.10-agent-path.md §6.2):
+// whoever holds the store's Cloudflare credentials writes the row, one audited
+// `system:cli` batch, to the target's own database and no other, and the
+// command sends the token to that target alone. The token lives in this
+// process's memory only: never printed, logged or saved. The row is deleted
+// when the command ends; one a crash leaves expires within ten minutes.
+import { type CliBatch, cliSessionEndSql, cliSessionSql } from "@kedge/db";
+import { type Cloudflare, UnknownOutcome } from "./cf";
+import { DeployRefused } from "./deploy";
+import type { StoreTarget } from "./target";
+
+/** What an older Worker's or database's refusal of a CLI session means for the person running it. */
+export const OLDER_KEDGE = "this store runs a Kedge older than this CLI, without CLI sessions: deploy first";
+
+export interface SessionDeps {
+  cloudflare: () => Promise<Cloudflare>;
+  /** `wrangler d1 execute --local` in the store's directory: `kedge dev`'s database. */
+  executeLocal: (b: CliBatch) => number;
+  now?: () => number;
+}
+
+async function write(target: StoreTarget, b: CliBatch, d: SessionDeps): Promise<void> {
+  if (target.kind === "local") {
+    if (d.executeLocal(b) !== 0) throw new DeployRefused("writing the CLI session to kedge dev's database failed");
+    return;
+  }
+  const cf = await d.cloudflare();
+  try {
+    await cf.executeD1File({ database: target.database.name, databaseId: target.database.id as string, sql: b.sql });
+  } catch (e) {
+    // A database from before P0.10 has no table to hold it.
+    if (e instanceof UnknownOutcome && /no such table: cli_session/.test(e.message))
+      throw new DeployRefused(OLDER_KEDGE);
+    throw e;
+  }
+}
+
+/** Runs `work` with a session holding `grants` on `target`, ending it after, whatever happened. */
+export async function withCliSession<T>(
+  target: StoreTarget,
+  grants: readonly string[],
+  d: SessionDeps,
+  work: (auth: Record<string, string>) => Promise<T>,
+): Promise<T> {
+  const now = d.now ?? Date.now;
+  const s = await cliSessionSql(grants, now());
+  await write(target, s, d);
+  try {
+    return await work({ authorization: `Bearer ${s.token}` });
+  } finally {
+    // Ending is housekeeping: a row left behind is useless without the token, and expires anyway.
+    await write(target, cliSessionEndSql(s.id, now()), d).catch(() => undefined);
+  }
+}
+
+/** Whether a request's credential was a CLI session, so a 401 can be read as an older Worker. */
+export const isCliSession = (auth: Record<string, string>) => auth.authorization?.startsWith("Bearer kcs_") === true;

package/src/code-lint.ts

@@ -0,0 +1,339 @@
+// The code lint (docs/proposals/p0.8-cli-agent-kit.md §4.5, K11, K12): what SQL
+// lint and types can't see. An effect sent around the journal is repeated
+// after a retry or a restore and is invisible to a preview's sinks; a
+// provider's reply or a customer's data in an error or a log line lands where
+// erasure can't reach (customer-erasure.md §3). It parses every local module
+// reachable from kedge.config.ts and the Worker entry, because a hook can be
+// written inline in the config and a helper can live outside src/.
+//
+// It's a lint, so it can be fooled (a `fetch` through an alias passes); a
+// preview without production credentials is the backstop. An exception is
+// `// kedge-allow <rule>: <why>` on the line or the line above, which doctor
+// lists, so an exception is visible rather than impossible.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { parse } from "@babel/parser";
+
+export const CODE_RULES = [
+  "no-direct-network",
+  "no-raw-provider-error",
+  "no-dynamic-throw",
+  "no-console",
+  "no-classified-log",
+] as const;
+export type CodeRule = (typeof CODE_RULES)[number];
+
+export interface CodeIssue {
+  file: string;
+  line: number;
+  rule: CodeRule;
+  message: string;
+  /** The `kedge-allow` reason, when the line carries one: listed, not failed. */
+  allowed?: string;
+}
+
+/** Packages that reach a provider over the network: importing one outside a port is a direct call. */
+export const PROVIDER_SDKS: readonly (string | RegExp)[] = [
+  "stripe",
+  "twilio",
+  "nodemailer",
+  "resend",
+  "postmark",
+  "mailgun.js",
+  "razorpay",
+  "braintree",
+  "square",
+  "shippo",
+  "axios",
+  "node-fetch",
+  "undici",
+  "got",
+  "ky",
+  "superagent",
+  "firebase-admin",
+  /^@sendgrid\//,
+  /^@aws-sdk\//,
+  /^@google-cloud\//,
+  /^@paypal\//,
+  /^@easypost\//,
+  /^@mailchimp\//,
+];
+
+/** A port's methods: the only places an external call belongs (K12). */
+const PORT_METHODS = new Set(["call", "observe", "credentialMode"]);
+const NETWORK_CONSTRUCTORS = new Set(["WebSocket", "XMLHttpRequest", "EventSource"]);
+
+// biome-ignore lint/suspicious/noExplicitAny: Babel's AST, walked generically
+type Node = any;
+
+const isSdk = (source: string) => PROVIDER_SDKS.some((s) => (typeof s === "string" ? source === s : s.test(source)));
+const keyName = (n: Node): string | null =>
+  n?.type === "Identifier" ? n.name : n?.type === "StringLiteral" ? n.value : null;
+const isFunction = (n: Node) =>
+  n?.type === "FunctionExpression" || n?.type === "ArrowFunctionExpression" || n?.type === "ObjectMethod";
+/** A plain string: a literal, or a template with nothing interpolated. */
+const isLiteralText = (n: Node) =>
+  n === undefined || n.type === "StringLiteral" || (n.type === "TemplateLiteral" && n.expressions.length === 0);
+
+function calleeName(n: Node): string | null {
+  if (n?.type === "Identifier") return n.name;
+  if (n?.type === "MemberExpression" && !n.computed) return keyName(n.property);
+  return null;
+}
+
+/** Whether `name` appears as an identifier anywhere in `n`. */
+function mentions(n: Node, name: string): boolean {
+  let found = false;
+  walk(n, [], (m) => {
+    if (m.type === "Identifier" && m.name === name) found = true;
+  });
+  return found;
+}
+
+function walk(n: Node, ancestors: Node[], visit: (n: Node, ancestors: Node[]) => void): void {
+  if (!n || typeof n.type !== "string") return;
+  visit(n, ancestors);
+  ancestors.push(n);
+  for (const [k, v] of Object.entries(n)) {
+    if (k === "loc" || k === "leadingComments" || k === "trailingComments" || k === "innerComments" || k === "extra")
+      continue;
+    if (Array.isArray(v)) for (const c of v) walk(c, ancestors, visit);
+    else if (v && typeof v === "object") walk(v, ancestors, visit);
+  }
+  ancestors.pop();
+}
+
+/** The port method a node is lexically inside, if any. */
+function inPortMethod(ancestors: readonly Node[]): boolean {
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const a = ancestors[i];
+    if (!isFunction(a)) continue;
+    if (a.type === "ObjectMethod" && PORT_METHODS.has(keyName(a.key) ?? "")) return true;
+    const parent = ancestors[i - 1];
+    if (parent?.type === "ObjectProperty" && parent.value === a && PORT_METHODS.has(keyName(parent.key) ?? ""))
+      return true;
+  }
+  return false;
+}
+
+/**
+ * `// kedge-allow <rule>: <why>`: at the end of a line, for that line; on a
+ * line of its own, for the whole statement below its run of comments, since a
+ * formatter moves a loop body's comment above the loop.
+ */
+function allowances(
+  text: string,
+  statementEnd: ReadonlyMap<number, number>,
+): { from: number; to: number; rule: string; reason: string }[] {
+  const out: { from: number; to: number; rule: string; reason: string }[] = [];
+  const lines = text.split("\n");
+  const commentOnly = (l: string | undefined) => l !== undefined && /^\s*(\/\/|\/\*|\*)/.test(l);
+  lines.forEach((l, i) => {
+    for (const m of l.matchAll(/kedge-allow\s+([a-z-]+):\s*(\S[^*]*?)\s*(?:\*\/|$)/g)) {
+      let at = i;
+      if (commentOnly(l)) while (commentOnly(lines[at])) at++;
+      const from = at + 1;
+      const to = commentOnly(l) ? (statementEnd.get(from) ?? from) : from;
+      out.push({ from, to, rule: m[1] as string, reason: m[2] as string });
+    }
+  });
+  return out;
+}
+
+export function lintSource(file: string, text: string): CodeIssue[] {
+  const ast = parse(text, {
+    sourceType: "module",
+    plugins: extname(file) === ".tsx" ? ["typescript", "jsx"] : ["typescript"],
+    errorRecovery: false,
+  });
+  const issues: CodeIssue[] = [];
+  const add = (n: Node, rule: CodeRule, message: string) =>
+    issues.push({ file, line: n.loc?.start.line ?? 0, rule, message });
+  const socketConnects = new Set<string>();
+
+  walk(ast.program, [], (n, ancestors) => {
+    switch (n.type) {
+      case "ImportDeclaration": {
+        const source = n.source.value as string;
+        if (source === "cloudflare:sockets")
+          for (const s of n.specifiers)
+            if (s.imported && keyName(s.imported) === "connect") socketConnects.add(s.local.name);
+        if (isSdk(source))
+          add(
+            n,
+            "no-direct-network",
+            `imports "${source}", a provider's SDK: call it only inside a port's call, observe or credentialMode`,
+          );
+        break;
+      }
+      case "CallExpression": {
+        const c = n.callee;
+        const direct =
+          (c.type === "Identifier" && (c.name === "fetch" || socketConnects.has(c.name))) ||
+          (c.type === "MemberExpression" &&
+            !c.computed &&
+            keyName(c.property) === "fetch" &&
+            c.object.type === "Identifier" &&
+            ["globalThis", "self", "window"].includes(c.object.name));
+        if (direct && !inPortMethod(ancestors))
+          add(
+            n,
+            "no-direct-network",
+            "calls the network outside a port: an effect sent here bypasses the journal and repeats after a retry or a restore",
+          );
+        if (c.type === "MemberExpression" && c.object.type === "Identifier" && c.object.name === "console") {
+          if (!n.arguments.every(isLiteralText))
+            add(
+              n,
+              "no-console",
+              "logs something other than literal text: a log line can carry a customer's data, and erasure can't reach logs",
+            );
+          const objects = n.arguments.flatMap((a: Node) =>
+            a.type === "CallExpression" && calleeName(a.callee) === "stringify" ? a.arguments : [a],
+          );
+          if (
+            objects.some(
+              (a: Node) =>
+                a.type === "Identifier" ||
+                (a.type === "ObjectExpression" && a.properties.some((p: Node) => p.type === "SpreadElement")),
+            )
+          )
+            add(
+              n,
+              "no-classified-log",
+              "logs a whole value: name each field logged, so nothing classified rides along",
+            );
+        }
+        break;
+      }
+      case "NewExpression": {
+        if (n.callee.type === "Identifier" && NETWORK_CONSTRUCTORS.has(n.callee.name) && !inPortMethod(ancestors))
+          add(n, "no-direct-network", `opens a ${n.callee.name} outside a port`);
+        break;
+      }
+      case "ThrowStatement": {
+        const e = n.argument;
+        if (e?.type !== "NewExpression" && e?.type !== "CallExpression") break;
+        const name = calleeName(e.callee) ?? "";
+        // Two kinds don't reach a log (§4.5's build note): a config error is
+        // thrown while a config resolves at boot, from its declarations,
+        // before any request exists; and a KedgeError is the requester's own
+        // refusal, rendered into its response, while core logs and records
+        // only its code (the server's onError, the relay's failureCode).
+        // A constructor (`new X()` or `X()` for a class name), not a helper
+        // like mapD1Error(e) that returns an error it already built.
+        if (!/^(?:[A-Z]\w*)?Error$/.test(name) || /ConfigError$/.test(name) || name === "KedgeError") break;
+        const texts = [e.arguments[0]];
+        if (!texts.every(isLiteralText))
+          add(
+            n,
+            "no-dynamic-throw",
+            `throws a ${name} whose message isn't literal text: an error's message reaches logs and Workflow history, which erasure can't reach`,
+          );
+        break;
+      }
+      case "CatchClause": {
+        if (!inPortMethod(ancestors) || n.param?.type !== "Identifier") break;
+        const p = n.param.name as string;
+        walk(n.body, [], (m) => {
+          if (m.type === "ThrowStatement" && m.argument?.type === "Identifier" && m.argument.name === p)
+            add(m, "no-raw-provider-error", "rethrows a provider's error from a port: its text can name a customer");
+          if (
+            m.type === "NewExpression" &&
+            calleeName(m.callee) === "KedgeProviderError" &&
+            m.arguments.some((a: Node) => mentions(a, p))
+          )
+            add(
+              m,
+              "no-raw-provider-error",
+              "builds a KedgeProviderError from the provider's error: map it to a declared failure code instead",
+            );
+          if (
+            m.type === "CallExpression" &&
+            m.callee.type === "MemberExpression" &&
+            m.callee.object.type === "Identifier" &&
+            m.callee.object.name === "console" &&
+            m.arguments.some((a: Node) => mentions(a, p))
+          )
+            add(m, "no-raw-provider-error", "logs the provider's error from a port");
+        });
+        break;
+      }
+    }
+  });
+
+  // Where each statement starting on a line ends: the outermost one wins.
+  const statementEnd = new Map<number, number>();
+  walk(ast.program, [], (n) => {
+    if (!/(Statement|Declaration)$/.test(n.type) || !n.loc) return;
+    const { start, end } = n.loc;
+    statementEnd.set(start.line, Math.max(statementEnd.get(start.line) ?? 0, end.line));
+  });
+  const allowed = allowances(text, statementEnd);
+  return issues.map((i) => {
+    const a = allowed.find((x) => x.rule === i.rule && i.line >= x.from && i.line <= x.to);
+    return a ? { ...i, allowed: a.reason } : i;
+  });
+}
+
+const RESOLVE = ["", ".ts", ".tsx", ".mts", "/index.ts", "/index.tsx"];
+
+/** A relative import to its file, or null: packages and anything outside the store aren't the store's code. */
+export function resolveImport(from: string, spec: string, root: string): string | null {
+  if (!spec.startsWith(".")) return null;
+  const base = resolve(dirname(from), spec);
+  const candidates = [...RESOLVE.map((x) => base + x), base.replace(/\.js$/, ".ts"), base.replace(/\.mjs$/, ".mts")];
+  for (const c of candidates) {
+    if (relative(root, c).startsWith("..") || c.includes(`${"/"}node_modules/`)) continue;
+    if (existsSync(c) && statSync(c).isFile()) return c;
+  }
+  return null;
+}
+
+/** Every local module reachable from the entries by static, re-export and literal dynamic imports. */
+export function reachableModules(entries: readonly string[], root: string): string[] {
+  const seen = new Set<string>();
+  const queue = entries.filter((e) => existsSync(e));
+  while (queue.length) {
+    const file = queue.pop() as string;
+    if (seen.has(file)) continue;
+    seen.add(file);
+    let ast: Node;
+    try {
+      ast = parse(readFileSync(file, "utf8"), { sourceType: "module", plugins: ["typescript", "jsx"] });
+    } catch {
+      continue; // reported by lintSource
+    }
+    walk(ast.program, [], (n) => {
+      const spec =
+        n.type === "ImportDeclaration" || n.type === "ExportNamedDeclaration" || n.type === "ExportAllDeclaration"
+          ? n.source?.value
+          : n.type === "CallExpression" && n.callee.type === "Import" && n.arguments[0]?.type === "StringLiteral"
+            ? n.arguments[0].value
+            : n.type === "ImportExpression" && n.source?.type === "StringLiteral"
+              ? n.source.value
+              : null;
+      if (typeof spec !== "string") return;
+      const r = resolveImport(file, spec, root);
+      if (r && !seen.has(r)) queue.push(r);
+    });
+  }
+  return [...seen].sort();
+}
+
+/** Lints the store's code: the config, the Worker entry and everything local they reach. */
+export function lintStore(root: string, entries: readonly string[]): CodeIssue[] {
+  const out: CodeIssue[] = [];
+  for (const f of reachableModules(
+    entries.map((e) => join(root, e)),
+    root,
+  )) {
+    const rel = relative(root, f);
+    try {
+      out.push(...lintSource(rel, readFileSync(f, "utf8")));
+    } catch (e) {
+      out.push({ file: rel, line: 0, rule: "no-direct-network", message: `doesn't parse: ${(e as Error).message}` });
+    }
+  }
+  return out;
+}