@kedge/cli 0.0.0-stage → 0.9.0

package/src/manifest.ts

@@ -0,0 +1,163 @@
+// kedge-manifest.json (docs/proposals/p0.8-cli-agent-kit.md §2): what a release
+// shipped, by package and file, written by scripts/pack-kedge.mjs into
+// @kedge/cli. Doctor compares the store's installed packages, core migrations
+// and ejected units with it. Hashing matches the pack script's, package.json
+// included: its keys are sorted first, because pnpm pack orders the
+// dependencies it rewrites differently from one run to the next.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface Manifest {
+  version: string;
+  upgradesFrom: string | null;
+  doStateFormat: number;
+  migrations: Record<string, { sha256: string; mode: "n1" | "cutover" }>;
+  units: Record<string, { package: string; path: string; sha256: string }>;
+  packages: Record<string, Record<string, string>>;
+}
+
+const sha256 = (buf: Buffer | string) => createHash("sha256").update(buf).digest("hex");
+const sorted = (v: unknown): unknown =>
+  Array.isArray(v)
+    ? v.map(sorted)
+    : v && typeof v === "object"
+      ? Object.fromEntries(
+          Object.keys(v)
+            .sort()
+            .map((k) => [k, sorted((v as Record<string, unknown>)[k])]),
+        )
+      : v;
+
+export function fileHash(path: string, buf: Buffer): string {
+  return path === "package.json" || path.endsWith("/package.json")
+    ? sha256(JSON.stringify(sorted(JSON.parse(buf.toString("utf8")))))
+    : sha256(buf);
+}
+
+/** This CLI's own manifest, or null where there is none (the monorepo's workspace links). */
+export function ownManifest(): Manifest | null {
+  const file = join(dirname(fileURLToPath(import.meta.url)), "..", "kedge-manifest.json");
+  return existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as Manifest) : null;
+}
+
+function filesUnder(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) {
+        if (e.name !== "node_modules") walk(p);
+      } else if (e.isFile()) out.push(relative(dir, p));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+export interface InstalledDrift {
+  package: string;
+  changed: string[];
+  added: string[];
+  missing: string[];
+}
+
+/** Where Node would find `name` from `fromDir`: each ancestor's node_modules, as the resolution algorithm walks. */
+function locate(fromDir: string, name: string): string | null {
+  let d = fromDir;
+  for (;;) {
+    if (basename(d) !== "node_modules") {
+      const p = join(d, "node_modules", ...name.split("/"));
+      if (existsSync(p)) return realpathSync(p);
+    }
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+/**
+ * Every `@kedge/*` package the store loads, found as Node finds it: the
+ * store's own dependencies, then theirs. pnpm keeps a transitive package out
+ * of the store's node_modules (core, db and server sit beside runtime-cf in
+ * its virtual store), and an edit there would run just the same.
+ */
+export function installedPackages(cwd: string): Map<string, string> {
+  const found = new Map<string, string>();
+  const queue: [string, string][] = [];
+  const pj = join(cwd, "package.json");
+  const own = existsSync(pj) ? (JSON.parse(readFileSync(pj, "utf8")) as Record<string, Record<string, string>>) : {};
+  for (const name of Object.keys({ ...own.dependencies, ...own.devDependencies }))
+    if (name.startsWith("@kedge/")) queue.push([cwd, name]);
+  while (queue.length) {
+    const [from, name] = queue.pop() as [string, string];
+    if (found.has(name)) continue;
+    const dir = locate(from, name);
+    if (!dir) continue;
+    found.set(name, dir);
+    const deps = (
+      JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { dependencies?: Record<string, string> }
+    ).dependencies;
+    for (const d of Object.keys(deps ?? {})) if (d.startsWith("@kedge/")) queue.push([dir, d]);
+  }
+  return found;
+}
+
+/**
+ * Every installed copy of every `@kedge/*` package the store can load, by directory: two dependents
+ * can resolve the same name to different copies, and checking only the first would leave the one the
+ * runtime loads unchecked (codex code r13).
+ */
+export function installedCopies(cwd: string): { name: string; dir: string }[] {
+  const seen = new Map<string, string>();
+  const queue: [string, string][] = [];
+  const pj = join(cwd, "package.json");
+  const own = existsSync(pj) ? (JSON.parse(readFileSync(pj, "utf8")) as Record<string, Record<string, string>>) : {};
+  for (const name of Object.keys({ ...own.dependencies, ...own.devDependencies }))
+    if (name.startsWith("@kedge/")) queue.push([cwd, name]);
+  while (queue.length) {
+    const [from, name] = queue.pop() as [string, string];
+    const dir = locate(from, name);
+    if (!dir || seen.has(dir)) continue;
+    seen.set(dir, name);
+    const deps = (
+      JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { dependencies?: Record<string, string> }
+    ).dependencies;
+    for (const d of Object.keys(deps ?? {})) if (d.startsWith("@kedge/")) queue.push([dir, d]);
+  }
+  return [...seen].map(([dir, name]) => ({ name, dir }));
+}
+
+/** Each installed copy of each `@kedge/*` package, its files against what the release shipped. */
+export function installedDrift(cwd: string, manifest: Manifest): InstalledDrift[] {
+  const out: InstalledDrift[] = [];
+  const copies = installedCopies(cwd);
+  const count = (n: string) => copies.filter((c) => c.name === n).length;
+  for (const { name: pkg, dir } of copies) {
+    const name = count(pkg) > 1 ? `${pkg} (${relative(cwd, dir)})` : pkg;
+    const files = manifest.packages[pkg];
+    if (!files) {
+      out.push({
+        package: name,
+        changed: [],
+        added: [`(the whole package: Kedge ${manifest.version} didn't ship it)`],
+        missing: [],
+      });
+      continue;
+    }
+    const have = filesUnder(dir);
+    const d: InstalledDrift = { package: name, changed: [], added: [], missing: [] };
+    for (const f of have) {
+      const want = files[f];
+      if (want === undefined) {
+        // The CLI carries the manifest that lists every other file.
+        if (!(pkg === "@kedge/cli" && f === "kedge-manifest.json")) d.added.push(f);
+      } else if (fileHash(f, readFileSync(join(dir, f))) !== want) d.changed.push(f);
+    }
+    const haveSet = new Set(have);
+    for (const f of Object.keys(files)) if (!haveSet.has(f)) d.missing.push(f);
+    if (d.changed.length || d.added.length || d.missing.length) out.push(d);
+  }
+  return out;
+}

package/src/n1.ts

@@ -0,0 +1,217 @@
+// Which pending migrations the previous Worker survives (docs/proposals/p0.8-cli-agent-kit.md §6.2).
+// Rollback doesn't change "resources connected to your Worker", so every file
+// an ordinary deploy applies must leave the running code working: by proof
+// (core's release suites, a plugin generation's design) or by a statement
+// someone wrote. Shape alone proves little: adding a column breaks a
+// positional INSERT, and an expression index can throw on an old write.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PluginInstance } from "@kedge/core";
+import { statementTexts } from "@kedge/core";
+import { CUTOVER_MIGRATIONS } from "@kedge/db";
+import type { Lock, LockEntry } from "./compose";
+import type { Manifest } from "./manifest";
+import { schemaOf } from "./schema";
+
+export type Mode = "n1" | "cutover";
+
+export interface Classified {
+  file: string;
+  source: string;
+  mode: Mode;
+  /** Why it's N−1: proof, design, shape, or the statement's text. */
+  because: string;
+}
+
+export class NotN1 extends Error {
+  constructor(readonly problems: string[]) {
+    super(`pending migrations the running Worker may not survive:\n  ${problems.join("\n  ")}`);
+    this.name = "NotN1";
+  }
+}
+
+const strip = (s: string) =>
+  s
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+/** A name as SQLite resolves it: unquoted, and case-blind, so `local_Cache` is `local_cache` (codex code r19). */
+const unquote = (n: string) => n.replace(/^["`[]|["`\]]$/g, "").toLowerCase();
+const NAME = String.raw`(?:"[^"]+"|\x60[^\x60]+\x60|\[[^\]]+\]|[A-Za-z_][\w$]*)`;
+
+/** A plain column in an index: a name, maybe a direction or collation. No expression. */
+const plainColumn = (c: string) =>
+  new RegExp(String.raw`^${NAME}(\s+COLLATE\s+\w+)?(\s+(ASC|DESC))?$`, "i").test(c.trim());
+
+/** The object one statement creates, by kind and name, if it creates one. */
+function createdBy(t: string): string | null {
+  const m = new RegExp(
+    String.raw`^CREATE\s+(?:TEMP\s+|TEMPORARY\s+)?(?:UNIQUE\s+)?(TABLE|INDEX|TRIGGER|VIEW)\s+(?:IF\s+NOT\s+EXISTS\s+)?(${NAME})`,
+    "i",
+  ).exec(strip(t));
+  return m ? `${(m[1] as string).toUpperCase()}:${unquote(m[2] as string)}` : null;
+}
+
+/** Objects a file creates, by kind and name. */
+function created(texts: readonly string[]): Set<string> {
+  return new Set(texts.map(createdBy).filter((k): k is string => k !== null));
+}
+
+/**
+ * Judges a file's statements in the order they run. A drop may take only what an earlier
+ * statement of the same file created and that didn't exist before the file: `DROP x; CREATE x`
+ * would otherwise pass as "its own new table" and destroy a live one (codex code r2).
+ */
+function judgeFile(
+  texts: readonly string[],
+  before: ReadonlySet<string>,
+  mayDrop: (kind: string, name: string) => boolean,
+): ReturnType<typeof judge>[] {
+  const own = new Set<string>();
+  return texts.map((t) => {
+    const j = judge(t, own, mayDrop);
+    const made = createdBy(t);
+    if (made && !before.has(made)) own.add(made);
+    const dropped = /^DROP\s+(TABLE|INDEX|TRIGGER|VIEW)\s+(?:IF\s+EXISTS\s+)?(\S+)/i.exec(strip(t));
+    if (dropped) own.delete(`${(dropped[1] as string).toUpperCase()}:${unquote(dropped[2] as string)}`);
+    return j;
+  });
+}
+
+/** Every object that exists before `file` runs, by kind and name: the lock's earlier files applied in order. */
+function existingBefore(input: ClassifyInput, file: string): Set<string> {
+  const pending = new Set(input.pending.map((p) => p.file));
+  const texts: string[] = [];
+  for (const e of input.lock.entries) {
+    if (e.file === file) break;
+    texts.push(pending.has(e.file) ? input.text(e.file) : readFileSync(join(input.cwd, "migrations", e.file), "utf8"));
+  }
+  const schema = schemaOf(texts);
+  schema.db.close();
+  return new Set(
+    schema.objects.filter((o) => o.type !== "constraint").map((o) => `${o.type.toUpperCase()}:${o.name.toLowerCase()}`),
+  );
+}
+
+/** What one plugin or local statement is, for the shape rule and the drop rule. */
+function judge(
+  stmt: string,
+  own: Set<string>,
+  mayDrop: (kind: string, name: string) => boolean,
+): { ok: boolean; drop?: string; why: string } {
+  const s = strip(stmt);
+  if (/^CREATE\s+(?:TEMP\s+|TEMPORARY\s+)?TABLE\b/i.test(s)) return { ok: true, why: "CREATE TABLE" };
+  const idx = new RegExp(
+    String.raw`^CREATE\s+(UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?${NAME}\s+ON\s+${NAME}\s*\((.*)\)\s*(WHERE\b.*)?$`,
+    "i",
+  ).exec(s);
+  if (idx) {
+    if (idx[1]) return { ok: false, why: "a unique index can refuse the running Worker's inserts" };
+    if (idx[3]) return { ok: false, why: "a partial index's predicate can throw on the running Worker's writes" };
+    if (!(idx[2] as string).split(",").every(plainColumn))
+      return { ok: false, why: "an expression index can throw on the running Worker's writes" };
+    return { ok: true, why: "a plain non-unique index" };
+  }
+  const drop = new RegExp(String.raw`^DROP\s+(TABLE|INDEX|TRIGGER|VIEW)\s+(?:IF\s+EXISTS\s+)?(${NAME})`, "i").exec(s);
+  if (drop) {
+    const kind = (drop[1] as string).toUpperCase();
+    const name = unquote(drop[2] as string);
+    if (own.has(`${kind}:${name}`) || mayDrop(kind, name)) return { ok: true, why: "drops what it may" };
+    return { ok: false, drop: `${kind} ${name}`, why: "drops something that exists before this file" };
+  }
+  if (/^ALTER\s+TABLE\b.*\b(RENAME|DROP\s+COLUMN)\b/i.test(s)) {
+    const t = new RegExp(String.raw`^ALTER\s+TABLE\s+(${NAME})`, "i").exec(s);
+    const name = unquote((t?.[1] as string) ?? "");
+    if (own.has(`TABLE:${name}`)) return { ok: true, why: "renames or drops within its own new table" };
+    return { ok: false, drop: `TABLE ${name}`, why: "renames or drops part of something that exists before this file" };
+  }
+  if (/^ALTER\s+TABLE\b.*\bADD\b/i.test(s))
+    return { ok: false, why: "a new column breaks the running Worker's positional INSERT" };
+  return { ok: false, why: `"${s.slice(0, 60)}" isn't a shape the running Worker can't trip` };
+}
+
+export interface ClassifyInput {
+  cwd: string;
+  lock: Lock;
+  pending: readonly LockEntry[];
+  manifest: Manifest | null;
+  // biome-ignore lint/suspicious/noExplicitAny: each plugin brings its own options type
+  plugins: readonly PluginInstance<any>[];
+  /** Each file's text, from the staged bytes the deploy applies (§6.2). */
+  text: (file: string) => string;
+}
+
+/** Classifies each pending file, or throws NotN1 naming each one that isn't. */
+export function classify(input: ClassifyInput): Classified[] {
+  const out: Classified[] = [];
+  const problems: string[] = [];
+  const cutovers = new Set(CUTOVER_MIGRATIONS);
+  for (const e of input.pending) {
+    const text = input.text(e.file);
+    if (e.source.startsWith("core:0")) {
+      const f = e.source.slice("core:".length);
+      const mode = input.manifest?.migrations[f]?.mode ?? (cutovers.has(f) ? "cutover" : "n1");
+      out.push({
+        file: e.file,
+        source: e.source,
+        mode,
+        because:
+          mode === "cutover" ? "core marks it a cutover" : "core's release suites ran the previous release over it",
+      });
+      continue;
+    }
+    if (e.source.startsWith("core:")) {
+      // The pinned timezone's rules and the checkout-track fingerprint: core's generated files, N−1 by design.
+      out.push({ file: e.file, source: e.source, mode: "n1", because: "core generates it N−1 (p0.4 §4, p0.7 §6)" });
+      continue;
+    }
+    const [kind, plugin, ...rest] = e.source.split(":");
+    const id = rest.join(":");
+    const texts = statementTexts(text);
+    const before = existingBefore(input, e.file);
+    if (kind === "plugin" && (id.startsWith("generated:") || id.startsWith("entity:") || id === "install")) {
+      // The composer replacing what it owns: drops only of this plugin's earlier generated objects.
+      const earlier = new Set<string>();
+      for (const prior of input.lock.entries) {
+        if (prior.file === e.file) break;
+        if (prior.source.startsWith(`plugin:${plugin}:`))
+          for (const o of created(statementTexts(readFileSync(join(input.cwd, "migrations", prior.file), "utf8"))))
+            earlier.add(o);
+      }
+      const bad = judgeFile(texts, before, (k, n) => earlier.has(`${k}:${n}`)).filter((j) => j.drop);
+      if (bad.length) problems.push(`${e.file} (${e.source}): ${bad.map((b) => `${b.drop}: ${b.why}`).join("; ")}`);
+      else
+        out.push({
+          file: e.file,
+          source: e.source,
+          mode: "n1",
+          because: "a plugin generation: an older Worker's writes are fenced as PLUGIN_UPGRADING (p0.7 §6)",
+        });
+      continue;
+    }
+    const judged = judgeFile(texts, before, () => false);
+    const drops = judged.filter((j) => j.drop);
+    if (drops.length) {
+      problems.push(
+        `${e.file} (${e.source}): ${drops.map((d) => `${d.drop}: ${d.why}; only core's cutovers may, behind the fence`).join("; ")}`,
+      );
+      continue;
+    }
+    const statement =
+      /--\s*kedge:n-1\s+(\S.*)/.exec(text)?.[1]?.trim() ??
+      (kind === "plugin"
+        ? input.plugins.find((p) => p.definition.name === plugin)?.definition.migrations?.find((m) => m.id === id)?.n1
+        : undefined);
+    const shaped = judged.filter((j) => !j.ok);
+    if (shaped.length === 0)
+      out.push({ file: e.file, source: e.source, mode: "n1", because: "shape: only new tables and plain indexes" });
+    else if (statement) out.push({ file: e.file, source: e.source, mode: "n1", because: `stated: ${statement}` });
+    else
+      problems.push(
+        `${e.file} (${e.source}): ${[...new Set(shaped.map((j) => j.why))].join("; ")}. If the running Worker survives it, say why in the file: -- kedge:n-1 <why>`,
+      );
+  }
+  if (problems.length) throw new NotN1(problems);
+  return out;
+}