create-quorum-router 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sakamoto-sann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# create-quorum-router
+
+Create a local QuorumRouter project scaffold.
+
+QuorumRouter is **MIT-licensed open source**. Commercial and production use are
+permitted under the MIT License.
+
+## Usage
+
+```bash
+npx --yes create-quorum-router@latest my-quorum-router-demo
+cd my-quorum-router-demo
+deno --version
+deno task smoke
+deno task intake
+```
+
+Current package version: `create-quorum-router@0.1.5`. Releases are published
+from an immutable Git tag through GitHub Actions OIDC Trusted Publishing.
+
+## What the generated project supports
+
+`deno task smoke` is deterministic fixture-only and does not call a provider
+API.
+
+`deno task intake` is the first real setup command. It detects local provider
+wrappers, checks OAuth/session status, runs safe list-only model inventory where
+possible, writes redacted local health artifacts under `out/`, and recommends
+the next command.
+
+```bash
+deno task check
+deno task smoke
+deno task intake
+deno task auth:status
+deno task auth:login
+deno task auth:logout
+deno task models:list
+deno task health
+```
+
+Real provider use is OAuth/session/wrapper-first:
+
+```bash
+RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task route:once --prompt "Review this README for risky claims."
+RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task route:once --prompt "https://github.com/sakamoto-sann/quorum-router review this repo's launch readiness."
+# GitHub URL prompts fetch bounded repository context before invoking the selected provider.
+# Only use this with repositories you are allowed to send to that provider.
+RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task best-route --prompt "Choose the safest launch copy."
+RUN_EXTERNAL_MODEL_DOGFOOD=1 RUN_EXPERIMENTAL_AGENT_CHAT=1 deno task agent-chat --prompt "Review this launch plan."
+```
+
+`auth:login` does not ask for API keys as the primary path. If OAuth/browser
+login is not wired in the generated scaffold, it fails closed and tells the user
+to use an installed provider CLI login, then rerun `deno task intake`.
+
+## Private/manual env fallback
+
+Generic env fallback exists only as an explicit private/manual fallback with
+`QUORUM_ROUTER_AUTH_MODE=env`. It is never used silently, and it is not the
+preferred public dogfood path.
+
+Do not commit `.env`, `router.config.local.json`, `.quorum-router/`, or `out/`.
+Do not paste tokens into chat/logs.
+
+## Runtime boundaries
+
+- Best Route/direct is production-ready best-answer routing.
+- Conversation-only `agent_chat` is explicit opt-in.
+- SafeLoop-backed Agent Chat can perform the verified local repository execution
+  slice only when separately configured with signed policy and distinct
+  approval.
+- The generated scaffold does not enable mutation by default.
+- No service-role runtime.
+- No live Supabase Agent Bus runtime writes.
+- Public launch requires the repository verification, package tarball, registry
+  readback, and clean-room NPX scaffold checks to pass.
+
+## CLI
+
+```bash
+create-quorum-router <dir>
+create-quorum-router <dir> --template basic
+create-quorum-router <dir> --force
+create-quorum-router --help
+create-quorum-router --version
+```
+
+The CLI refuses to overwrite a non-empty directory unless `--force` is passed.

package/bin/create-quorum-router.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const VERSION = "0.1.5";
+const SUPPORTED_TEMPLATES = new Set(["basic"]);
+
+function usage() {
+  return `create-quorum-router ${VERSION}
+
+Usage:
+  create-quorum-router <dir>
+  create-quorum-router <dir> --template basic
+  create-quorum-router <dir> --force
+  create-quorum-router --help
+  create-quorum-router --version
+
+Creates a local QuorumRouter project scaffold. The scaffold does not fetch remote
+code, install dependencies, ask for credentials, write secrets, enable process
+adapters, or configure live runtime services. Fixture smoke is deterministic;
+external provider dogfood and GitHub URL context fetching are explicit manual
+opt-in paths.`;
+}
+
+function hasCommand(command) {
+  const result = spawnSync(command, ["--version"], { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const options = { template: "basic", force: false, dir: undefined };
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === "--help" || arg === "-h") return { help: true };
+    if (arg === "--version" || arg === "-v") return { version: true };
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--template") {
+      const template = args.shift();
+      if (!template) throw new Error("--template requires a value");
+      options.template = template;
+      continue;
+    }
+    if (arg && arg.startsWith("--template=")) {
+      options.template = arg.slice("--template=".length);
+      continue;
+    }
+    if (arg && arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+    if (options.dir) throw new Error(`unexpected extra argument: ${arg}`);
+    options.dir = arg;
+  }
+  return options;
+}
+
+function copyRecursive(from, to) {
+  const stat = fs.statSync(from);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from)) {
+      const targetEntry = entry === "gitignore" ? ".gitignore" : entry;
+      copyRecursive(path.join(from, entry), path.join(to, targetEntry));
+    }
+    return;
+  }
+  fs.copyFileSync(from, to);
+}
+
+function isNonEmptyDirectory(dir) {
+  try {
+    const stat = fs.statSync(dir);
+    return stat.isDirectory() && fs.readdirSync(dir).length > 0;
+  } catch (error) {
+    if (error && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    console.log(usage());
+    return;
+  }
+  if (parsed.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (!parsed.dir) {
+    throw new Error("target directory is required\n\n" + usage());
+  }
+  if (!SUPPORTED_TEMPLATES.has(parsed.template)) {
+    throw new Error(`unsupported template: ${parsed.template}`);
+  }
+
+  const targetDir = path.resolve(process.cwd(), parsed.dir);
+  if (isNonEmptyDirectory(targetDir) && !parsed.force) {
+    throw new Error(
+      `refusing to overwrite non-empty directory: ${targetDir}\n` +
+        "Pass --force to overwrite template files in this directory.",
+    );
+  }
+
+  const templateDir = path.join(__dirname, "..", "templates", parsed.template);
+  fs.mkdirSync(targetDir, { recursive: true });
+  copyRecursive(templateDir, targetDir);
+  fs.mkdirSync(path.join(targetDir, "out"), { recursive: true });
+  fs.writeFileSync(path.join(targetDir, "out", ".gitkeep"), "");
+
+  console.log(`Created QuorumRouter project in ${targetDir}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${path.relative(process.cwd(), targetDir) || "."}`);
+  console.log("  deno task check");
+  console.log("  deno task smoke");
+  console.log("  deno task intake");
+  console.log("  deno task auth:status");
+  console.log("  deno task models:list");
+  console.log("  deno task health");
+  if (!hasCommand("deno")) {
+    console.log("");
+    console.log("Warning: Deno was not found on PATH.");
+    console.log(
+      "Install Deno before running the tasks above: brew install deno, or use the official installer at deno.com/install.",
+    );
+    console.log("Then verify with: deno --version");
+  }
+  console.log(
+    "  # Optional one-shot real provider dogfood after intake reports a usable OAuth/session/wrapper provider:",
+  );
+  console.log(
+    '  RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task route:once --prompt "Review this README for risky claims."',
+  );
+  console.log("  # Optional Best Route over local wrappers:");
+  console.log(
+    '  RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task best-route --prompt "Choose the safest launch copy."',
+  );
+  console.log(
+    "  # Optional conversation-only Agent Chat stays explicit opt-in:",
+  );
+  console.log(
+    '  RUN_EXTERNAL_MODEL_DOGFOOD=1 RUN_EXPERIMENTAL_AGENT_CHAT=1 deno task agent-chat --prompt "Review this launch plan."',
+  );
+  console.log("");
+  console.log(
+    "Note: deno task smoke is deterministic fixture-only and does not call a provider API.",
+  );
+  console.log(
+    "Note: intake is the first real setup command; route:once/best-route are manual opt-in real provider dogfood; env fallback requires QUORUM_ROUTER_AUTH_MODE=env.",
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error && error.message ? error.message : String(error));
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "create-quorum-router",
+  "version": "0.1.5",
+  "description": "Create a local QuorumRouter project.",
+  "license": "MIT",
+  "bin": {
+    "create-quorum-router": "bin/create-quorum-router.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sakamoto-sann/quorum-router.git"
+  }
+}

package/templates/basic/README.md

@@ -0,0 +1,168 @@
+# QuorumRouter generated workspace
+
+This generated workspace contains the MIT-licensed QuorumRouter current release.
+npm latest targets v0.1.5.
+
+QuorumRouter is **MIT**. It is **open source**. Commercial and production use
+are permitted under the MIT License.
+
+## Security and runtime boundaries
+
+- MIT-licensed open source; commercial and production use are permitted.
+- `deno task smoke` is fixture-only and credential-free.
+- `deno task intake` is the first real setup command.
+- Real provider use is OAuth/session/wrapper-first.
+- API key env fallback is private/manual only and never used silently.
+- Never commit `.env`, `router.config.local.json`, `provider_config.json`,
+  `.quorum-router/`, or `out/` traces.
+- Never paste tokens into chat/logs.
+- Conversation-only `agent_chat` is explicit opt-in.
+- SafeLoop-backed production repository execution is not enabled by this
+  generated scaffold; it requires external signed policy and distinct approval.
+- No service-role runtime.
+- No live Supabase runtime writes.
+- No live Supabase Agent Bus runtime writes.
+- Best Route/direct is the production-ready best-answer routing path.
+- `agent-chat` is read-only explicit opt-in only.
+
+## First launch
+
+Prerequisite: install Deno before running scaffold tasks. Verify with:
+
+```bash
+deno --version
+```
+
+```bash
+deno task smoke
+deno task intake
+deno task auth:status
+deno task models:list
+deno task health
+```
+
+`smoke` proves the local scaffold runs with deterministic fixtures only. It does
+**not** call a real provider API.
+
+`intake` detects local provider wrappers, checks OAuth/session status, runs safe
+model inventory/list-only probes where possible, writes local health traces
+under `out/`, and recommends the next command.
+
+In short: intake is the first real setup command before `route:once`,
+`best-route`, or read-only `agent-chat`.
+
+## Real provider dogfood commands
+
+Run only after `intake` reports a usable OAuth/session/wrapper provider:
+
+```bash
+RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task route:once --prompt "Review this README for risky claims."
+RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task best-route --prompt "Choose the safest launch copy."
+RUN_EXTERNAL_MODEL_DOGFOOD=1 RUN_EXPERIMENTAL_AGENT_CHAT=1 deno task agent-chat --prompt "Review this launch plan."
+```
+
+Behavior:
+
+- `route:once` requires `RUN_EXTERNAL_MODEL_DOGFOOD=1`.
+- `best-route` requires `RUN_EXTERNAL_MODEL_DOGFOOD=1`.
+- `agent-chat` requires both `RUN_EXTERNAL_MODEL_DOGFOOD=1` and
+  `RUN_EXPERIMENTAL_AGENT_CHAT=1`.
+- Live Agent Chat requires at least two distinct working provider/model
+  identities. It passes the bounded transcript to alternating models, prints
+  each response and `replying to` lineage as it arrives, and stores turns in
+  `out/agent-chat-trace.json`.
+- Set `QUORUM_ROUTER_AGENT_CHAT_MAX_TURNS` from 2–12 (default 6) to bound calls.
+- Default auth mode is OAuth/session/wrapper-first.
+- In auto mode, `route:once` prefers list-verified wrapper models and safely
+  tries the next wrapper when an invocation fails; the trace records the failed
+  attempt and `fallback_used`.
+- Explicit provider/model selection never falls back to a different wrapper.
+- Env fallback is used only with `QUORUM_ROUTER_AUTH_MODE=env` and local private
+  credential environment.
+- Traces are redacted and written under `out/`.
+- When the prompt contains a GitHub repository URL like
+  `https://github.com/owner/repo`, `route:once`, `best-route`, and read-only
+  `agent-chat` fetch a bounded, prioritized set of repository text files first,
+  quote them as untrusted JSON data, and record context coverage in the trace.
+  Only use this with repositories you are allowed to send to the selected
+  provider.
+
+### Forced wrapper provider/model selection
+
+Use these only when you want a specific local wrapper/model. The scaffold fails
+closed if the requested provider or model is unavailable; it never silently
+falls back to OpenAI/Codex or private env fallback unless
+`QUORUM_ROUTER_AUTH_MODE=env` is explicit.
+
+```bash
+QUORUM_ROUTER_AUTH_MODE=wrapper \
+QUORUM_ROUTER_PROVIDER_LABEL=grok-cli \
+QUORUM_ROUTER_PROVIDER_MODEL=grok-build \
+RUN_EXTERNAL_MODEL_DOGFOOD=1 \
+  deno task route:once --prompt "Review this README for risky claims."
+
+QUORUM_ROUTER_AUTH_MODE=wrapper \
+QUORUM_ROUTER_PROVIDER_LABEL=grok-cli \
+QUORUM_ROUTER_PROVIDER_MODEL=grok-composer-2.5-fast \
+RUN_EXTERNAL_MODEL_DOGFOOD=1 \
+  deno task route:once --prompt "Review this README for usability."
+```
+
+Supported provider aliases include `grok-cli`, `grok`, `xai`, `xAI`, `OpenAI`,
+`codex-cli`, `claude-code`, `gemini-cli`, `devin-cli`, and `qwen-cli`. Wrapper
+invocations use argv arrays, closed stdin, timeout guards, and sanitized
+stdout/stderr; CLI banners or auth/runtime errors are not accepted as valid
+model answers.
+
+## Auth and inventory
+
+```bash
+deno task auth:status
+deno task auth:login
+deno task auth:logout
+deno task models:list
+```
+
+`auth:login` does not ask for API keys as the primary path. If OAuth/browser
+login is not wired in this scaffold, it fails closed and tells you to use an
+installed provider CLI login, then rerun `deno task intake`.
+
+Browser/device login handling is safe-by-default: the scaffold does not open a
+browser automatically. Provider CLIs own their own login flows.
+
+## Private/manual env fallback
+
+Generic OpenAI-compatible env fallback exists only as an explicit private
+fallback:
+
+```bash
+QUORUM_ROUTER_AUTH_MODE=env \
+RUN_EXTERNAL_MODEL_DOGFOOD=1 \
+  deno task route:once --prompt "Review this README change."
+```
+
+Credential values must come from your local environment or secret manager. Do
+not paste them into chat/logs and do not commit `.env`.
+
+## Generated files
+
+- `main.ts` — deterministic fixture smoke only.
+- `deno.json` — generated task surface.
+- `README.md` — practical first-launch guide.
+- `.gitignore` — excludes `.env`, `out/`, `router.config.local.json`,
+  `provider_config.json`, and `.quorum-router/`.
+- `router.config.example.json` — non-secret example boundaries.
+- `src/cli.ts` — command dispatcher.
+- `src/intake.ts` — first-run onboarding.
+- `src/auth.ts`, `src/auth_oauth.ts`, `src/auth_session.ts`,
+  `src/auth_env_fallback.ts` — auth/session/fallback boundaries.
+- `src/provider_registry.ts`, `src/model_inventory.ts`, `src/wrapper_client.ts`,
+  `src/provider_client.ts` — provider discovery and safe invocation.
+- `src/best_route.ts`, `src/agent_chat.ts` — gated dogfood commands.
+- `src/trace.ts`, `src/redact.ts`, `src/schema.ts`, `src/fixture_smoke.ts` —
+  trace/redaction/schema/fixture support.
+- `out/.gitkeep` — local output directory placeholder.
+
+Public Product Hunt/X launch remains blocked until the user personally runs a
+local pre-release workspace and approves release continuation. This scaffold
+does not publish npm, create a GitHub release, or mutate tags/dist-tags.

package/templates/basic/deno.json

@@ -0,0 +1,19 @@
+{
+  "lock": false,
+  "imports": {
+    "zod": "https://deno.land/x/zod@v3.23.8/mod.ts"
+  },
+  "tasks": {
+    "check": "deno check main.ts src/*.ts",
+    "smoke": "deno run main.ts",
+    "intake": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts intake",
+    "auth:status": "deno run --allow-read --allow-env --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts auth:status",
+    "auth:login": "deno run src/cli.ts auth:login",
+    "auth:logout": "deno run --allow-read --allow-write --allow-env src/cli.ts auth:logout",
+    "models:list": "deno run --allow-read --allow-write --allow-env --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts models:list",
+    "health": "deno run --allow-read --allow-write --allow-env --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts health",
+    "route:once": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts route:once",
+    "best-route": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts best-route",
+    "agent-chat": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts agent-chat"
+  }
+}

package/templates/basic/gitignore

@@ -0,0 +1,5 @@
+.env
+out/
+router.config.local.json
+provider_config.json
+.quorum-router/

package/templates/basic/main.ts

@@ -0,0 +1,3 @@
+import { runFixtureSmoke } from "./src/fixture_smoke.ts";
+
+await runFixtureSmoke();

package/templates/basic/router.config.example.json

@@ -0,0 +1,15 @@
+{
+  "auth_mode": "auto",
+  "preferred_path": "oauth-session-wrapper-first",
+  "env_fallback": {
+    "enabled_by": "QUORUM_ROUTER_AUTH_MODE=env",
+    "usage": "private manual fallback only"
+  },
+  "runtime_boundaries": {
+    "best_route_direct": "production-ready best-answer routing",
+    "agent_chat": "experimental explicit opt-in only",
+    "production_autonomous_runtime": false,
+    "live_supabase_agent_bus_writes": false,
+    "service_role_runtime": false
+  }
+}