create-op-node 0.5.0 → 0.7.0

package/README.md

@@ -28,6 +28,66 @@ npx create-op-node bootstrap
 
 Configures macOS power settings, installs Homebrew + the CLI tool list, sets up Docker Desktop + Tailscale + Ollama, clones the node repo you created, reads the pgsodium key + Tunnel token from the Studio's Keychain (or prompts you to paste them once, then persists for re-runs), writes the LaunchAgent plist, logs into ghcr.io, pulls + warms the LLM model, and finally `docker compose --profile public pull && up -d` brings the whole stack online. Health-check loop waits until all containers are `(healthy)`.
 
+### Choosing the LLM model
+
+When you run `bootstrap` interactively (no `-y`, no `--llm-model` flag),
+you'll get a curated picker:
+
+- `qwen2.5:72b` — 72B, ~50 GB Ollama RAM. **Default**, recommended for
+  128 GB Studios. Best Spanish + multilingual quality.
+- `qwen2.5:32b` — 32B, ~22 GB Ollama RAM. Middle tier for 64 GB Studios.
+- `qwen3.5:9b` — 9B, ~8 GB Ollama RAM. Validation runs or smaller
+  Studios (36–48 GB).
+- `Other…` — any Ollama model name you specify.
+
+The picker is Qwen-only because the Opus Populi platform serves
+Spanish-speaking civic users and Qwen has the strongest Spanish (and
+broader multilingual) capability of the open-weight models in this
+size class. Pick "Other…" for non-Qwen models.
+
+For non-interactive runs (`-y`) or scripted invocations, the LLM
+defaults to `qwen3.5:9b` (small, fast) — pass `--llm-model` to override:
+
+```bash
+# Just swap the LLM, keep the default embedding model:
+npx create-op-node bootstrap --region us-ca --llm-model llama3.3:70b
+
+# Override both:
+npx create-op-node bootstrap \
+  --region us-ca \
+  --llm-model llama3.3:70b \
+  --embedding-model mxbai-embed-large
+```
+
+The chosen models flow two places:
+
+1. **Ollama**: bootstrap pulls + warms them so the daemon has them
+   resident before the stack comes up. The embedding model pulls first
+   (small, fast feedback); the LLM pulls second (can be tens of GB).
+2. **LaunchAgent**: the plist exports `LLM_MODEL` and `EMBEDDINGS_MODEL`
+   into the launchd session, which Docker Desktop inherits — so compose
+   services read them via env, no `.env.production` edits needed.
+
+> **`--embedding-model` only takes effect when the knowledge service
+> runs with `EMBEDDINGS_PROVIDER=ollama`.** The default provider is
+> `xenova` (in-process), which bundles its own embedding model and
+> ignores both `EMBEDDINGS_MODEL` and the local Ollama model. Setting
+> `EMBEDDINGS_PROVIDER=ollama` is a separate decision (set in your
+> region repo's `.env.production`) — see `docs/provider-pattern.md`.
+
+> **Template contract**: for `--llm-model` to actually change the
+> running model, the region repo's `docker-compose-prod.yml` must use
+> `${LLM_MODEL:-qwen3.5:9b}` (or similar) on the knowledge service's
+> `environment:` block. The current `opuspopuli-node` template does;
+> a fork that hardcodes the value would ignore the flag silently.
+
+For RAM sizing, the [Docker resources doc](https://github.com/OpusPopuli/opuspopuli-node/blob/main/docs/docker-resources.md)
+has a tier table: 9B-class needs ~8 GB Ollama; 70B-class needs ~50 GB;
+frontier MoE needs ~80 GB. Allocate Docker the remainder.
+
+To switch models post-bootstrap, re-run with the new flag and
+`docker compose down && up -d` to pick up the changed env.
+
 ### Local-only mode (no Cloudflare)
 
 For local dev / testing — frontend on your laptop, backend on the Studio
@@ -481,6 +541,17 @@ pnpm build                  # tsup → dist/
 node dist/cli.js --help     # test the built binary
 ```
 
+### Releases
+
+Releases are automated via [release-please](https://github.com/googleapis/release-please-action):
+
+1. **Write Conventional Commits.** `feat:` → minor bump (or major on `BREAKING CHANGE:`); `fix:` → patch; `docs:`/`refactor:`/`perf:` show up in CHANGELOG; `chore:`/`test:`/`build:`/`ci:` are hidden.
+2. **Merge PRs to `main`** as normal.
+3. **release-please opens a `chore(main): release X.Y.Z` PR** that bumps `package.json` + `src/cli.ts`'s `VERSION` constant + adds a CHANGELOG section. It updates the PR continuously as more commits land.
+4. **Merge the release PR.** That creates the `vX.Y.Z` tag + a GitHub Release. `publish.yml` fires on the tag push and runs `npm publish --provenance --access public`.
+
+No manual version bumps, no manual tagging. To trigger a release with no functional changes (re-publishing after a CI fix, etc.), push a commit with `chore: trigger release` — release-please will skip it but still update the PR.
+
 ## License
 
 [AGPL-3.0-or-later](./LICENSE). The Opus Populi platform code is AGPL-3.0 + dual commercial; this CLI inherits the AGPL-3.0 terms.

package/dist/cli.js

@@ -1189,10 +1189,21 @@ async function writePgsodiumKeyFile(key, keyFile) {
     return { ok: false, reason: `writing ${keyFile} failed: ${err.message}` };
   }
 }
+var MODEL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
 function renderLaunchAgentPlist(input) {
   if (input.tunnelToken !== void 0 && !TUNNEL_TOKEN_RE.test(input.tunnelToken)) {
     throw new Error("Tunnel token contains characters outside the expected base64-url set");
   }
+  if (input.llmModel !== void 0 && !MODEL_NAME_RE.test(input.llmModel)) {
+    throw new Error(
+      `llmModel ${JSON.stringify(input.llmModel)} contains characters not allowed in a launchd setenv value`
+    );
+  }
+  if (input.embeddingModel !== void 0 && !MODEL_NAME_RE.test(input.embeddingModel)) {
+    throw new Error(
+      `embeddingModel ${JSON.stringify(input.embeddingModel)} contains characters not allowed in a launchd setenv value`
+    );
+  }
   if (!SAFE_PATH_RE.test(input.keyFilePath)) {
     throw new Error(
       `keyFilePath ${JSON.stringify(input.keyFilePath)} contains characters not allowed in a launchd path interpolation`
@@ -1200,7 +1211,9 @@ function renderLaunchAgentPlist(input) {
   }
   const setenvLines = [
     `launchctl setenv PGSODIUM_ROOT_KEY "$(cat ${input.keyFilePath})"`,
-    ...input.tunnelToken !== void 0 ? [`launchctl setenv TUNNEL_TOKEN "${input.tunnelToken}"`] : []
+    ...input.tunnelToken !== void 0 ? [`launchctl setenv TUNNEL_TOKEN "${input.tunnelToken}"`] : [],
+    ...input.llmModel !== void 0 ? [`launchctl setenv LLM_MODEL "${input.llmModel}"`] : [],
+    ...input.embeddingModel !== void 0 ? [`launchctl setenv EMBEDDINGS_MODEL "${input.embeddingModel}"`] : []
   ];
   const command = setenvLines.join("; ");
   return [
@@ -1255,7 +1268,9 @@ async function setupLaunchAgent(input) {
   try {
     plistContent = renderLaunchAgentPlist({
       keyFilePath: paths.keyFile,
-      ...input.tunnelToken !== void 0 ? { tunnelToken: input.tunnelToken } : {}
+      ...input.tunnelToken !== void 0 ? { tunnelToken: input.tunnelToken } : {},
+      ...input.llmModel !== void 0 ? { llmModel: input.llmModel } : {},
+      ...input.embeddingModel !== void 0 ? { embeddingModel: input.embeddingModel } : {}
     });
   } catch (err) {
     return { ok: false, paths, step: "plist", reason: err.message };
@@ -1475,7 +1490,8 @@ function assessHealth(snapshots, requireHealthy) {
 
 // src/lib/ollama.ts
 var OLLAMA_URL = "http://localhost:11434";
-var DEFAULT_MODELS = ["qwen3.5:9b", "nomic-embed-text"];
+var DEFAULT_LLM_MODEL = "qwen3.5:9b";
+var DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
 var PROBE_ALPINE_TAG = "3.20";
 async function startOllamaService() {
   const res = await safeExeca("brew", ["services", "start", "ollama"]);
@@ -1646,7 +1662,17 @@ var bootstrapCommand = new Command("bootstrap").description(
     "--skip-launch-agent",
     "Skip the LaunchAgent setup (assumes one is already in place)"
   ).default(false)
-).addOption(new Option("--skip-ollama", "Skip the Ollama model pull + warm").default(false)).addOption(new Option("--skip-stack", "Stop before `docker compose pull && up`").default(false)).addOption(
+).addOption(new Option("--skip-ollama", "Skip the Ollama model pull + warm").default(false)).addOption(
+  new Option(
+    "--llm-model <model>",
+    `Ollama LLM model to pull and warm. Default: ${DEFAULT_LLM_MODEL}. Examples: \`llama3.3:70b\`, \`qwen2.5:72b\`. Memory sizing table: docs/docker-resources.md in the opuspopuli-node template (or your region repo's checkout).`
+  )
+).addOption(
+  new Option(
+    "--embedding-model <model>",
+    `Ollama embedding model. Default: ${DEFAULT_EMBEDDING_MODEL}. Only takes effect when the knowledge service runs with EMBEDDINGS_PROVIDER=ollama (otherwise embeddings are computed in-process via xenova).`
+  )
+).addOption(new Option("--skip-stack", "Stop before `docker compose pull && up`").default(false)).addOption(
   new Option(
     "--local-only",
     "Run for local dev / testing: no Tunnel token required, cloudflared stays down. Auto-generates the pgsodium key if not in Keychain (init unnecessary)."
@@ -1664,6 +1690,11 @@ var bootstrapCommand = new Command("bootstrap").description(
   const repoName = `opuspopuli-node-${region}`;
   const composeFileDefault = opts.localOnly ? ["docker-compose-prod.yml"] : ["docker-compose-prod.yml", "docker-compose-backup.yml"];
   const composeFile = opts.composeFile ?? composeFileDefault;
+  const llmModelChoice = opts.llmModel ?? await selectLlmModel(opts);
+  const [embeddingModel, llmModel] = resolveModels({
+    llmModel: llmModelChoice,
+    ...opts.embeddingModel !== void 0 ? { embeddingModel: opts.embeddingModel } : {}
+  });
   const sysSpin = p3.spinner();
   sysSpin.start("Inspecting macOS\u2026");
   const snap = await inspectSystem();
@@ -1724,7 +1755,7 @@ var bootstrapCommand = new Command("bootstrap").description(
       unwrap(await p3.confirm({ message: "Homebrew installed?", initialValue: true }));
     }
     const brewSpin = p3.spinner();
-    brewSpin.start("Installing Studio packages\u2026");
+    brewSpin.start("Installing Studio packages\u2026 (~5\u201315 min first run)");
     const report = await installPackages(STUDIO_PACKAGES, (pkg, status) => {
       brewSpin.message(`${status}: ${pkg.name}`);
     });
@@ -1799,7 +1830,9 @@ var bootstrapCommand = new Command("bootstrap").description(
     laSpin.start("Writing pgsodium key file + LaunchAgent plist\u2026");
     const la = await setupLaunchAgent({
       pgsodiumKey,
-      ...tunnelToken !== void 0 ? { tunnelToken } : {}
+      ...tunnelToken !== void 0 ? { tunnelToken } : {},
+      llmModel,
+      embeddingModel
     });
     if (!la.ok) {
       laSpin.stop(pc2.red(`\u2717 LaunchAgent step ${la.step} failed.`));
@@ -1823,7 +1856,7 @@ var bootstrapCommand = new Command("bootstrap").description(
   ghcrSpin.stop(pc2.green("\u2713 Logged in to ghcr.io."));
   if (!opts.skipOllama) {
     const olSpin = p3.spinner();
-    olSpin.start("Pulling + warming Ollama models\u2026");
+    olSpin.start(`Pulling + warming Ollama models\u2026 (${estimatedPullTime(llmModel)})`);
     let olHealth = await checkOllamaHealth();
     if (!olHealth.reachable) {
       olSpin.message("Ollama not reachable \u2014 running `brew services start ollama`\u2026");
@@ -1847,7 +1880,7 @@ var bootstrapCommand = new Command("bootstrap").description(
         process.exit(1);
       }
     }
-    const modelReport = await setupModels(DEFAULT_MODELS, (model, status) => {
+    const modelReport = await setupModels([embeddingModel, llmModel], (model, status) => {
       olSpin.message(`${status}: ${model}`);
     });
     olSpin.stop(
@@ -1888,7 +1921,7 @@ var bootstrapCommand = new Command("bootstrap").description(
     );
   }
   const pullSpin = p3.spinner();
-  pullSpin.start("Pulling images from ghcr.io\u2026");
+  pullSpin.start("Pulling images from ghcr.io\u2026 (~5\u201315 min first run, < 1 min cached)");
   const pull = await composePull(composeOpts);
   if (!pull.ok) {
     pullSpin.stop(pc2.red("\u2717 compose pull failed."));
@@ -1906,7 +1939,7 @@ var bootstrapCommand = new Command("bootstrap").description(
   }
   upSpin.stop(pc2.green("\u2713 Containers started \u2014 waiting for healthy\u2026"));
   const healthSpin = p3.spinner();
-  healthSpin.start("Polling for healthy containers (5s, up to 5 minutes)\u2026");
+  healthSpin.start("Polling for healthy containers\u2026 (every 5s, up to 5 min)");
   const outcome = await waitForHealthy(composeOpts, {
     onPoll: (snaps) => {
       const healthy = snaps.filter((s) => s.health === "healthy").length;
@@ -1966,6 +1999,65 @@ function resolveComposeFiles(repoPath, composeFile) {
   const inputs = composeFile ?? ["docker-compose-prod.yml"];
   return inputs.map((f) => f.startsWith("/") ? f : join(repoPath, f));
 }
+function resolveModels(opts) {
+  return [
+    opts.embeddingModel ?? DEFAULT_EMBEDDING_MODEL,
+    opts.llmModel ?? DEFAULT_LLM_MODEL
+  ];
+}
+var LLM_MODEL_CHOICES = [
+  {
+    value: "qwen2.5:72b",
+    label: "qwen2.5:72b",
+    hint: "72B, ~50 GB Ollama RAM. Recommended for 128 GB Studios. Best Spanish + multilingual quality. Pull ~40 GB, 30\u201360 min."
+  },
+  {
+    value: "qwen2.5:32b",
+    label: "qwen2.5:32b",
+    hint: "32B, ~22 GB Ollama RAM. Middle-tier for 64 GB Studios. Solid Spanish, faster than 72B. Pull ~20 GB, 15\u201330 min."
+  },
+  {
+    value: "qwen3.5:9b",
+    label: "qwen3.5:9b",
+    hint: "9B, ~8 GB Ollama RAM. Validation / smaller Studios (36\u201348 GB). Pull ~5 GB, 3\u20135 min."
+  }
+];
+var OTHER_SENTINEL = "__OTHER__";
+async function selectLlmModel(opts) {
+  if (opts.yes) return DEFAULT_LLM_MODEL;
+  const choice = unwrap(
+    await p3.select({
+      message: "Choose the LLM model to pull + run",
+      initialValue: "qwen2.5:72b",
+      options: [
+        ...LLM_MODEL_CHOICES.map((c) => ({ value: c.value, label: c.label, hint: c.hint })),
+        {
+          value: OTHER_SENTINEL,
+          label: "Other\u2026",
+          hint: "Specify any Ollama model name (e.g. mistral-small:24b)"
+        }
+      ]
+    })
+  );
+  if (choice !== OTHER_SENTINEL) return choice;
+  return unwrap(
+    await p3.text({
+      message: "Ollama model name",
+      placeholder: "e.g. mistral-small:24b",
+      validate: (v) => /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(v ?? "") ? void 0 : "Letters, digits, `.`, `:`, `_`, `-`, `/` only; must start with alphanumeric"
+    })
+  );
+}
+function estimatedPullTime(model) {
+  if (/\d+x\d+b/i.test(model)) return "~60+ min for frontier MoE";
+  const match = /(\d+)b\b/i.exec(model);
+  if (!match) return "time depends on model size";
+  const size = Number.parseInt(match[1], 10);
+  if (size <= 13) return "~3\u20135 min for \u2264 13B-class";
+  if (size <= 35) return "~15\u201330 min for ~32B-class";
+  if (size <= 80) return "~30\u201360 min for 70B-class";
+  return "~60+ min for frontier-class";
+}
 function kvBool(b) {
   return b ? pc2.green("on") : pc2.yellow("off");
 }
@@ -3808,7 +3900,7 @@ async function looksLikeRegionsRepo(dir) {
 }
 
 // src/cli.ts
-var VERSION = "0.5.0";
+var VERSION = "0.7.0";
 var program = new Command();
 program.name("create-op-node").description(
   "Interactive bootstrap for an Opus Populi federation node.\nCloudflare infrastructure \u2192 Mac Studio \u2192 live public API."