/**
* Moves cloudhal-template (the Deploy to Cloudflare button) to a Cloudhal release, issue #111.
* .github/workflows/template-sync.yml runs it after each npm publish, then refreshes the
* lockfile and opens the PR; scripts/template-plan.ts has the rules. Without the workflow's
* GitHub App it runs by hand from a checkout, the same two commands (CONTRIBUTING.md, Releasing).
*
* node scripts/template-sync.ts --template
--version
* [--starter ] [--wait ] [--summary ] [--check] [--allow-downgrade]
* node scripts/template-sync.ts --template --version --lock [--wait ]
*
* Without --starter it waits up to --wait seconds (default 0) for npm to serve
* `@cloudhal/cli@`, takes the blog starter out of `npm pack` of it (no package code
* runs) and waits for every `@cloudhal/*` package that starter names. --starter reads a
* published-layout starter from disk instead, offline (the repo's starters/blog is refused: its
* specs are workspace:). --check writes nothing and exits 1 when the template is not current.
* --summary writes the PR body. The sync itself never runs npm install, nor `cloudhal deploy`,
* which rewrites the tracked wrangler.jsonc.
*
* --lock, run after a sync (an --allow-downgrade one too), refreshes package-lock.json with
* `npm install --package-lock-only --ignore-scripts` and every `@cloudhal/*` at exactly
* (scripts/template-lock.ts), retrying for up to --wait seconds while npm catches up, and fails
* unless the lock holds that version everywhere. Node built-ins only: the workflow runs it
* without a pnpm install.
*/
import { execFileSync } from "node:child_process";
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { parseArgs } from "node:util";
import { onNpm, unpublished } from "./release-plan.ts";
import { lockPins, lockProblems } from "./template-lock.ts";
import {
applySync,
currentVersion,
dependencyChanges,
planSync,
type SyncOp,
} from "./template-plan.ts";
import { prBody } from "./template-pr.ts";
/** Where the CLI tarball carries the starter `cloudhal init` copies. */
const STARTER_IN_TARBALL = "package/dist/assets/starters/blog";
function args() {
const { values } = parseArgs({
options: {
template: { type: "string" },
version: { type: "string" },
starter: { type: "string" },
wait: { type: "string", default: "0" },
summary: { type: "string" },
check: { type: "boolean", default: false },
"allow-downgrade": { type: "boolean", default: false },
lock: { type: "boolean", default: false },
},
strict: true,
});
const { template, version } = values;
const wait = Number(values.wait);
if (!template || !version) throw new Error("--template and --version are required");
if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`--version must be x.y.z, not ${version}`);
if (!Number.isInteger(wait) || wait < 0) throw new Error("--wait takes whole seconds");
if (
values.lock &&
(values.starter || values.summary || values.check || values["allow-downgrade"])
)
throw new Error("--lock takes only --template, --version and --wait");
return { ...values, template, version, wait };
}
/** Polls npm until it serves every package at `version`; throws once `seconds` have passed. */
async function waitForNpm(names: readonly string[], version: string, seconds: number) {
const pkgs = names.map((name) => ({ dir: name, name, version }));
const served = (name: string, v: string) => onNpm(name, v).catch(() => false);
const deadline = Date.now() + seconds * 1000;
for (;;) {
const missing = (await unpublished(pkgs, served)).map((p) => `${p.name}@${version}`);
if (!missing.length) return;
if (Date.now() >= deadline)
throw new Error(`npm does not serve ${missing.join(", ")} (waited ${seconds} s)`);
console.log(`waiting for npm to serve ${missing.join(", ")}`);
await new Promise((r) => setTimeout(r, Math.min(15_000, Math.max(0, deadline - Date.now()))));
}
}
/** Downloads `@cloudhal/cli@` into `tmp` and extracts only its blog starter. */
async function fetchStarter(version: string, wait: number, tmp: string): Promise {
await waitForNpm(["@cloudhal/cli"], version, wait);
const out = execFileSync(
"npm",
["pack", `@cloudhal/cli@${version}`, "--pack-destination", tmp, "--ignore-scripts", "--json"],
{ cwd: tmp, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] },
);
const [packed] = JSON.parse(out) as { filename?: string }[];
if (!packed?.filename) throw new Error(`npm pack printed no tarball: ${out}`);
const into = path.join(tmp, "x");
await mkdir(into);
const tgz = path.join(tmp, path.basename(packed.filename));
execFileSync("tar", ["-xzf", tgz, "-C", into, STARTER_IN_TARBALL], { stdio: "inherit" });
const starter = path.join(into, STARTER_IN_TARBALL);
const pkg = JSON.parse(await readFile(path.join(starter, "package.json"), "utf8")) as {
dependencies?: Record;
devDependencies?: Record;
};
const scoped = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })
.filter((name) => name.startsWith("@cloudhal/"))
.sort();
await waitForNpm(scoped, version, wait);
return starter;
}
const readJson = async (file: string) =>
JSON.parse(await readFile(file, "utf8")) as Record;
/** --lock: package-lock.json with every `@cloudhal/*` at exactly `version`, or an error. */
async function refreshLock(templateDir: string, version: string, wait: number): Promise {
const pkgFile = path.join(templateDir, "package.json");
const npmArgs = [
"install",
"--package-lock-only",
"--ignore-scripts",
"--no-audit",
"--no-fund",
"--save-prefix=^",
"--no-save-exact",
...lockPins(await readJson(pkgFile), version),
];
// npm can serve a new version's metadata minutes after the publish.
const deadline = Date.now() + wait * 1000;
for (let attempt = 1; ; attempt++) {
try {
execFileSync("npm", npmArgs, { cwd: templateDir, stdio: "inherit" });
break;
} catch {
if (Date.now() >= deadline)
throw new Error(
`npm install --package-lock-only failed (attempt ${attempt}, --wait ${wait})`,
);
console.log(`npm install failed (attempt ${attempt}); retrying in up to 60 s`);
await new Promise((r) => setTimeout(r, Math.min(60_000, deadline - Date.now())));
}
}
const lock = await readJson(path.join(templateDir, "package-lock.json"));
const problems = lockProblems(await readJson(pkgFile), lock, version);
if (problems.length)
throw new Error(`the refreshed lock does not install ${version}:\n ${problems.join("\n ")}`);
console.log(`package-lock.json locks every @cloudhal/* package at ${version}`);
}
function describe(op: SyncOp): string {
if (op.kind === "delete") return `removed ${op.path}`;
return `${op.added ? "added" : "updated"} ${op.path}`;
}
function runUrl(): string | undefined {
const { GITHUB_SERVER_URL: server, GITHUB_REPOSITORY: repo, GITHUB_RUN_ID: run } = process.env;
return server && repo && run ? `${server}/${repo}/actions/runs/${run}` : undefined;
}
async function main(): Promise {
const opts = args();
const templateDir = path.resolve(opts.template);
if (opts.lock) return refreshLock(templateDir, opts.version, opts.wait);
const tmp = await mkdtemp(path.join(os.tmpdir(), "cloudhal-template-sync-"));
try {
const starterDir = opts.starter
? path.resolve(opts.starter)
: await fetchStarter(opts.version, opts.wait, tmp);
const pkgFile = path.join(templateDir, "package.json");
const before = await readJson(pkgFile);
const ops = await planSync({
starterDir,
templateDir,
version: opts.version,
allowDowngrade: opts["allow-downgrade"],
});
for (const op of ops) console.log(describe(op));
if (!ops.length) console.log(`cloudhal-template is current at ${opts.version}`);
if (opts.check) {
process.exitCode = ops.length ? 1 : 0;
return;
}
await applySync(templateDir, ops);
if (opts.summary) {
const after = await readJson(pkgFile);
const deps = dependencyChanges(before, after);
const from = currentVersion(before);
await writeFile(
opts.summary,
prBody({ ops, from, to: opts.version, deps, runUrl: runUrl() }),
);
}
} finally {
await rm(tmp, { recursive: true, force: true });
}
}
try {
await main();
} catch (e) {
console.error(`template-sync: ${(e as Error).message}`);
process.exitCode = 1;
}