create-bridgething 0.11.0 → 0.12.1

package/dist/index.mjs

@@ -1,102 +1,53 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, extname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { v7 } from "uuid";
-//#region src/index.ts
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TEMPLATE_DIR = resolve(__dirname, "..", "template");
-const VARIANTS = {
-	app: { summary: "webapp" },
-	launcher: {
-		dir: "template-launcher",
-		manifest: {
-			role: "launcher",
-			description: "A custom home screen."
-		},
-		summary: "launcher (a replacement home screen)"
-	},
-	overlay: {
-		dir: "template-overlay",
-		manifest: {
-			overlay: "overlay.js",
-			description: "A custom system overlay."
-		},
-		scripts: { build: "vite build && vite build -c vite.settings.config.ts && vite build -c vite.overlay.config.ts" },
-		summary: "overlay (system UI drawn over every webapp)"
+import { createInterface } from "node:readline/promises";
+//#region src/prompt.ts
+var Interactive = class {
+	rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	async ask(question, fallback) {
+		return (await this.rl.question(`${question}${fallback ? ` (${fallback})` : ""}: `)).trim() || fallback;
+	}
+	async confirm(question) {
+		return /^y(es)?$/i.test((await this.rl.question(`${question} (y/N): `)).trim());
+	}
+	close() {
+		this.rl.close();
 	}
 };
-function parseArgs(argv) {
-	const positional = [];
-	let install = true;
-	let git = true;
-	let variant = "app";
-	for (const arg of argv) if (arg === "--no-install") install = false;
-	else if (arg === "--no-git") git = false;
-	else if (arg === "--launcher") variant = "launcher";
-	else if (arg === "--overlay") variant = "overlay";
-	else if (arg === "--help" || arg === "-h") {
-		printHelp();
-		process.exit(0);
-	} else if (arg.startsWith("-")) {
-		console.error(`unknown flag: ${arg}`);
-		printHelp();
-		process.exit(1);
-	} else positional.push(arg);
-	if (positional.length !== 1) {
-		printHelp();
-		process.exit(1);
+var Silent = class {
+	async ask(_question, fallback) {
+		return fallback;
 	}
-	return {
-		target: positional[0],
-		install,
-		git,
-		variant
-	};
-}
-function printHelp() {
-	console.log(`Usage: create-bridgething <target-dir> [--launcher | --overlay] [--no-install] [--no-git]
-
-Scaffold a new bridgething webapp at <target-dir>.
-
-Variants:
-  (default)     A normal webapp.
-  --launcher    A home screen. Declares 'role: launcher' and can take the
-                device's launcher slot, replacing the built-in hub.
-  --overlay     A system overlay. Ships an 'overlay.js' the daemon injects
-                into every webapp, replacing the built-in one.
-
-Options:
-  --no-install  Skip 'bun install' after copying.
-  --no-git      Skip 'git init' after copying.
-`);
+	async confirm() {
+		return false;
+	}
+	close() {}
+};
+function asker(interactive) {
+	return interactive && process.stdin.isTTY ? new Interactive() : new Silent();
 }
-function patchJson(path, patch) {
-	const parsed = JSON.parse(readFileSync(path, "utf8"));
-	writeFileSync(path, `${JSON.stringify({
-		...parsed,
-		...patch
-	}, null, 2)}\n`);
+function slugify(value) {
+	return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app";
 }
-function applyVariant(target, variant, subs) {
-	const spec = VARIANTS[variant];
-	if (spec.dir) copyTemplate(resolve(__dirname, "..", spec.dir), target, subs);
-	const appendPath = join(target, "_claude_append.md");
-	if (existsSync(appendPath)) {
-		const claudePath = join(target, "CLAUDE.md");
-		writeFileSync(claudePath, readFileSync(claudePath, "utf8") + readFileSync(appendPath, "utf8"));
-		rmSync(appendPath);
-	}
-	if (spec.manifest) patchJson(join(target, "public", "manifest.json"), spec.manifest);
-	if (spec.scripts) {
-		const pkgPath = join(target, "package.json");
-		patchJson(pkgPath, { scripts: {
-			...JSON.parse(readFileSync(pkgPath, "utf8")).scripts,
-			...spec.scripts
-		} });
-	}
+function isSlug(value) {
+	return /^[a-z0-9][a-z0-9-]*$/.test(value);
 }
+//#endregion
+//#region src/template.ts
+const RENAMES = {
+	_gitignore: ".gitignore",
+	_claude: ".claude",
+	_github: ".github",
+	_bunversion: ".bun-version",
+	"_prettierrc.js": ".prettierrc.js"
+};
 const BINARY_EXT = new Set([
 	".ttf",
 	".otf",
@@ -111,15 +62,17 @@ const BINARY_EXT = new Set([
 	".ico",
 	".wasm"
 ]);
+function substitute(raw, subs) {
+	return raw.replace(/__[A-Z0-9_]+__/g, (token) => subs[token] ?? token);
+}
 function copyTemplate(src, dest, subs) {
+	mkdirSync(dest, { recursive: true });
 	for (const entry of readdirSync(src)) {
 		const srcPath = join(src, entry);
-		const destPath = join(dest, entry === "_gitignore" ? ".gitignore" : entry === "_claude" ? ".claude" : entry);
-		if (statSync(srcPath).isDirectory()) {
-			mkdirSync(destPath, { recursive: true });
-			copyTemplate(srcPath, destPath, subs);
-		} else if (BINARY_EXT.has(extname(entry).toLowerCase())) copyFileSync(srcPath, destPath);
-		else writeFileSync(destPath, readFileSync(srcPath, "utf8").replace(/__PROJECT_NAME__/g, subs.projectName).replace(/__WEBAPP_UUID__/g, subs.webappUuid));
+		const destPath = join(dest, RENAMES[entry] ?? entry);
+		if (statSync(srcPath).isDirectory()) copyTemplate(srcPath, destPath, subs);
+		else if (BINARY_EXT.has(extname(entry).toLowerCase())) copyFileSync(srcPath, destPath);
+		else writeFileSync(destPath, substitute(readFileSync(srcPath, "utf8"), subs));
 	}
 }
 function copyDir(src, dest) {
@@ -131,18 +84,163 @@ function copyDir(src, dest) {
 		else copyFileSync(srcPath, destPath);
 	}
 }
-function linkAgentAliases(target) {
+function move(from, to) {
+	if (!existsSync(from)) return;
+	rmSync(to, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(join(to, ".."), { recursive: true });
+	copyDir(from, to);
+	rmSync(from, {
+		recursive: true,
+		force: true
+	});
+}
+function linkOrCopy(target, linkPath, realPath) {
+	rmSync(linkPath, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(join(linkPath, ".."), { recursive: true });
 	try {
-		symlinkSync("CLAUDE.md", join(target, "AGENTS.md"));
+		symlinkSync(target, linkPath, "dir");
 	} catch {
-		copyFileSync(join(target, "CLAUDE.md"), join(target, "AGENTS.md"));
+		copyDir(realPath, linkPath);
 	}
-	mkdirSync(join(target, ".agents"), { recursive: true });
-	try {
-		symlinkSync(join("..", ".claude", "skills"), join(target, ".agents", "skills"), "dir");
-	} catch {
-		copyDir(join(target, ".claude", "skills"), join(target, ".agents", "skills"));
+}
+function readJson(path) {
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+function writeJson(path, value) {
+	mkdirSync(join(path, ".."), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+function patchJson(path, patch) {
+	writeJson(path, {
+		...readJson(path),
+		...patch
+	});
+}
+function sortKeys(record) {
+	const entries = Object.entries(record).sort(([a], [b]) => a.localeCompare(b));
+	return entries.length ? Object.fromEntries(entries) : void 0;
+}
+//#endregion
+//#region src/index.ts
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const TEMPLATE_DIR = join(PACKAGE_ROOT, "template");
+const SOURCE_TEMPLATE_DIR = join(PACKAGE_ROOT, "template-source");
+const SKILL_IN_APP = join(".claude", "skills", "bridgething");
+const SDK_VERSIONS = readJson(join(PACKAGE_ROOT, "template-versions.json"));
+const EXTENSION = {
+	dir: "template-extension",
+	manifest: {
+		extension: {
+			entry: "extension/desktop.mjs",
+			permissions: ["all"],
+			api: 1
+		},
+		config: [{
+			type: "string",
+			data: {
+				key: "greeting",
+				label: "Greeting the extension sends on connect"
+			}
+		}]
+	},
+	dependencies: { "@bridgething/extension": SDK_VERSIONS["@bridgething/extension"] },
+	devDependencies: {
+		deno: "2.9.6",
+		esbuild: "^0.28.2"
+	},
+	summary: "native extension (a desktop-side Deno process)"
+};
+const VARIANTS = {
+	app: { summary: "webapp" },
+	launcher: {
+		dir: "template-launcher",
+		manifest: {
+			role: "launcher",
+			description: "A custom home screen."
+		},
+		summary: "launcher (a replacement home screen)"
+	},
+	overlay: {
+		dir: "template-overlay",
+		manifest: {
+			overlay: "overlay.js",
+			description: "A custom system overlay."
+		},
+		scripts: { build: "vite build && vite build -c vite.settings.config.ts && vite build -c vite.overlay.config.ts" },
+		summary: "overlay (system UI drawn over every webapp)"
+	}
+};
+function parseArgs(argv) {
+	const args = {
+		target: null,
+		install: true,
+		git: true,
+		interactive: true,
+		variant: "app",
+		extension: false,
+		sourceName: null,
+		sourceDescription: null,
+		repo: null
+	};
+	const value = (at, flag) => argv[at] ?? die(`${flag} needs a value`);
+	for (let at = 0; at < argv.length; at++) {
+		const arg = argv[at];
+		if (arg === "--no-install") args.install = false;
+		else if (arg === "--no-git") args.git = false;
+		else if (arg === "--yes" || arg === "-y") args.interactive = false;
+		else if (arg === "--launcher") args.variant = "launcher";
+		else if (arg === "--overlay") args.variant = "overlay";
+		else if (arg === "--extension") args.extension = true;
+		else if (arg === "--source-name") args.sourceName = value(++at, "--source-name");
+		else if (arg === "--source-description") args.sourceDescription = value(++at, "--source-description");
+		else if (arg === "--repo") args.repo = value(++at, "--repo");
+		else if (arg === "--help" || arg === "-h") {
+			printHelp();
+			process.exit(0);
+		} else if (arg.startsWith("-")) die(`unknown flag: ${arg}`);
+		else if (args.target) die("name one target");
+		else args.target = arg;
 	}
+	return args;
+}
+function printHelp() {
+	console.log(`Usage: create-bridgething [target] [options]
+
+scaffold a bridgething app at [target].
+
+Variants:
+  (default)     a normal webapp
+  --launcher    a home screen that can take the device's launcher slot, replacing the built-in hub
+  --overlay     A system overlay that can be injected into every webapp, replacing the built-in one
+
+Add-ons:
+  --extension   A native extension with a Deno process the desktop app runs alongside the webapp
+
+Options:
+  --source-name <name>         name the source (app store repo) instead of asking
+  --source-description <text>  describe the source instead of asking
+  --repo <owner/repo>          the github repo this source publishes from
+  -y, --yes                    take every default
+  --no-install                 skip 'bun install'
+  --no-git                     skip 'git init'
+`);
+}
+function die(message) {
+	console.error(`error: ${message}`);
+	process.exit(1);
+}
+function capture(cmd, args, cwd = process.cwd()) {
+	const result = spawnSync(cmd, args, {
+		encoding: "utf8",
+		cwd
+	});
+	return result.status === 0 ? result.stdout.trim() : null;
 }
 function run(cmd, args, cwd) {
 	return spawnSync(cmd, args, {
@@ -150,59 +248,295 @@ function run(cmd, args, cwd) {
 		stdio: "inherit"
 	}).status === 0;
 }
-function main() {
-	const args = parseArgs(process.argv.slice(2));
-	const target = resolve(process.cwd(), args.target);
-	const projectName = args.target.replace(/^.*[\\/]/, "");
-	if (existsSync(target)) {
-		if (readdirSync(target).length > 0) {
-			console.error(`error: ${target} exists and is not empty`);
-			process.exit(1);
+function findSourceRoot(from) {
+	let dir = resolve(from);
+	for (;;) {
+		if (existsSync(join(dir, "source.json")) && existsSync(join(dir, "apps"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+function repoFromRemote(cwd) {
+	const remote = capture("git", [
+		"remote",
+		"get-url",
+		"origin"
+	], cwd);
+	const match = remote ? /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/.exec(remote) : null;
+	return match ? `${match[1]}/${match[2]}` : null;
+}
+function sourceHomepage(root) {
+	const homepage = readJson(join(root, "source.json")).homepage ?? null;
+	return homepage && /^https:\/\/github\.com\/[^/]+\/[^/]+\/?$/.test(homepage) ? homepage.replace(/\/$/, "") : null;
+}
+function githubLogin() {
+	return capture("gh", [
+		"api",
+		"user",
+		"-q",
+		".login"
+	]) ?? capture("git", ["config", "github.user"]);
+}
+function splitRepo(repo) {
+	const match = /^([A-Za-z0-9][A-Za-z0-9-]*)\/([A-Za-z0-9._-]+)$/.exec(repo.replace(/\.git$/, ""));
+	if (!match) die(`"${repo}" is not owner/repo`);
+	return {
+		owner: match[1],
+		name: match[2]
+	};
+}
+function repoSubs(repo) {
+	return {
+		__REPO_OWNER__: repo.owner,
+		__REPO_OWNER_LOWER__: repo.owner.toLowerCase(),
+		__REPO_NAME__: repo.name,
+		__BASE_URL__: `https://${repo.owner.toLowerCase()}.github.io/${repo.name}`
+	};
+}
+function patchPackage(dir, patch) {
+	const path = join(dir, "package.json");
+	const pkg = readJson(path);
+	patchJson(path, {
+		scripts: {
+			...pkg.scripts,
+			...patch.scripts
+		},
+		dependencies: sortKeys({
+			...pkg.dependencies,
+			...patch.dependencies
+		}),
+		devDependencies: sortKeys({
+			...pkg.devDependencies,
+			...patch.devDependencies
+		})
+	});
+}
+function overlayTemplate(target, dir, subs) {
+	copyTemplate(join(PACKAGE_ROOT, dir), target, subs);
+	const appendPath = join(target, "_claude_append.md");
+	if (!existsSync(appendPath)) return;
+	const claudePath = join(target, "CLAUDE.md");
+	const addition = readFileSync(appendPath, "utf8");
+	const existing = existsSync(claudePath) ? `${readFileSync(claudePath, "utf8").trimEnd()}\n\n` : "";
+	writeFileSync(claudePath, `${existing}${existing ? addition : addition.replace(/^## /, "# ")}`);
+	rmSync(appendPath, { force: true });
+}
+function scaffoldApp(root, spec) {
+	const dir = join(root, "apps", spec.slug);
+	if (existsSync(dir) && readdirSync(dir).length) die(`apps/${spec.slug} already exists`);
+	const uuid = v7();
+	const subs = {
+		__PROJECT_NAME__: spec.slug,
+		__WEBAPP_UUID__: uuid,
+		__APP_SLUG__: spec.slug
+	};
+	copyTemplate(TEMPLATE_DIR, dir, subs);
+	patchPackage(dir, { dependencies: { "@bridgething/client": SDK_VERSIONS["@bridgething/client"] } });
+	const variant = VARIANTS[spec.variant];
+	if (variant.dir) overlayTemplate(dir, variant.dir, subs);
+	if (variant.manifest) patchJson(join(dir, "public", "manifest.json"), variant.manifest);
+	if (variant.scripts) patchPackage(dir, { scripts: variant.scripts });
+	if (spec.extension) {
+		overlayTemplate(dir, EXTENSION.dir, subs);
+		patchJson(join(dir, "public", "manifest.json"), EXTENSION.manifest);
+		patchPackage(dir, {
+			dependencies: EXTENSION.dependencies,
+			devDependencies: EXTENSION.devDependencies
+		});
+	}
+	const tsconfigPath = join(dir, "tsconfig.json");
+	patchJson(tsconfigPath, { include: readJson(tsconfigPath).include.filter((entry) => existsSync(join(dir, entry))) });
+	writeJson(join(dir, "catalog.json"), {
+		author: spec.author,
+		homepage: spec.repoUrl,
+		source: spec.repoUrl,
+		icon: null,
+		screenshots: [],
+		min_libbridgething_version: SDK_VERSIONS.libbridgething
+	});
+	const manifest = readJson(join(dir, "public", "manifest.json"));
+	writeFileSync(join(dir, "CHANGELOG.md"), `# ${manifest.name}\n\n## ${manifest.version}\n\nFirst release.\n`);
+	return {
+		dir,
+		uuid,
+		shape: spec.extension ? `${variant.summary} + ${EXTENSION.summary}` : variant.summary
+	};
+}
+function linkAgentGuides(root, appDir) {
+	const rootSkill = join(root, SKILL_IN_APP);
+	const appSkill = join(appDir, SKILL_IN_APP);
+	if (!existsSync(rootSkill)) move(appSkill, rootSkill);
+	linkOrCopy(relative(dirname(appSkill), rootSkill), appSkill, rootSkill);
+	for (const link of [join(root, "AGENTS.md"), join(appDir, "AGENTS.md")]) {
+		if (existsSync(link) || !existsSync(join(dirname(link), "CLAUDE.md"))) continue;
+		try {
+			symlinkSync("CLAUDE.md", link);
+		} catch {
+			writeFileSync(link, readFileSync(join(dirname(link), "CLAUDE.md"), "utf8"));
 		}
-	} else mkdirSync(target, { recursive: true });
-	const webappUuid = v7();
+	}
+	for (const dir of [root, appDir]) {
+		mkdirSync(join(dir, ".agents"), { recursive: true });
+		linkOrCopy(join("..", ".claude", "skills"), join(dir, ".agents", "skills"), join(dir, ".claude", "skills"));
+	}
+}
+async function askSourceDetails(ask, args) {
+	const named = args.target && !isSlug(args.target) ? basename(resolve(args.target)) : args.target;
+	const name = args.sourceName ?? await ask.ask("Source name", named || "My Car Thing Apps");
+	const description = args.sourceDescription ?? await ask.ask("Source description", `Webapps by ${name}.`);
+	const suggested = `${githubLogin() ?? "your-github-username"}/${slugify(name)}`;
+	const repo = splitRepo(args.repo ?? await ask.ask("GitHub repo", suggested));
+	let app = args.target && isSlug(args.target) ? args.target : "";
+	while (!app) {
+		const answer = slugify(await ask.ask("First app", named ? slugify(named) : "weather"));
+		if (isSlug(answer)) app = answer;
+	}
+	return {
+		name,
+		description,
+		repo,
+		app
+	};
+}
+async function createSource(args) {
+	const ask = asker(args.interactive);
+	let details;
+	try {
+		details = await askSourceDetails(ask, args);
+		if (details.repo.owner === "your-github-username") die("pass --repo <owner/repo>, or answer the GitHub repo prompt; the catalog url is derived from it");
+	} finally {
+		ask.close();
+	}
+	const target = resolve(process.cwd(), args.target && !isSlug(args.target) ? args.target : details.repo.name);
+	if (existsSync(target) && readdirSync(target).length) die(`${target} exists and is not empty`);
 	const subs = {
-		projectName,
-		webappUuid
+		...repoSubs(details.repo),
+		__SOURCE_NAME__: details.name,
+		__SOURCE_DESCRIPTION__: details.description,
+		__APP_SLUG__: details.app
 	};
-	console.log(`scaffolding ${projectName} (${webappUuid}) in ${target}`);
-	copyTemplate(TEMPLATE_DIR, target, subs);
-	applyVariant(target, args.variant, subs);
-	console.log(`  ✓ template copied (${VARIANTS[args.variant].summary})`);
-	linkAgentAliases(target);
-	console.log("  ✓ agent guides linked (CLAUDE.md, AGENTS.md, /bridgething skill)");
-	if (args.git) if (run("git", ["init", "--quiet"], target)) console.log("  ✓ git initialized");
-	else console.warn("  ! git init failed (skipping)");
+	console.log(`\nscaffolding ${details.name} in ${target}`);
+	copyTemplate(SOURCE_TEMPLATE_DIR, target, subs);
+	patchPackage(target, { devDependencies: { "@bridgething/source": SDK_VERSIONS["@bridgething/source"] } });
+	const repoUrl = `https://github.com/${details.repo.owner}/${details.repo.name}`;
+	const app = scaffoldApp(target, {
+		slug: details.app,
+		variant: args.variant,
+		extension: args.extension,
+		author: capture("git", ["config", "user.name"]) ?? details.repo.owner,
+		repoUrl
+	});
+	linkAgentGuides(target, app.dir);
+	console.log(`  ✓ source and apps/${details.app} (${app.uuid}) created as a ${app.shape}`);
+	if (args.git && run("git", ["init", "--quiet"], target)) console.log("  ✓ git initialized");
 	if (args.install) {
 		console.log("  installing dependencies with bun...");
 		if (!run("bun", ["install"], target)) console.warn("  ! bun install failed; install manually with `bun install`");
 		else console.log("  ✓ dependencies installed");
 	}
+	await offerRepoCreate(args, target, details.repo, details.description);
+	printSourceNextSteps(target, details, repoUrl);
+}
+async function offerRepoCreate(args, target, repo, description) {
+	if (!args.interactive || !args.git || !capture("gh", ["auth", "status"])) return;
+	const ask = asker(true);
+	try {
+		if (!await ask.confirm(`\nCreate github.com/${repo.owner}/${repo.name} and push now?`)) return;
+	} finally {
+		ask.close();
+	}
+	run("git", ["add", "--all"], target);
+	run("git", [
+		"commit",
+		"--quiet",
+		"-m",
+		"scaffold the app source"
+	], target);
+	const created = run("gh", [
+		"repo",
+		"create",
+		`${repo.owner}/${repo.name}`,
+		"--public",
+		"--source",
+		".",
+		"--push",
+		"-d",
+		description
+	], target);
+	console.log(created ? "  ✓ repo created and pushed" : "  ! gh repo create failed; push it yourself");
+}
+function printSourceNextSteps(target, details, repoUrl) {
+	const base = `https://${details.repo.owner.toLowerCase()}.github.io/${details.repo.name}`;
 	console.log(`
-Done! Next steps:
+Done. ${target}
+
+  cd ${basename(target)}
+  bun run dev          # local dev server against the connected Car Thing
+  bun run dev:device   # dev server on the Car Thing's own screen
+  bun run check        # check that your app and source is valid
 
-  cd ${args.target}
-${args.install ? "" : "  bun install\n"}  bun run dev          # local dev server (http://localhost:5173/)
+Fill in the description in apps/${details.app}/public/manifest.json.
 
-Open this folder with your coding agent (Claude Code, Codex, opencode, ...).
-It reads CLAUDE.md / AGENTS.md and the /bridgething skill in .claude/skills
-(mirrored at .agents/skills), which goes deep on the client API, running and
-driving the app, and installing and sharing it.
+Push to ${repoUrl}, then in Settings > Pages set the branch to gh-pages, folder / (root).
+Your catalog ends up at at ${base}/catalog.v1.json, which you can submit to the bridgething store.
 
-  bun run build        # production bundle into dist/
-  bun run push <addr>  # build + install onto a connected Car Thing (default bridgething.local)
-  bun run share        # build first, then zip dist/ to hand to friends
-  bun run update       # bring the connected Car Thing to the latest bridgething release
-${args.variant === "app" ? "" : `
-'bun run push' also claims the device's ${args.variant} slot, so this is live the
-moment it lands. 'bun run push --release' hands the slot back to the built-in
-${args.variant === "launcher" ? "hub" : "overlay"}, which is how you recover if a build of this wedges the screen.
-The companion phone app can do the same thing.
-`}
-The starter App connects to ws://127.0.0.1:8891/ on the device, and to
-ws://<device-ip>:8891/ in dev when you set VITE_BRIDGETHING_URL.
+  bun run new <slug>   add another app to this source
+  bun run bump ${details.app} [version]
 `);
 }
-main();
+async function addApp(root, args) {
+	const ask = asker(args.interactive);
+	let slug = args.target ?? "";
+	try {
+		while (!isSlug(slug)) {
+			if (slug) console.error(`"${slug}" is not a usable slug; use lowercase letters, digits and dashes`);
+			slug = slugify(await ask.ask("App slug", "weather"));
+			if (!args.interactive) break;
+		}
+	} finally {
+		ask.close();
+	}
+	if (!isSlug(slug)) die("name the app: create-bridgething <slug>");
+	const repo = repoFromRemote(root);
+	const repoUrl = repo ? `https://github.com/${repo}` : sourceHomepage(root);
+	if (args.extension && !repoUrl) console.warn("warning: this source has no github origin, so catalog.json \"source\" is null. An app that ships an\n         extension must have its repo url before it can be published.");
+	const app = scaffoldApp(root, {
+		slug,
+		variant: args.variant,
+		extension: args.extension,
+		author: capture("git", ["config", "user.name"], root) ?? "Your Name",
+		repoUrl
+	});
+	linkAgentGuides(root, app.dir);
+	console.log(`apps/${slug} (${app.uuid}) created as a ${app.shape}`);
+	if (args.install && !run("bun", ["install"], root)) console.warn("! bun install failed. install manually with `bun install`");
+	console.log(`
+Next:
+
+  fill in the description in apps/${slug}/public/manifest.json, and check the author
+  and repo url in apps/${slug}/catalog.json
+
+  bun run dev ${slug}      develop against a connected Car Thing
+  bun run check            ensure your app and source are valid
+  bun run bump ${slug} patch
+
+Push to main and the publish workflow puts it in your catalog.`);
+}
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const root = findSourceRoot(process.cwd());
+	if (root) await addApp(root, args);
+	else await createSource(args);
+}
+try {
+	await main();
+} catch (err) {
+	if (err.name === "AbortError") {
+		console.log("\ncancelled; nothing was written.");
+		process.exit(130);
+	}
+	throw err;
+}
 //#endregion
 export {};