@kedge/cli 0.0.0-stage → 0.10.0

package/src/upgrade.ts

@@ -0,0 +1,235 @@
+// `kedge upgrade --to <version>` (docs/proposals/p0.8-cli-agent-kit.md §8.2).
+// Medusa's rule: cover every release in between and stop on the first failure
+// rather than pile on speculative fixes (research/14 §1). Hydrogen's: write what
+// a codemod can't do to a file. And Kedge's own: a deploy refuses a release not
+// proven against the one serving, and composed migrations can't be un-composed,
+// so a target more than one supported step away refuses before anything changes.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isMap, parse, parseDocument } from "yaml";
+import { installedPackages, type Manifest } from "./manifest";
+import { byCodePoint } from "./order";
+import type { Git } from "./store";
+import { unitDrift } from "./units";
+
+export interface NoteEntry {
+  id: string;
+  affects?: string[];
+  detect?: string;
+  codemod?: string | null;
+  manual?: string;
+  verify?: string;
+}
+
+export interface UpgradeNote {
+  version: string;
+  upgradesFrom: string | null;
+  /** Packages this release adds to a store, written in before the install (p0.9 §3.2). */
+  adds?: string[];
+  entries: NoteEntry[];
+}
+
+export class UpgradeRefused extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UpgradeRefused";
+  }
+}
+
+export function readNotes(dir: string): Map<string, UpgradeNote> {
+  const out = new Map<string, UpgradeNote>();
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+    const m = /^---\n([\s\S]*?)\n---\n/.exec(readFileSync(join(dir, f), "utf8"));
+    if (!m) continue;
+    const fm = parse(m[1] as string) as Partial<UpgradeNote>;
+    if (typeof fm.version === "string")
+      out.set(fm.version, {
+        version: fm.version,
+        upgradesFrom: fm.upgradesFrom ?? null,
+        ...(Array.isArray(fm.adds)
+          ? { adds: fm.adds.filter((a) => typeof a === "string" && a.startsWith("@kedge/")) }
+          : {}),
+        entries: fm.entries ?? [],
+      });
+  }
+  return out;
+}
+
+/** The releases from `current` to `target`, each proven against the one before; null when there's no such chain. */
+export function chain(notes: ReadonlyMap<string, UpgradeNote>, current: string, target: string): string[] | null {
+  const stages: string[] = [];
+  let at: string | null = target;
+  while (at && at !== current) {
+    stages.unshift(at);
+    if (stages.length > 50) return null;
+    at = notes.get(at)?.upgradesFrom ?? null;
+  }
+  return at === current ? stages : null;
+}
+
+export interface UpgradeInput {
+  cwd: string;
+  to: string;
+  fromPacks?: string;
+  git: Git;
+  manifest: (cwd: string) => Manifest | null;
+  /** Runs a command in the store; tests replace it. */
+  run?: (cmd: string, args: string[], cwd: string) => number;
+  /** `kedge generate` then `kedge check`, by the CLI the upgrade just installed, never this process's older one. */
+  kedge: (argv: string[]) => Promise<number>;
+  log?: (s: string) => void;
+}
+
+/** The target's @kedge/docs, fetched before anything is installed, so its notes decide. */
+function fetchDocs(to: string, fromPacks: string | undefined): { dir: string; cleanup: () => void } {
+  const tmp = mkdtempSync(join(tmpdir(), "kedge-upgrade-"));
+  let tgz: string;
+  if (fromPacks) tgz = join(fromPacks, `kedge-docs-${to}.tgz`);
+  else {
+    const r = spawnSync("npm", ["pack", `@kedge/docs@${to}`, "--pack-destination", tmp], { encoding: "utf8" });
+    if (r.status !== 0)
+      throw new UpgradeRefused(`can't fetch @kedge/docs@${to}: ${r.stderr.trim().split("\n").at(-1)}`);
+    tgz = join(tmp, r.stdout.trim().split("\n").at(-1) as string);
+  }
+  if (!existsSync(tgz)) throw new UpgradeRefused(`no @kedge/docs ${to} at ${tgz}`);
+  const x = spawnSync("tar", ["-xzf", tgz, "-C", tmp]);
+  if (x.status !== 0) throw new UpgradeRefused(`can't unpack ${tgz}`);
+  return { dir: join(tmp, "package"), cleanup: () => rmSync(tmp, { recursive: true, force: true }) };
+}
+
+/**
+ * The workspace's Kedge overrides, made to name the requested source: each package's tarball in
+ * `fromPacks`, or none, for the registry. An override left from the last source wins at install, and
+ * the old release would stay installed under the new one's version (codex code r30). Other overrides stay.
+ */
+export function reconcileOverrides(text: string, to: string, fromPacks?: string): string {
+  const doc = parseDocument(text);
+  const found = doc.get("overrides");
+  const overrides = isMap(found) ? found : doc.createNode({});
+  for (const item of [...overrides.items]) {
+    const key = String((item.key as { value?: unknown })?.value ?? item.key);
+    if (key.startsWith("@kedge/")) overrides.delete(key);
+  }
+  if (fromPacks) {
+    const tgz = new RegExp(`^kedge-(.+)-${to.replace(/\./g, "\\.")}\\.tgz$`);
+    const packs = readdirSync(fromPacks)
+      .map((f) => [f, tgz.exec(f)?.[1]] as const)
+      .filter((x): x is readonly [string, string] => Boolean(x[1]))
+      .sort(([, a], [, b]) => byCodePoint(a, b));
+    if (!packs.length) throw new UpgradeRefused(`no Kedge ${to} packs in ${fromPacks}`);
+    for (const [file, name] of packs) overrides.set(`@kedge/${name}`, `file:${join(fromPacks, file)}`);
+  }
+  if (overrides.items.length) doc.set("overrides", overrides);
+  else doc.delete("overrides");
+  return doc.toString();
+}
+
+/** Installed Kedge packages that aren't the target's version, which no codemod may run against. */
+export function notAt(cwd: string, to: string): string[] {
+  return [...installedPackages(cwd)]
+    .map(([name, dir]) => [
+      name,
+      (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { version: string }).version,
+    ])
+    .filter(([, v]) => v !== to)
+    .map(([name, v]) => `${name} ${v}`);
+}
+
+export async function upgrade(input: UpgradeInput): Promise<void> {
+  const log = input.log ?? console.log;
+  const run = input.run ?? ((cmd, args, cwd) => spawnSync(cmd, args, { cwd, stdio: "inherit" }).status ?? 1);
+  if (input.git.dirty().length)
+    throw new UpgradeRefused("commit first: an upgrade's diff should be the upgrade's alone");
+  const cliDir = installedPackages(input.cwd).get("@kedge/cli");
+  if (!cliDir) throw new UpgradeRefused("@kedge/cli isn't installed here");
+  const current = (JSON.parse(readFileSync(join(cliDir, "package.json"), "utf8")) as { version: string }).version;
+  if (current === input.to) throw new UpgradeRefused(`already on ${current}`);
+  const docs = fetchDocs(input.to, input.fromPacks);
+  let notes: Map<string, UpgradeNote>;
+  try {
+    notes = readNotes(join(docs.dir, "upgrading"));
+  } finally {
+    docs.cleanup();
+  }
+  const stages = chain(notes, current, input.to);
+  if (!stages) throw new UpgradeRefused(`Kedge ${input.to}'s upgrade notes don't reach ${current}: no supported path`);
+  if (stages.length > 1)
+    throw new UpgradeRefused(
+      `${input.to} is ${stages.length} supported steps from ${current}; deploy each in turn:\n${stages.map((v) => `  kedge upgrade --to ${v}${input.fromPacks ? " --from-packs <dir>" : ""}, then kedge deploy`).join("\n")}`,
+    );
+
+  // Every @kedge package to the target, together.
+  const pkgFile = join(input.cwd, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgFile, "utf8")) as Record<string, Record<string, string>>;
+  for (const field of ["dependencies", "devDependencies"])
+    for (const dep of Object.keys(pkg[field] ?? {}))
+      if (dep.startsWith("@kedge/")) (pkg[field] as Record<string, string>)[dep] = input.to;
+  // A package the release adds, before the one install, so the codemod that uses it finds it (p0.9 §3.2).
+  for (const added of notes.get(input.to)?.adds ?? [])
+    if (!pkg.dependencies?.[added] && !pkg.devDependencies?.[added]) {
+      pkg.dependencies = { ...(pkg.dependencies ?? {}), [added]: input.to };
+      log(`added ${added} ${input.to}, which this release brings`);
+    }
+  writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+  const ws = join(input.cwd, "pnpm-workspace.yaml");
+  if (existsSync(ws) || input.fromPacks)
+    writeFileSync(ws, reconcileOverrides(existsSync(ws) ? readFileSync(ws, "utf8") : "", input.to, input.fromPacks));
+  // An upgrade changes the lockfile by definition; CI would otherwise freeze it.
+  if (run("pnpm", ["install", "--no-frozen-lockfile"], input.cwd) !== 0)
+    throw new UpgradeRefused("pnpm install failed; nothing else ran");
+  const stale = notAt(input.cwd, input.to);
+  if (stale.length) throw new UpgradeRefused(`the install left ${stale.join(", ")}, not ${input.to}; no codemod ran`);
+
+  // Each entry's codemod, from the newly installed @kedge/docs; what's left goes to UPGRADE-TODO.md.
+  const installedDocs = installedPackages(input.cwd).get("@kedge/docs");
+  const note = notes.get(input.to) as UpgradeNote;
+  const todo: string[] = [
+    `# Upgrading to Kedge ${input.to}`,
+    "",
+    `From ${current}. Written by kedge upgrade; work through it, then delete it.`,
+    "",
+  ];
+  for (const e of note.entries) {
+    const left: string[] = [];
+    if (e.codemod) {
+      const file = installedDocs ? join(installedDocs, "upgrading", "codemods", `${e.codemod}.mjs`) : "";
+      if (!file || !existsSync(file)) left.push(`the codemod ${e.codemod} is missing from @kedge/docs`);
+      else {
+        const mod = (await import(pathToFileURL(file).href)) as {
+          default: (
+            dir: string,
+          ) => { changed: string[]; todo: string[] } | Promise<{ changed: string[]; todo: string[] }>;
+        };
+        const r = await mod.default(input.cwd);
+        for (const c of r.changed) log(`codemod ${e.codemod}: changed ${c}`);
+        left.push(...r.todo);
+      }
+    }
+    // Manual steps stand beside a codemod, not instead of one: what it can't do is why they're there (codex code r10).
+    if (e.manual) left.push(e.manual);
+    if (left.length)
+      todo.push(
+        `## ${e.id}`,
+        "",
+        ...(e.affects?.length ? [`Affects: ${e.affects.join(", ")}`, ""] : []),
+        ...left.map((l) => `- ${l}`),
+        ...(e.verify ? ["", `Verify: \`${e.verify}\``] : []),
+        "",
+      );
+  }
+  const drift = unitDrift(input.cwd, input.manifest(input.cwd), null, { ignoreWiring: true });
+  if (drift.status === "fail") todo.push("## Ejected units", "", "```diff", ...(drift.details ?? []), "```", "");
+  writeFileSync(join(input.cwd, "UPGRADE-TODO.md"), `${todo.join("\n").trimEnd()}\n`);
+  log("wrote UPGRADE-TODO.md");
+
+  // Then generate and check, stopping at the first failure with its output.
+  if ((await input.kedge(["generate"])) !== 0)
+    throw new UpgradeRefused("kedge generate failed after the upgrade; UPGRADE-TODO.md says what's left");
+  if ((await input.kedge(["check"])) !== 0)
+    throw new UpgradeRefused("kedge check failed after the upgrade; UPGRADE-TODO.md says what's left");
+  log(`upgraded to Kedge ${input.to}; nothing is committed`);
+}

package/src/worker-config.ts

@@ -0,0 +1,81 @@
+// The store's Worker config (docs/proposals/p0.6b-webhooks-calendar-preview.md
+// §2.8): every Worker that sends webhooks needs `global_fetch_strictly_public`,
+// or a `fetch` to a host in its own zone goes straight to that zone's origin,
+// around Cloudflare's security settings for it
+// (https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public).
+//
+// `kedge generate` reads the config as wrangler does, to a value, and checks
+// that value; it never edits the file. Editing JSONC text without a full
+// parser failed three codex rounds (a trailing comma, a commented-out list,
+// a string holding a bracket), so the merchant adds the flag, told exactly
+// where. An `env.<name>` that sets its own list overrides the top-level one
+// ("Inheritable keys … can be inherited (or overridden) by
+// environment-specific configuration",
+// https://developers.cloudflare.com/workers/wrangler/configuration/#inheritable-keys),
+// so each such list needs the flag too.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const STRICTLY_PUBLIC = "global_fetch_strictly_public";
+const FILES = ["wrangler.jsonc", "wrangler.json"];
+
+/**
+ * JSONC as JSON: comments and trailing commas dropped, every string kept
+ * byte for byte. One pass that knows when it is inside a string, so nothing
+ * a string holds is read as a comment, a comma or structure.
+ */
+export function jsoncToJson(text: string): string {
+  let out = "";
+  let i = 0;
+  const skip = (from: number): number => {
+    let j = from;
+    for (;;) {
+      if (/\s/.test(text[j] ?? "")) j++;
+      else if (text.startsWith("//", j)) j = text.includes("\n", j) ? text.indexOf("\n", j) + 1 : text.length;
+      else if (text.startsWith("/*", j)) j = text.includes("*/", j + 2) ? text.indexOf("*/", j + 2) + 2 : text.length;
+      else return j;
+    }
+  };
+  while (i < text.length) {
+    const ch = text[i] as string;
+    if (ch === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j + 1;
+    } else if (text.startsWith("//", i) || text.startsWith("/*", i)) {
+      i = skip(i);
+      out += " ";
+    } else if (ch === ",") {
+      const next = skip(i + 1);
+      if (text[next] !== "]" && text[next] !== "}") out += ",";
+      i++;
+    } else {
+      out += ch;
+      i++;
+    }
+  }
+  return out;
+}
+
+type Flags = unknown;
+const hasFlag = (flags: Flags) => Array.isArray(flags) && flags.includes(STRICTLY_PUBLIC);
+
+/** The Worker config's refusal, or null when every list it deploys with holds the flag. */
+export function strictlyPublic(cwd: string): { file: string | null; problem: string | null } {
+  const file = FILES.map((f) => join(cwd, f)).find((f) => existsSync(f));
+  if (!file) return { file: null, problem: null };
+  let config: { compatibility_flags?: Flags; env?: Record<string, { compatibility_flags?: Flags }> };
+  try {
+    config = JSON.parse(jsoncToJson(readFileSync(file, "utf8")));
+  } catch (e) {
+    return { file, problem: `${file} doesn't parse as JSONC: ${(e as Error).message}` };
+  }
+  const add = `add "${STRICTLY_PUBLIC}" to`;
+  if (!hasFlag(config.compatibility_flags))
+    return { file, problem: `${file}: ${add} the top-level "compatibility_flags" (webhooks need it, p0.6b §2.8)` };
+  for (const [name, env] of Object.entries(config.env ?? {}))
+    if (env && typeof env === "object" && "compatibility_flags" in env && !hasFlag(env.compatibility_flags))
+      return { file, problem: `${file}: env.${name} sets its own "compatibility_flags"; ${add} it (p0.6b §2.8)` };
+  return { file, problem: null };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.