@getvitops/cli 8.0.0 → 8.1.0

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, parse, relative, resolve } from "node:path";
-import { JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_LOCAL_PATH, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, movedTokens, processorsMissingLocation, renderRobotsTxt, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
+import { CONFIG_SCHEMA_LOCAL_PATH, JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_LOCAL_PATH, buildIconSprite, defaultConfig, defaultSiteConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, movedTokens, processorsMissingLocation, renderRobotsTxt, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
 import { collectIconRefs, generateFavicons, generateIconInclude, resolveIcon, scanFiles } from "@getvitops/utils";
 import { SCOPES, SNAPSHOT_PATH, adcCredentialsPath, adcQuotaProject, collectEntries, formatPlan, googleAccessToken, inspectUrl, keyFileContents, newKey, parseAdcUser, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
 import { REVIEWS_CACHE_PATH, fetchReviews, formatPlan as formatPlan$1, mergeCache, plan as plan$1, readCache, selectReviews, toCache, writeCache } from "@getvitops/utils/reviews";
@@ -14,6 +14,8 @@ import { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan as form
 import { AD_PLATFORMS, AD_PROVIDER_KEYS, formatPlan as formatPlan$4, formatSummary as formatSummary$1, hasDrift as hasDrift$1, isAdProvider, missingFields, plan as plan$3, renderTag, tagId } from "@getvitops/utils/ads";
 import { PLATFORM_PARAMS } from "@getvitops/utils/tracking";
 import { createInterface } from "node:readline/promises";
+import { execFileSync } from "node:child_process";
+import { adminCollaboratorIds, branches, createD1, createDevEnvironment, createProdEnvironment, createR2Bucket, createRepo, defaultBranch, environments, findD1, findR2Bucket, formatPlan as formatPlan$5, formatSummary as formatSummary$2, ghAuthed, mainProtected, originRemote, plan as plan$4, planDomainConsistency, protectMain, pushBranches, repoNwo, secretsPresent, setDefaultBranch, setSecret, wranglerWhoami } from "@getvitops/utils/hosting";
 
 //#region src/args.ts
 /**
@@ -326,6 +328,7 @@ Usage:
   vitops icons [options]        Report which icons your source uses, and build the sprite
   vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)
   vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint
+  vitops setup <sub> [opts]     Scripted onboarding: repo, hosting, domain, search, ads, all
   vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
 
 Generate options:
@@ -344,8 +347,15 @@ Generate options:
       --site-env <env>  Environment whose A/B variant applies (default: production)
 
 Init options:
-  -o, --out <path>      Where to write (default: ./design-system.json)
+  -o, --out <path>      Where to write (default: ./design-system.json, or
+                        ./site.json with --site)
       --force           Overwrite an existing file
+      --site            Write a site config (Config) instead of a bare
+                        design-system.json — embeds a starter design system at
+                        designSystem.themes.default, since a Config can't
+                        merely reference a sibling file
+      --name <name>     organization.name, when --site is set
+      --url <url>       site.environments.{production,dev}.url, when --site is set
 
 Validate options:
   <file>                Config to check (default: ./design-system.json). Either
@@ -381,6 +391,7 @@ Docs options:
 
 Icons options:
   -i, --input <path>    Site config carrying the "icons" block (default: ./site.json)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
       --src <dir>       Source to scan for icon usage (default: ./src)
       --sprite          Also build the SVG sprite
   -o, --out <dir>       Where to write icons.svg with --sprite (default: ./dist)
@@ -566,6 +577,61 @@ Ads lint options:
   off (every conversion arrives unattributed), and a configured property with no
   tag ID. Exits non-zero on a finding.
 
+Setup repo options:
+      --dry             Print the plan and exit
+      --check           Report drift/blocked steps and exit non-zero, mutating nothing
+      --public          Create the repo public (default: private)
+      --platform <p>    cloudflare (default) | node — shown for parity with the hosting stage's plan
+      --no-dev-resources  Same — this stage never provisions D1/R2 either way
+
+  Creates the GitHub repo (via \`gh\`), pushes main + dev, makes dev the default
+  branch, and requests main branch protection + the production/dev environments.
+  Idempotent — a re-run of a fully set-up repo is all skips. Branch protection and
+  environment reviewers 403 on a private repo without GitHub Pro/Team; that is
+  reported as blocked, with the manual Settings path, never as a failure.
+
+Setup hosting options:
+      --dry             Print the plan and exit
+      --check           Report drift/blocked steps and exit non-zero, mutating nothing
+      --platform <p>    cloudflare (default) | node
+      --no-dev-resources  Skip D1/R2 — a pure static Workers Assets project has
+                        nothing to provision, just the account id + token
+
+  Provisions the isolated dev D1 database + R2 bucket (cloudflare) and sets the
+  DEV_D1_ID / CLOUDFLARE_ACCOUNT_ID repo secrets, once \`vitops setup repo\` has run.
+  CLOUDFLARE_API_TOKEN is always reported as blocked — no API can create one; see
+  the printed dashboard link. Requires \`npx wrangler login\` first.
+
+Setup domain options:
+  -i, --input <path>    Site config (default: ./site.json)
+      --site-env <env>  Environment to check (default: production)
+      --dry             Print the plan and exit
+      --check           Exit non-zero if the domain state is inconsistent
+      --domain <apex>   Print the manual cutover steps for this apex
+
+  Plans and checks the consistency between wrangler.jsonc's workers.dev/custom-domain
+  state and site.json's environments/domains/robots — it NEVER edits wrangler.jsonc
+  or deploys. Cutover overwrites the zone's DNS record and can take an existing live
+  site down; that step is manual, on purpose. See SETUP.html's "Domain strategy" stage.
+
+Setup search options:
+  Forwards every option to \`vitops search setup\` unchanged — see "Search setup
+  options:" above.
+
+Setup ads options:
+  Forwards every option to \`vitops ads setup\` unchanged — see "Ads setup options:"
+  above.
+
+Setup all options:
+      --dry             Print every stage's plan and exit
+      --check           Report drift across every stage and exit non-zero
+      --public          Create the repo public, for the repo stage
+      --platform <p>    cloudflare (default) | node, for the repo + hosting stages
+      --no-dev-resources  Skip D1/R2 in the hosting stage (repo stage never provisions them)
+
+  Runs repo, hosting, search, ads in order. Stops at the first stage that fails;
+  a blocked step (the API token, GitHub Pro/Team gating) is reported, not fatal.
+
 Media options:
       --raw <dir>       Directory of unprocessed video, walked recursively
                         (default: ./raw)
@@ -607,6 +673,18 @@ const ADS_HELP = `vitops ads — link this site to its ad properties
   vitops ads tags [opts]        Print the consent-gated pixel snippets
   vitops ads lint [opts]        Report ad properties the rest of the config can't see
 
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
+const SETUP_HELP$1 = `vitops setup — the scripted path from an empty scaffold to a live site
+
+  vitops setup repo [opts]      GitHub repo + branch policy (main protected, dev open)
+  vitops setup hosting [opts]   Dev D1 + R2 + repo secrets (cloudflare) or a Node target
+  vitops setup domain [opts]    Plan/check the workers.dev-vs-custom-domain consistency
+                                 (never applies the cutover — see SETUP.html)
+  vitops setup search [opts]    Forwards to \`vitops search setup\`
+  vitops setup ads [opts]       Forwards to \`vitops ads setup\`
+  vitops setup all [opts]       Run repo, hosting, search, ads in order
+
 Run \`vitops --help\` for the full option list for each subcommand.
 `;
 /**
@@ -628,6 +706,7 @@ const COMMANDS = [
 	"icons",
 	"search",
 	"ads",
+	"setup",
 	"media"
 ];
 /**
@@ -657,7 +736,7 @@ const wantsHelp = (argv) => argv.includes("-h") || argv.includes("--help");
 /** The help text to print for `vitops <command> [sub] --help`. */
 function helpFor(command, argv) {
 	const sub = argv[0] && !argv[0].startsWith("-") ? argv[0] : void 0;
-	return (sub ? helpSection(command, sub) : void 0) ?? helpSection(command) ?? (command === "search" ? SEARCH_HELP : command === "ads" ? ADS_HELP : void 0) ?? HELP;
+	return (sub ? helpSection(command, sub) : void 0) ?? helpSection(command) ?? (command === "search" ? SEARCH_HELP : command === "ads" ? ADS_HELP : command === "setup" ? SETUP_HELP$1 : void 0) ?? HELP;
 }
 
 //#endregion
@@ -1472,6 +1551,421 @@ async function cmdAds(argv) {
 	}
 }
 
+//#endregion
+//#region src/commands/setup.ts
+/**
+* `vitops setup` — the scripted path from an empty scaffold to a live site.
+* Subcommands: `repo | hosting | domain | search | ads | all`.
+*
+* Absorbs what each template's `scripts/init-{github,hosting}.mjs` used to do
+* template-locally, so the capability reaches every consumer, not just a fresh
+* `vp create` scaffold. `repo`/`hosting` follow the pure-planner/executor split in
+* `@getvitops/utils/hosting` — see that module's docblock. `search`/`ads` are not
+* reimplemented: this shells out to the CLI's own `search setup`/`ads setup`
+* subcommands as child processes, so their behaviour (prompting, `--dry`,
+* `--check`, writing the config patch back) stays exactly what it already is,
+* with no risk of the two copies drifting.
+*
+* `domain` only ever plans and checks the workers.dev-vs-custom-domain
+* consistency — it never touches `wrangler.jsonc` or deploys anything. Cutover
+* overwrites the zone's DNS record and can take an existing live site down; that
+* is a human's call, made in `SETUP.html`, not a step this command applies.
+*/
+const SETUP_HELP = `vitops setup <sub> [options]
+
+  vitops setup repo    [--dry] [--check] [--public]
+  vitops setup hosting [--dry] [--check] [--platform cloudflare|node]
+  vitops setup domain  [--dry] [--check] [--domain <apex>]
+  vitops setup search  [options]   (forwards to \`vitops search setup\`)
+  vitops setup ads     [options]   (forwards to \`vitops ads setup\`)
+  vitops setup all     [--dry] [--check] [--public] [--platform <p>]
+
+--dry prints the plan and stops. --check reports drift/blocked steps and exits
+non-zero, mutating nothing. Neither creates the Cloudflare API token or performs
+a custom-domain cutover — both are named as manual steps; see SETUP.html.`;
+function projectName() {
+	const path = resolve("package.json");
+	if (!existsSync(path)) fail("package.json not found — run this from the project root");
+	const pkg = JSON.parse(readFileSync(path, "utf8"));
+	if (!pkg.name) fail("package.json has no \"name\" field");
+	return pkg.name.replace(/^@[^/]+\//, "");
+}
+async function gatherHostingState(name, platform) {
+	const [wrangler, gh, origin] = await Promise.all([
+		platform === "cloudflare" ? wranglerWhoami() : Promise.resolve({ authed: false }),
+		ghAuthed(),
+		originRemote()
+	]);
+	const nwo = origin ? await repoNwo() : void 0;
+	const [branchesList, def, protectedMain, envs, secrets, d1Id, r2] = await Promise.all([
+		branches(),
+		nwo ? defaultBranch(nwo) : Promise.resolve(void 0),
+		nwo ? mainProtected(nwo) : Promise.resolve(false),
+		nwo ? environments(nwo) : Promise.resolve([]),
+		nwo ? secretsPresent(nwo) : Promise.resolve([]),
+		platform === "cloudflare" ? findD1(`${name}-dev`) : Promise.resolve(void 0),
+		platform === "cloudflare" ? findR2Bucket(`${name}-media-dev`) : Promise.resolve(false)
+	]);
+	return {
+		wranglerAuthed: wrangler.authed,
+		..."accountId" in wrangler && wrangler.accountId ? { accountId: wrangler.accountId } : {},
+		d1Present: Boolean(d1Id),
+		...d1Id ? { d1Id } : {},
+		r2Present: r2,
+		ghAuthed: gh,
+		...origin ? { originRemote: origin } : {},
+		...nwo ? { repoNwo: nwo } : {},
+		branches: branchesList,
+		...def ? { defaultBranch: def } : {},
+		mainProtected: protectedMain,
+		environments: envs,
+		secretsPresent: secrets
+	};
+}
+async function cmdSetupRepo(argv) {
+	const a = parse$1(argv, {
+		dry: {
+			type: "boolean",
+			default: false
+		},
+		check: {
+			type: "boolean",
+			default: false
+		},
+		public: {
+			type: "boolean",
+			default: false
+		},
+		platform: {
+			type: "string",
+			default: "cloudflare"
+		},
+		"no-dev-resources": {
+			type: "boolean",
+			default: false
+		}
+	});
+	const platform = a.str("platform");
+	if (platform !== "cloudflare" && platform !== "node") fail(`--platform "${platform}" must be cloudflare or node`);
+	const name = projectName();
+	const setup = {
+		platform,
+		projectName: name,
+		repoVisibility: a.flag("public") ? "public" : "private",
+		devResources: !a.flag("no-dev-resources")
+	};
+	const state = await gatherHostingState(name, setup.platform);
+	const p = plan$4(setup, state);
+	const dry = a.flag("dry");
+	const check = a.flag("check");
+	if (dry || check) {
+		console.log(formatPlan$5(p));
+		if (check && (p.repo.action !== "skip" || p.branches.action !== "skip" || p.defaultBranch.action !== "skip")) {
+			console.error("\n✖ repo/branch setup is not complete");
+			process.exit(1);
+		}
+		return;
+	}
+	const results = [];
+	if (p.repo.action === "create") {
+		const r = await createRepo(name, setup.repoVisibility);
+		results.push({
+			step: "repo",
+			status: r.ok ? "created" : "failed",
+			detail: r.ok ? name : r.message ?? "failed"
+		});
+		if (r.ok) {
+			const push = await pushBranches();
+			results.push({
+				step: "branches",
+				status: push.ok ? "created" : "failed",
+				detail: push.ok ? "main + dev pushed" : push.message ?? "failed"
+			});
+		}
+	} else results.push({
+		step: "repo",
+		status: "present",
+		detail: p.repo.detail
+	});
+	const nwo = state.repoNwo ?? await repoNwo();
+	if (nwo) {
+		if (p.defaultBranch.action !== "skip") {
+			const r = await setDefaultBranch(nwo, "dev");
+			results.push({
+				step: "default branch",
+				status: r.ok ? "updated" : "failed",
+				detail: r.ok ? "dev" : r.message ?? "failed"
+			});
+		} else results.push({
+			step: "default branch",
+			status: "present",
+			detail: "dev"
+		});
+		if (p.mainProtection.action === "blocked") {
+			const r = await protectMain(nwo);
+			results.push({
+				step: "main protection",
+				status: r.ok ? "created" : "blocked",
+				detail: r.ok ? "protected" : r.message ?? p.mainProtection.detail
+			});
+		} else results.push({
+			step: "main protection",
+			status: "present",
+			detail: p.mainProtection.detail
+		});
+		if (p.prodEnvironment.action === "blocked") {
+			const ids = await adminCollaboratorIds(nwo);
+			const r = await createProdEnvironment(nwo, ids);
+			results.push({
+				step: "production env",
+				status: r.ok ? "created" : "blocked",
+				detail: r.ok ? `${ids.length} reviewer(s)` : r.message ?? p.prodEnvironment.detail
+			});
+		} else results.push({
+			step: "production env",
+			status: "present",
+			detail: p.prodEnvironment.detail
+		});
+		if (p.devEnvironment.action === "create") {
+			const r = await createDevEnvironment(nwo);
+			results.push({
+				step: "dev env",
+				status: r.ok ? "created" : "failed",
+				detail: r.ok ? "no required reviewers" : r.message ?? "failed"
+			});
+		} else results.push({
+			step: "dev env",
+			status: "present",
+			detail: p.devEnvironment.detail
+		});
+	} else results.push({
+		step: "branch policy",
+		status: "blocked",
+		detail: "no GitHub repo yet — run this again once \"repo\" succeeds"
+	});
+	console.log(formatSummary$2(results));
+	if (results.some((r) => r.status === "failed")) process.exit(1);
+}
+async function cmdSetupHosting(argv) {
+	const a = parse$1(argv, {
+		dry: {
+			type: "boolean",
+			default: false
+		},
+		check: {
+			type: "boolean",
+			default: false
+		},
+		platform: {
+			type: "string",
+			default: "cloudflare"
+		},
+		"no-dev-resources": {
+			type: "boolean",
+			default: false
+		}
+	});
+	const platform = a.str("platform");
+	if (platform !== "cloudflare" && platform !== "node") fail(`--platform "${platform}" must be cloudflare or node`);
+	const name = projectName();
+	const setup = {
+		platform,
+		projectName: name,
+		repoVisibility: "private",
+		devResources: !a.flag("no-dev-resources")
+	};
+	const state = await gatherHostingState(name, platform);
+	const p = plan$4(setup, state);
+	const dry = a.flag("dry");
+	const check = a.flag("check");
+	if (platform === "node") {
+		console.log("Hosting target \"node\" has no cloud resources to provision — see the template README's \"Hosting\" section.");
+		return;
+	}
+	if (!state.wranglerAuthed && !dry) fail("wrangler is not logged in — run `npx wrangler login` first");
+	if (dry || check) {
+		console.log(formatPlan$5(p));
+		if (check && (p.d1.action !== "skip" || p.r2.action !== "skip")) {
+			console.error("\n✖ hosting resources are not fully provisioned");
+			process.exit(1);
+		}
+		return;
+	}
+	const results = [];
+	let d1Id = state.d1Id;
+	if (p.d1.action === "create") {
+		const r = await createD1(`${name}-dev`);
+		results.push({
+			step: "dev D1",
+			status: r.ok ? "created" : "failed",
+			detail: r.ok ? r.id ?? "" : r.message ?? "failed"
+		});
+		if (r.ok) d1Id = r.id;
+	} else results.push({
+		step: "dev D1",
+		status: "present",
+		detail: p.d1.detail
+	});
+	if (p.r2.action === "create") {
+		const r = await createR2Bucket(`${name}-media-dev`);
+		results.push({
+			step: "dev R2",
+			status: r.ok ? "created" : "failed",
+			detail: r.ok ? `${name}-media-dev` : r.message ?? "failed"
+		});
+	} else results.push({
+		step: "dev R2",
+		status: "present",
+		detail: p.r2.detail
+	});
+	if ((state.repoNwo ?? await repoNwo()) && state.ghAuthed) {
+		if (d1Id && !state.secretsPresent.includes("DEV_D1_ID")) {
+			const r = await setSecret("DEV_D1_ID", d1Id);
+			results.push({
+				step: "secret DEV_D1_ID",
+				status: r.ok ? "created" : "failed",
+				detail: r.ok ? "set" : r.message ?? "failed"
+			});
+		} else results.push({
+			step: "secret DEV_D1_ID",
+			status: state.secretsPresent.includes("DEV_D1_ID") ? "present" : "blocked",
+			detail: d1Id ?? "D1 id unknown"
+		});
+		if (state.accountId && !state.secretsPresent.includes("CLOUDFLARE_ACCOUNT_ID")) {
+			const r = await setSecret("CLOUDFLARE_ACCOUNT_ID", state.accountId);
+			results.push({
+				step: "secret CLOUDFLARE_ACCOUNT_ID",
+				status: r.ok ? "created" : "failed",
+				detail: r.ok ? "set" : r.message ?? "failed"
+			});
+		} else results.push({
+			step: "secret CLOUDFLARE_ACCOUNT_ID",
+			status: state.secretsPresent.includes("CLOUDFLARE_ACCOUNT_ID") ? "present" : "blocked",
+			detail: state.accountId ?? "unknown"
+		});
+	} else results.push({
+		step: "secrets",
+		status: "blocked",
+		detail: "no GitHub repo wired up yet — run `vitops setup repo` first"
+	});
+	results.push({
+		step: "secret CLOUDFLARE_API_TOKEN",
+		status: "blocked",
+		detail: p.secrets["CLOUDFLARE_API_TOKEN"]?.detail ?? "create it by hand"
+	});
+	console.log(formatSummary$2(results));
+	for (const n of p.notes) console.log(`! ${n}`);
+	if (results.some((r) => r.status === "failed")) process.exit(1);
+}
+async function cmdSetupDomain(argv) {
+	const a = parse$1(argv, {
+		...SITE_OPTS,
+		dry: {
+			type: "boolean",
+			default: false
+		},
+		check: {
+			type: "boolean",
+			default: false
+		},
+		domain: { type: "string" }
+	});
+	const wranglerPath = resolve("wrangler.jsonc");
+	if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run this from the project root");
+	const raw = readFileSync(wranglerPath, "utf8");
+	const customDomainMatch = /^\s*"routes":\s*\[\s*\{\s*"pattern":\s*"([^"]+)"/m.exec(raw.split("\n").filter((l) => !l.trim().startsWith("//")).join("\n"));
+	const customDomain = customDomainMatch?.[1] ?? (a.opt("domain") ? void 0 : void 0);
+	const cfg = await loadConfig(a.path("input"), a.str("site-env"));
+	const env = cfg.site.environments[a.str("site-env")] ?? cfg.site.environments["production"];
+	const step = planDomainConsistency({
+		wranglerDev: !raw.includes("\"routes\"") || Boolean(customDomainMatch) === false,
+		...customDomain ? { customDomain } : {},
+		...env?.url ? { configuredUrl: env.url } : {},
+		...cfg.site.domains?.canonical ? { canonical: cfg.site.domains.canonical } : {},
+		...env?.robots ? { robots: env.robots } : {}
+	});
+	console.log(`${step.action === "skip" ? "·" : "?"} domain consistency  ${step.detail}`);
+	if (a.opt("domain")) console.log(`\nCutover is never applied by this command — see SETUP.html stage 4b. To cut over: uncomment routes in wrangler.jsonc with "pattern": "${a.opt("domain")}", deploy, then update site.domains.canonical and site.environments.${a.str("site-env")}.url to match.`);
+	if (a.flag("check") && step.action !== "skip") process.exit(1);
+}
+/** Forward to the CLI's own `search setup` / `ads setup` as a child process — see
+* this module's docblock for why (their behaviour must not be re-derived). */
+function forward(sub, argv) {
+	try {
+		execFileSync(process.execPath, [
+			process.argv[1],
+			sub,
+			"setup",
+			...argv
+		], { stdio: "inherit" });
+		return true;
+	} catch (err) {
+		if (err.status != null) return false;
+		fail(msg(err));
+	}
+}
+async function cmdSetup(argv) {
+	const [sub, ...rest] = argv;
+	switch (sub) {
+		case "repo": return cmdSetupRepo(rest);
+		case "hosting": return cmdSetupHosting(rest);
+		case "domain": return cmdSetupDomain(rest);
+		case "search":
+			if (!forward("search", rest)) process.exit(1);
+			return;
+		case "ads":
+			if (!forward("ads", rest)) process.exit(1);
+			return;
+		case "all": {
+			const a = parse$1(rest, {
+				dry: {
+					type: "boolean",
+					default: false
+				},
+				check: {
+					type: "boolean",
+					default: false
+				},
+				public: {
+					type: "boolean",
+					default: false
+				},
+				platform: {
+					type: "string",
+					default: "cloudflare"
+				},
+				"no-dev-resources": {
+					type: "boolean",
+					default: false
+				}
+			});
+			const dryCheckFlags = [...a.flag("dry") ? ["--dry"] : [], ...a.flag("check") ? ["--check"] : []];
+			const hostingFlags = [
+				...dryCheckFlags,
+				"--platform",
+				a.str("platform"),
+				...a.flag("no-dev-resources") ? ["--no-dev-resources"] : []
+			];
+			console.log("── repo ──");
+			await cmdSetupRepo([...hostingFlags, ...a.flag("public") ? ["--public"] : []]);
+			console.log("\n── hosting ──");
+			await cmdSetupHosting(hostingFlags);
+			console.log("\n── search ──");
+			const searchOk = forward("search", dryCheckFlags);
+			console.log("\n── ads ──");
+			const adsOk = forward("ads", dryCheckFlags);
+			if (!searchOk || !adsOk) process.exit(1);
+			return;
+		}
+		case void 0:
+		case "-h":
+		case "--help":
+			console.log(SETUP_HELP);
+			return;
+		default: fail(`unknown "setup" subcommand "${sub}" (expected: repo | hosting | domain | search | ads | all). Try: vitops --help`);
+	}
+}
+
 //#endregion
 //#region src/agents.ts
 /**
@@ -2378,7 +2872,7 @@ function lintSource(files, v, format) {
 * `vitops` — CLI for the Vitops design-system generator.
 *
 *   vitops generate  --input <json> --format <bricks|css|tailwind|design[,…]> --out <dir>
-*   vitops init      [--out design-system.json] [--force]
+*   vitops init      [--out design-system.json] [--force] [--site [--name <n>] [--url <u>]]
 *   vitops validate  <design-system.json|site.json>
 *   vitops favicon   --input <svg|png> --out <dir> [--low-res <svg|png>] [--background <hex>]
 *   vitops agents    [--input <json>] [--out AGENTS.md] [--docs-dir <dir>]
@@ -2389,6 +2883,7 @@ function lintSource(files, v, format) {
 *   vitops reviews   [--input <site.json>] [--location <key>] [--dry] [--check] [--out <dir>]
 *   vitops search    setup [--domain <name>] [--dry] [--check]  |  notify [--dry] [--all] [--check]
 *   vitops ads       setup [--provider <name>] [--dry] [--check]  |  tags  |  lint
+*   vitops setup     repo | hosting | domain | search | ads | all [--dry] [--check]
 *   vitops media     [--raw <dir>] [--out <dir>] [--force] [--dry]
 *
 * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
@@ -2464,27 +2959,53 @@ async function cmdGenerate(argv) {
 		fail(msg(err));
 	}
 }
+/**
+* `vitops init` writes a starter `design-system.json`; `--site` writes a starter
+* `site.json` instead — the umbrella `Config` that embeds the design system under
+* `designSystem.themes.default`, since there is no file-level `extends` and a
+* scaffolded config can't merely reference a sibling file (see `defaultSiteConfig`'s
+* docblock in `@getvitops/generator`). `--name`/`--url` fill the two facts a
+* consumer almost certainly has on hand; everything else stays the documented
+* placeholder, edited by hand or via `vitops setup` (see AGENTS.md's "Client
+* onboarding" section).
+*/
 function cmdInit(argv) {
 	const { values } = parseArgs({
 		args: argv,
 		options: {
 			out: {
 				type: "string",
-				short: "o",
-				default: "design-system.json"
+				short: "o"
 			},
 			force: {
 				type: "boolean",
 				default: false
-			}
+			},
+			site: {
+				type: "boolean",
+				default: false
+			},
+			name: { type: "string" },
+			url: { type: "string" }
 		},
 		allowPositionals: false
 	});
-	const out = resolve(values.out);
+	const out = resolve(values.out ?? (values.site ? "site.json" : "design-system.json"));
 	if (existsSync(out) && !values.force) fail(`${out} already exists (use --force to overwrite)`);
+	if (values.site) {
+		const config = defaultSiteConfig({
+			name: values.name,
+			url: values.url
+		});
+		writeFileSync(out, JSON.stringify(config, null, 2) + "\n");
+		console.log(`✓ wrote ${out}`);
+		console.log(`  Edit it, then: vitops validate ${relative(".", out)}`);
+		console.log(`  Editors read the "$schema" (${CONFIG_SCHEMA_LOCAL_PATH}) for autocomplete + validation — the installed copy, so it matches the toolchain you build with.`);
+		return;
+	}
 	writeFileSync(out, JSON.stringify(defaultConfig(), null, 2) + "\n");
 	console.log(`✓ wrote ${out}`);
-	console.log(`  Edit it, then: vitops generate --input ${values.out} --format tailwind --out src/styles`);
+	console.log(`  Edit it, then: vitops generate --input ${relative(".", out)} --format tailwind --out src/styles`);
 	console.log(`  Editors read the "$schema" (${SCHEMA_LOCAL_PATH}) for autocomplete + validation — the installed copy, so it matches the toolchain you build with.`);
 }
 /**
@@ -3315,6 +3836,7 @@ async function main() {
 		case "icons": return cmdIcons(rest);
 		case "search": return cmdSearch(rest);
 		case "ads": return cmdAds(rest);
+		case "setup": return cmdSetup(rest);
 		case "media": return cmdMedia(rest);
 		default: fail(`unknown command "${command}" (expected: ${COMMANDS.join(" | ")}). Try: vitops --help`);
 	}