@solidrt/cli 0.0.51 → 0.0.52

package/src/{commands/bundle.ts → bundle/main.ts}

@@ -1,15 +1,18 @@
-import { values, source, isPrebuilt } from "../args"
+import { values, source, isPrebuilt } from "../lib/args"
 import {
   bundleFlux,
-  bundleIsolatesDir,
   bundleSolid,
+  bundleWith,
   compileToBytecode,
   findFluxIsolates,
+  isolateManifestAssets,
   readPrebuiltIsolates,
   walkFiles,
   writeIsolates,
-} from "../bundler"
-import { projectDirFor } from "../project"
+} from "./bundler"
+import { resolveMode } from "../lib/mode"
+import { buildManifest } from "../lib/project"
+import type { BundleOutput } from "../types/bundle"
 import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs"
 import { basename, dirname, join, resolve } from "node:path"
 
@@ -23,12 +26,13 @@ function writeStdout(data: string): Promise<void> {
 }
 
 // The bundle output dir (okf/backlog/build-output-dirs.md): the bundle flow's
-// subdir of the build root, or an explicit --output dir. Only reused when it
-// is empty or already a bundle output (a *.srt.* or *.flux.* bundle at top
-// level) - the writePackFolder rule - so it never writes into an unrelated
-// directory.
-function ensureOutDir(entry: string): string {
-  let outDir = values.output ?? join(projectDirFor(entry), "dist", "bundle")
+// subdir of the build root, or an explicit --output dir. The build root is
+// the cwd: a project command runs in its root (mode.ts), and a file on its
+// own builds where it is run from. Only reused when it is empty or already a
+// bundle output (a *.srt.* or *.flux.* bundle at top level) - the
+// writePackFolder rule - so it never writes into an unrelated directory.
+function ensureOutDir(defaultDir = join("dist", "bundle")): string {
+  let outDir = values.output ?? defaultDir
   let existing = existsSync(outDir) ? readdirSync(outDir) : null
   if (existing && existing.length > 0 && !existing.some((name) => /\.(srt|flux)\.(js|bin)$/.test(name))) {
     console.error(`${resolve(outDir)} exists and is not a bundle output; choose another --output`)
@@ -64,7 +68,7 @@ async function writeBytecode(jsCode: string, outfile: string) {
   console.log(`>> wrote ${binSize} bytes to ${outfile}`)
 }
 
-export async function runBundleCommand() {
+export async function main() {
   if (values.flux) {
     let entry = resolve(source!)
     let name = basename(entry).replace(/\.[jt]s$/, "")
@@ -83,7 +87,7 @@ export async function runBundleCommand() {
       await writeStdout(jsCode)
       process.exit()
     }
-    let outDir = ensureOutDir(entry)
+    let outDir = ensureOutDir()
     if (values.compile) {
       await writeBytecode(jsCode, join(outDir, name + ".flux.bin"))
     } else {
@@ -110,27 +114,65 @@ export async function runBundleCommand() {
     process.exit()
   }
 
+  // --json: the dev server's rebuild (server/rebuild.ts spawns it in the
+  // project root or the entry's directory with the entry and --project or
+  // --file, so the mode resolves the same). One BundleOutput object on
+  // stdout (types/bundle.d.ts), diagnostics on stderr, exit 1 with an empty
+  // stdout on a build failure. A prebuilt .srt.js is read as-is with its
+  // sibling isolate bundles.
+  if (values.json) {
+    let mode = resolveMode()
+    let result: BundleOutput | null
+    if (mode.entry.endsWith(".srt.js")) {
+      let code = await Bun.file(mode.entry).text()
+      let isolates = readPrebuiltIsolates(mode.entry).map((i) => ({ ...i, map: null }))
+      result = {
+        code,
+        map: null,
+        manifest: buildManifest(code, mode.entry, isolateManifestAssets(isolates), mode.projectDir),
+        isolates,
+        inputs: [mode.entry],
+      }
+    } else {
+      result = await bundleWith({
+        entry: mode.entry,
+        project: mode.projectDir,
+        dev: values.dev,
+        minify: values.minify,
+      })
+    }
+    if (!result) process.exit(1)
+    await writeStdout(JSON.stringify(result))
+    process.exit()
+  }
+
+  // A prebuilt .srt.js (validateArgs admits no other prebuilt form) is
+  // compiled to bytecode: the only step left, so --compile is implied. The
+  // output lands in the bundle's own dir unless --output says otherwise; its
+  // isolate bundles compile along into the output's isolates/ (the ids match,
+  // the extension picks the form).
   if (isPrebuilt) {
-    if (!source!.endsWith(".srt.js")) {
-      console.error("Can only compile .srt.js files. .srt.bin is already compiled.")
+    let jsFile = resolve(source!)
+    if (!existsSync(jsFile)) {
+      console.error(`Entry not found: ${source}`)
       process.exit(1)
     }
-    let jsFile = resolve(source!)
-    let binOut = jsFile.replace(/\.srt\.js$/, ".srt.bin").replace(/\.js$/, ".bin")
-    await writeBytecode(await Bun.file(jsFile).text(), binOut)
-    // The isolate bundles compile along, .bin beside .js in the output's
-    // isolates/ dir (the ids match, the extension picks the form).
+    let outDir = ensureOutDir(dirname(jsFile))
+    await writeBytecode(await Bun.file(jsFile).text(), join(outDir, basename(jsFile).replace(/\.js$/, ".bin")))
+    let isolatesDir = join(outDir, "isolates")
+    clearIsolates(isolatesDir, ".bin")
     for (let isolate of readPrebuiltIsolates(jsFile)) {
-      await writeIsolateBytecode(bundleIsolatesDir(jsFile), isolate)
+      await writeIsolateBytecode(isolatesDir, isolate)
     }
     process.exit()
   }
 
-  let entry = resolve(source!)
+  let mode = resolveMode()
+  let entry = mode.entry
   let name = basename(entry).replace(/\.[jt]sx?$/, "")
 
   if (values.stdout) {
-    let result = await bundleSolid()
+    let result = await bundleSolid(mode)
     if (result.isolates.length) {
       console.error("[cli] Warning: this app has isolate modules; --stdout carries only the main bundle")
     }
@@ -138,11 +180,11 @@ export async function runBundleCommand() {
     process.exit()
   }
 
-  let outDir = ensureOutDir(entry)
+  let outDir = ensureOutDir()
   let isolatesDir = join(outDir, "isolates")
 
   if (values.compile) {
-    let result = await bundleSolid()
+    let result = await bundleSolid(mode)
     await writeBytecode(result.code, join(outDir, name + ".srt.bin"))
     clearIsolates(isolatesDir, ".bin")
     for (let isolate of result.isolates) {
@@ -151,7 +193,7 @@ export async function runBundleCommand() {
     process.exit()
   }
 
-  let result = await bundleSolid()
+  let result = await bundleSolid(mode)
   let jsOutfile = join(outDir, name + ".srt.js")
   await Bun.write(jsOutfile, result.code)
   clearIsolates(isolatesDir, ".js")

package/src/check/docs.md

@@ -0,0 +1,10 @@
+# srt check
+
+{{ usage check }}
+
+The gate worth wiring into CI: it builds and typechecks the app without
+producing build output. With a folder it covers every entry under it
+(`src/index.tsx`, `examples/*`, and in a monorepo every example app,
+package example and package demo), so one call at the repo root answers
+"did I break any example" before pushing. The dev server runs the same check once at
+startup, without gating on it.

package/src/check/main.ts

@@ -0,0 +1,85 @@
+import { existsSync, statSync } from "node:fs"
+import { Glob } from "bun"
+import { join, resolve } from "node:path"
+import { source } from "../lib/args"
+import { bundleWith } from "../bundle/bundler"
+import { findProject } from "../lib/project"
+import { findProjectRoot, reportTypes, typecheck } from "./typecheck"
+
+// srt check: verify the app without side effects. Bundles in memory (nothing
+// written, so no dev-server reload fires and no build outputs land in the
+// project) and typechecks with the project's own tsc (typecheck.ts).
+
+// Check one entry: bundle in memory, then typecheck. Returns whether it passed.
+async function checkEntry(entry: string): Promise<boolean> {
+  let failed = false
+  // check verifies trees of entries from one cwd, so it is the one command
+  // that walks up from each entry to its project.
+  let result = await bundleWith({ entry, dev: true, minify: false, project: findProject(entry)?.dir ?? null })
+  if (!result) {
+    // bundleWith already printed the compile errors.
+    failed = true
+  }
+  let root = findProjectRoot(entry)
+  if (!root) {
+    console.warn("Typecheck skipped: no tsconfig.json or package.json above the entry")
+  } else {
+    let types = await typecheck(root, entry)
+    if (types && reportTypes(types)) failed = true
+  }
+  return !failed
+}
+
+// The entries `srt check <folder>` covers, relative to the folder (a bare
+// `srt check` is `srt check .`): the app itself, its own examples, and in
+// a monorepo every example app, package example and package demo. The same
+// set CI gates, so one call at the repo root answers "did I break any
+// example" before pushing. Entries, not files: a source no entry imports is
+// not checked.
+const CHECK_ALL_GLOBS = [
+  "src/index.tsx",
+  "examples/*.tsx",
+  "examples/*/src/index.tsx",
+  "packages/*/examples/*.tsx",
+  "packages/*/demos/src/*.tsx",
+]
+function discoverEntries(root: string): string[] {
+  let entries: string[] = []
+  for (let pattern of CHECK_ALL_GLOBS) {
+    entries.push(...[...new Glob(pattern).scanSync({ cwd: root })].map((e) => join(root, e)))
+  }
+  return entries.sort()
+}
+
+export async function main() {
+  let target = source ?? "."
+  if (!existsSync(target)) {
+    // Without this, the missing file surfaces later as an internal ENOENT
+    // stack trace (scandir/Bun.build), which reads as a CLI bug - the common
+    // cause is just running from the wrong directory.
+    console.error(`No such entry: ${target} (resolved from ${process.cwd()})`)
+    process.exit(1)
+  }
+  if (!statSync(target).isDirectory()) {
+    if (!(await checkEntry(target))) process.exit(1)
+    console.log("Check passed")
+    process.exit(0)
+  }
+
+  let entries = discoverEntries(target)
+  if (entries.length === 0) {
+    console.error(`No entries found under ${resolve(target)} (looked for ${CHECK_ALL_GLOBS.join(", ")})`)
+    process.exit(1)
+  }
+  let failures: string[] = []
+  for (let entry of entries) {
+    console.log(`== ${entry}`)
+    if (!(await checkEntry(entry))) failures.push(entry)
+  }
+  if (failures.length > 0) {
+    console.error(`${failures.length} of ${entries.length} entries failed:\n  ${failures.join("\n  ")}`)
+    process.exit(1)
+  }
+  console.log(`Check passed (${entries.length} entries)`)
+  process.exit(0)
+}

package/src/{commands/check.ts → check/typecheck.ts}

@@ -1,14 +1,12 @@
 import { existsSync, mkdirSync, rmSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
-import { source } from "../args"
-import { bundleWith, findIsolateModules } from "../bundler"
+import { findIsolateModules } from "../bundle/bundler"
 
-// srt check: verify the app without side effects. Bundles in memory (nothing
-// written, so no dev-server reload fires and no build outputs land in the
-// project) and typechecks with the project's own tsc, reporting only
-// diagnostics in app code. @solidrt packages ship raw .ts sources, so a strict
-// consumer config surfaces their internal errors too; those are counted and
-// hidden, not the caller's problem to wade through.
+// Typechecking an app entry with the project's own tsc, reporting only
+// diagnostics in app code. Used by `srt check` (the hard gate) and by the dev
+// server's startup check (it spawns `srt check <entry>`). @solidrt packages ship
+// raw .ts sources, so a strict consumer config surfaces their internal errors
+// too; those are counted and hidden, not the caller's problem to wade through.
 
 // Walk up from the entry to the enclosing project (tsconfig.json or, failing
 // that, package.json).
@@ -27,7 +25,7 @@ export function findProjectRoot(entry: string): string | null {
 
 // One tsc --pretty false diagnostic: the "path(line,col): error TS...: ..."
 // head line plus any indented continuation lines.
-type Diagnostic = { head: string; lines: string[]; inDependencies: boolean }
+export type Diagnostic = { head: string; lines: string[]; inDependencies: boolean }
 
 function parseDiagnostics(output: string): Diagnostic[] {
   let diagnostics: Diagnostic[] = []
@@ -58,6 +56,8 @@ function findTsc(fromDir: string): string | null {
   }
 }
 
+export type TypecheckResult = { app: Diagnostic[]; hidden: number }
+
 // Typecheck the entry's program, not the enclosing project: a transient
 // config extends the project's tsconfig and roots the program at the entry
 // alone (plus the project's ambient declarations), so tsc checks exactly the
@@ -65,7 +65,7 @@ function findTsc(fromDir: string): string | null {
 // config lives in the project-local .srt-data (the dev-artifact dir; absolute
 // paths inside, so its location only matters for type-package resolution,
 // which walks up to the project's node_modules from there).
-export async function typecheck(root: string, entry: string): Promise<{ app: Diagnostic[]; hidden: number } | null> {
+export async function typecheck(root: string, entry: string): Promise<TypecheckResult | null> {
   let tsconfig = join(root, "tsconfig.json")
   if (!existsSync(tsconfig)) {
     console.warn("Typecheck skipped: no tsconfig.json above the entry")
@@ -111,7 +111,7 @@ export async function typecheck(root: string, entry: string): Promise<{ app: Dia
 // whether app-code errors were found. Callers pass repl-aware printers when
 // the output lands over a live prompt (the dev-server startup check).
 export function reportTypes(
-  types: { app: Diagnostic[]; hidden: number },
+  types: TypecheckResult,
   log: (...args: any[]) => void = console.log,
   error: (...args: any[]) => void = console.error,
 ): boolean {
@@ -125,33 +125,3 @@ export function reportTypes(
   else log("Types OK")
   return false
 }
-
-export async function runCheckCommand() {
-  let entry = source!
-  if (!existsSync(entry)) {
-    // Without this, the missing file surfaces later as an internal ENOENT
-    // stack trace (scandir/Bun.build), which reads as a CLI bug - the common
-    // cause is just running from the wrong directory.
-    console.error(`No such entry: ${entry} (resolved from ${process.cwd()})`)
-    process.exit(1)
-  }
-  let failed = false
-
-  let result = await bundleWith({ entry, dev: true, minify: false })
-  if (!result) {
-    // bundleWith already printed the compile errors.
-    failed = true
-  }
-
-  let root = findProjectRoot(entry)
-  if (!root) {
-    console.warn("Typecheck skipped: no tsconfig.json or package.json above the entry")
-  } else {
-    let types = await typecheck(root, entry)
-    if (types && reportTypes(types)) failed = true
-  }
-
-  if (failed) process.exit(1)
-  console.log("Check passed")
-  process.exit(0)
-}

package/src/client/docs.md

@@ -0,0 +1,9 @@
+# srt client
+
+{{ usage client }}
+
+The client half of [srt run](../server/docs.md), on its own. Without flags
+it attaches to the dev server of the project (or file) in the current
+directory; `--port` picks a local server by port and `--server` names any
+address, which is how a second machine joins a server started with `--lan`.
+A phone or tablet is [srt android](../android/docs.md).

package/src/client/main.ts

@@ -0,0 +1,33 @@
+import { values, port, clientStorageArgs } from "../lib/args"
+import { requireBinary, run } from "../lib/util"
+import { resolveFromCwd } from "../lib/registry"
+
+// Standalone solidrt-go client (no dev server of its own). Without flags it
+// attaches to the dev server of the project (or file) in the current
+// directory, resolved from the registry; --port picks a local server by port
+// and --server names any address. A device is `srt android`.
+export async function main() {
+  let runner = requireBinary("solidrt-go")
+  let args: string[] = [...clientStorageArgs()]
+  if (values.size) args.push("--size", values.size)
+  let address: string
+  if (values.server) {
+    if (!values.server.includes(":")) {
+      console.error(`--server needs host:port (got "${values.server}"); dev servers have no fixed port`)
+      process.exit(1)
+    }
+    address = values.server
+  } else if (port !== undefined) {
+    address = `127.0.0.1:${port}`
+  } else {
+    let resolved = await resolveFromCwd(process.cwd())
+    if (!resolved.ok) {
+      console.error(resolved.message)
+      process.exit(1)
+    }
+    address = `127.0.0.1:${resolved.record.port}`
+  }
+  args.push("--dev-server", address)
+  let exit = await run(runner, args)
+  process.exit(exit)
+}

package/src/console/docs.md

@@ -0,0 +1,14 @@
+# srt console
+
+{{ usage console }}
+
+The dev console: the dev servers running on this machine, the clients
+attached to each, and a button to start a local client for one. It is not
+served by a dev server: the CLI ships the console pre-compiled
+(`dist/console.srtapp`, see [srt pack --app](../pack/docs.md)) and this
+command starts the `solidrt` runner on that file, so it opens at once and
+runs the same whether a project is open or not.
+
+In a checkout the file is built with `make -C packages/cli
+dist/console.srtapp`; rerun it after editing `apps/console`. Everything
+after `--` reaches the console as its arguments.

package/src/console/main.ts

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { appArgs } from "../lib/args"
+import { requireBinary, run } from "../lib/util"
+
+// srt console: the dev console (apps/console) as a packed app on the plain
+// runner. The console is pre-compiled: dist/console.srtapp (manifest +
+// bytecode + assets, `srt pack --app`), built by `make -C packages/cli
+// dist/console.srtapp` - the release workflow before publishing, a checkout
+// after editing the console. This command builds nothing: it points the
+// runner at the file, and the runner is used in place, so a signed runner
+// stays signed.
+export async function main() {
+  let app = fileURLToPath(new URL("../../dist/console.srtapp", import.meta.url))
+  if (!existsSync(app)) {
+    console.error("Console not built: run make -C packages/cli dist/console.srtapp")
+    process.exit(1)
+  }
+  let exit = await run(requireBinary("solidrt"), [app, ...appArgs])
+  process.exit(exit)
+}

package/src/demo/docs.md

@@ -0,0 +1,27 @@
+# srt demo
+
+{{ usage demo }}
+
+The demos that come with the packages this project installs. Without an
+argument it lists them, numbered:
+
+```
+  1  3d/the-third-dimension
+```
+
+`srt demo 1` runs that one, exactly as [srt run](../server/docs.md) runs any
+project: a dev server, a local client window, reload on save, and the same
+server options (`--lan` to reach it from a device, `--port`, `--tunnel`). The qualified
+name works too (`srt demo 3d/the-third-dimension`), which is the stable way to
+name one in a script - the numbers follow the list, and the list follows what
+is installed.
+
+A package keeps its demos in `demos/`, and that folder is one project: its own
+package.json, one `assets/` folder, and `src/<name>.tsx` per demo. So the
+demos of one package share a dev server and a port - start a second one while
+the first is up and it says so. Demos from different packages run side by
+side.
+
+The demos ship inside the packages, so `node_modules` is where they are found:
+`srt demo` looks in the current directory and nowhere above it. Run it from
+the project root.

package/src/demo/main.ts

@@ -0,0 +1,67 @@
+import { readdirSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { source } from "../lib/args"
+
+// srt demo: the demos the installed @solidrt packages ship. A package's
+// demos are ONE project (`<package>/demos/`: package.json, one assets/, and
+// src/<name>.tsx per demo), so a demo runs as the project it lives in - this
+// file only lists and resolves, and main.ts starts the ordinary dev server
+// with its cwd set to that project. Nothing downstream knows about demos.
+
+export type Demo = { name: string; cwd: string; entry: string }
+
+const SCOPE = join("node_modules", "@solidrt")
+
+/** Every demo installed here, sorted so the printed numbers are stable.
+ * The cwd and nothing above it - the same rule the server's mode resolution
+ * follows (server/mode.ts), so this lists what THIS project installed. */
+function discover(): Demo[] {
+  let demos: Demo[] = []
+  for (let pkg of names(SCOPE)) {
+    let dir = join(SCOPE, pkg, "demos")
+    for (let file of names(join(dir, "src"))) {
+      if (!file.endsWith(".tsx")) continue
+      demos.push({ name: `${pkg}/${file.slice(0, -".tsx".length)}`, cwd: resolve(dir), entry: join("src", file) })
+    }
+  }
+  return demos
+}
+
+// A missing folder is the normal case (most packages ship no demos), so it
+// reads as an empty one rather than an error.
+function names(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort()
+  } catch {
+    return []
+  }
+}
+
+function list(demos: Demo[]) {
+  for (let [i, demo] of demos.entries()) console.log(`  ${String(i + 1).padStart(2)}  ${demo.name}`)
+}
+
+/** Lists (no argument) or resolves one demo for the dev server to serve. */
+export async function main(): Promise<{ cwd: string; entry: string } | undefined> {
+  let demos = discover()
+  if (demos.length === 0) {
+    console.error(`No demos installed in ${process.cwd()} (looked in ${SCOPE}/*/demos/src/)`)
+    process.exit(1)
+  }
+
+  if (source === undefined) {
+    list(demos)
+    console.log("\nRun one with: srt demo <number>")
+    return undefined
+  }
+
+  // A number picks from the printed list; the qualified name it printed
+  // works too, so a demo can be named in a script without a fixed index.
+  let picked = /^\d+$/.test(source) ? demos[Number(source) - 1] : demos.find((d) => d.name === source)
+  if (!picked) {
+    console.error(`No such demo: ${source}`)
+    list(demos)
+    process.exit(1)
+  }
+  return { cwd: picked.cwd, entry: picked.entry }
+}

package/src/init/docs.md

@@ -0,0 +1,11 @@
+# srt init
+
+{{ usage init }}
+
+Scaffolds a new SolidRT project into a new (empty) folder: package.json,
+tsconfig.json, AGENTS.md, a starter src/index.tsx, an empty assets/
+(everything in it ships with the app) and an `.mcp.json`, then installs the
+dependencies. The picker offers extensions on an interactive terminal.
+
+The public entry point is `bun create solidrt <dir>`, which forwards here and
+needs nothing installed first.

package/src/{commands/init.ts → init/main.ts}

@@ -1,15 +1,15 @@
 import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
-import { source, values } from "../args"
-import { multiselect, note, text } from "../prompt"
+import { source, values } from "../lib/args"
+import { multiselect, note, text } from "./prompt"
 
 const DEFAULT_NAME = "solidrt-app"
 
-const SCAFFOLD_DIR = join(import.meta.dir, "../../scaffold")
+const SCAFFOLD_DIR = join(import.meta.dir, "scaffold")
 const TEMPLATES_DIR = join(SCAFFOLD_DIR, "templates")
 
 // Shared project files written for every template. Sources live in
-// cli/scaffold/. The .gitignore is stored there as `gitignore` because npm
+// cli/src/init/scaffold/. The .gitignore is stored there as `gitignore` because npm
 // strips files literally named `.gitignore` from published packages, so it is
 // renamed on the way out. The per-template src/ comes from scaffold/templates/.
 const TEMPLATE_FILES: Array<{ from: string; to: string }> = [
@@ -31,22 +31,26 @@ function packageName(dir: string): string {
 const DEFAULT_TEMPLATE = "default"
 
 // One AGENTS.md serves every template, so the lines that point an agent at
-// @solidrt/components docs are fenced between markers: with the extension
-// selected only the markers go, without it the block goes too, so a core-only
-// app never ships references to files that are not installed.
-const MARKED_BLOCK = /^<!-- components:begin -->\n[\s\S]*?^<!-- components:end -->\n/gm
-const MARKER = /^<!-- components:(?:begin|end) -->\n/gm
-
+// an extension's docs are fenced between `<!-- <key>:begin/end -->` markers:
+// with the extension selected only the markers go, without it the block goes
+// too, so an app never ships references to files that are not installed.
 function resolveMarkers(text: string, extensions: Extension[]): string {
-  let selected = extensions.some((e) => e.pkg === "@solidrt/components")
-  return selected ? text.replace(MARKER, "") : text.replace(MARKED_BLOCK, "")
+  for (let ext of EXTENSIONS) {
+    let selected = extensions.includes(ext)
+    let block = new RegExp(`^<!-- ${ext.key}:begin -->\\n[\\s\\S]*?^<!-- ${ext.key}:end -->\\n`, "gm")
+    let marker = new RegExp(`^<!-- ${ext.key}:(?:begin|end) -->\\n`, "gm")
+    text = selected ? text.replace(marker, "") : text.replace(block, "")
+  }
+  return text
 }
 
 // Optional packages an app can opt into on top of core. Each maps to a
 // dependency in the scaffold package.json (kept when selected, removed
-// otherwise) and optionally to a starter under scaffold/templates/.
+// otherwise), to a marker key fencing its lines in scaffold/AGENTS.md, and
+// optionally to a starter under scaffold/templates/.
 interface Extension {
   pkg: string
+  key: string
   template?: string
   description: string
 }
@@ -54,10 +58,12 @@ interface Extension {
 const EXTENSIONS: Extension[] = [
   {
     pkg: "@solidrt/components",
+    key: "components",
     template: "components",
     description: "component framework: widgets, theming, navigation",
   },
-  { pkg: "@solidrt/3d", description: "general purpose 3D library" },
+  { pkg: "@solidrt/2d", key: "2d", description: "general purpose 2D library" },
+  { pkg: "@solidrt/3d", key: "3d", description: "general purpose 3D library" },
 ]
 
 // Resolve which extensions the app takes: an interactive picker on a TTY,
@@ -80,7 +86,7 @@ function resolveTemplate(extensions: Extension[]): string {
   return extensions.find((e) => e.template)?.template ?? DEFAULT_TEMPLATE
 }
 
-export async function runInitCommand() {
+export async function main() {
   // The target folder comes from the positional arg, or an interactive prompt
   // (defaulting to a suggested name) when omitted.
   let dir = source