constella 0.1.0

package/drizzle/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1781826259088,
+      "tag": "0000_regular_nightshade",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1782163410060,
+      "tag": "0001_mixed_zombie",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.mjs

@@ -0,0 +1,16 @@
+// Plain-JS config (NOT .ts): the compiled distribution ships this under the user's `node_modules`, and
+// Node refuses to strip TypeScript types for files under `node_modules` ("Stripping types is currently
+// unsupported …"). `drizzle-kit migrate` loads this at first run, so it must be loadable without any
+// TypeScript tooling. `out` + `schema` are relative to the dir `drizzle-kit` runs in.
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/db/schema.ts",
+  out: "./drizzle",
+  dialect: "sqlite",
+  dbCredentials: {
+    url: process.env.DATABASE_URL ?? "file:./.constella/constella.db",
+  },
+  verbose: true,
+  strict: true,
+});

package/next.config.mjs

@@ -0,0 +1,18 @@
+// Plain-JS config (NOT .ts) on purpose: `next start` re-reads this at runtime, and the compiled
+// distribution installs `dependencies` only — `typescript` isn't present for end users, so a .ts
+// config would fail to load. JSDoc keeps editor types without a runtime TypeScript dependency.
+
+/** @type {import("next").NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  // Heavy/native packages Next must NOT bundle — loaded from node_modules at runtime.
+  serverExternalPackages: ["better-sqlite3", "@playwright/test", "playwright-core", "playwright", "chromium-bidi"],
+  typedRoutes: true,
+  // NOTE: `output: "standalone"` was removed. Its NFT tracer aborts on the dev-server manager's
+  // runtime fs/spawn operations ("whole project traced unintentionally"), and its chdir into
+  // `.next/standalone/` forked a separate DB. Plain `next start` serves assets + auto-loads `.env`
+  // from the project root — simpler and correct for local prod. The npm package instead ships the
+  // prebuilt `.next` directly (see package.json "files"), which is self-contained enough.
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "constella",
+  "version": "0.1.0",
+  "description": "Constella — run autonomous AI agent-companies locally: real claude/codex agents, Goals → Specs → Issues → Plans, local models, GitHub & Telegram, all from one cosmic control plane.",
+  "//name": "Unscoped so `npx constella` works. If the name is taken on npm, fall back to `@constella/cli` (then commands become `npx @constella/cli`).",
+  "license": "MIT",
+  "author": "Gabriel Silva <gabrielluizoliveirasilva724@gmail.com>",
+  "homepage": "https://github.com/gabriel7silva/constella#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gabriel7silva/constella.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gabriel7silva/constella/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "autonomous-agents",
+    "ai-agents",
+    "claude",
+    "codex",
+    "llm",
+    "local-models",
+    "llama.cpp",
+    "rag",
+    "nextjs",
+    "self-hosted",
+    "cli"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "//files": "Ships the COMPILED build (.next) + generated migrations (drizzle) + the launcher — NOT src/. End users get a compiled, minified runtime, never the source. next.config is .mjs so `next start` needs no TypeScript at runtime (devDeps aren't installed for end users).",
+  "files": [
+    ".next",
+    "bin",
+    "scripts",
+    "skills",
+    "docs",
+    "drizzle",
+    "next.config.mjs",
+    "drizzle.config.mjs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "dev:all": "node scripts/dev-all.mjs",
+    "build": "next build --webpack",
+    "start": "node scripts/start-all.mjs",
+    "start:web": "next start",
+    "lint": "eslint .",
+    "lint:i18n": "eslint src/components src/app --max-warnings 0",
+    "parity": "node scripts/i18n-parity.mjs",
+    "typecheck": "tsc --noEmit",
+    "validate": "npm run typecheck && npm run parity && npm run build",
+    "update": "node bin/constella.mjs update",
+    "clean": "node scripts/clean-repo.mjs",
+    "prepublishOnly": "drizzle-kit generate --config drizzle.config.mjs && npm run validate",
+    "prepack": "node scripts/trim-next.mjs",
+    "db:dir": "node -e \"require('fs').mkdirSync('.constella',{recursive:true})\"",
+    "db:generate": "drizzle-kit generate --config drizzle.config.mjs",
+    "predb:migrate": "npm run db:dir",
+    "db:migrate": "drizzle-kit migrate --config drizzle.config.mjs",
+    "predb:push": "npm run db:dir",
+    "db:push": "drizzle-kit push --config drizzle.config.mjs",
+    "db:studio": "drizzle-kit studio --config drizzle.config.mjs",
+    "predb:seed": "npm run db:dir",
+    "db:seed": "tsx src/db/seed.ts",
+    "db:migrate-fs": "tsx src/db/migrate-fs.ts",
+    "db:defake-models": "tsx src/db/defake-models.ts",
+    "db:reset-state": "tsx src/db/reset-state.ts",
+    "db:repair-fs": "tsx src/db/repair-fs.ts",
+    "db:nuke": "node -e \"const fs=require('fs'),os=require('os'),p=require('path');fs.rmSync('.constella',{recursive:true,force:true});fs.rmSync(p.join(process.env.CONSTELLA_HOME||p.join(os.homedir(),'.constella'),'organizations'),{recursive:true,force:true})\"",
+    "db:reset": "npm run db:nuke && npm run db:migrate",
+    "db:reset-demo": "npm run db:nuke && npm run db:migrate && npm run db:seed && npm run db:repair-fs",
+    "worker": "node --env-file=.env bin/worker.mjs",
+    "constella": "node bin/constella.mjs"
+  },
+  "bin": {
+    "constella": "bin/constella.mjs"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.61.0",
+    "@simplewebauthn/browser": "^13.3.0",
+    "@simplewebauthn/server": "^13.3.1",
+    "adm-zip": "^0.5.17",
+    "archiver": "^8.0.0",
+    "better-auth": "^1.6.19",
+    "better-sqlite3": "^11.10.0",
+    "chokidar": "^5.0.0",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-orm": "^0.45.2",
+    "next": "^16.2.9",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.1",
+    "@types/adm-zip": "^0.5.8",
+    "@types/archiver": "^8.0.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.19.21",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^10.5.0",
+    "eslint-plugin-react": "^7.37.5",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.1",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.61.1"
+  },
+  "//pnpm.overrides": "Force patched transitive build-tooling across the tree. postcss: Next bundles 8.4.31 (GHSA: XSS via unescaped </style>). esbuild: the vulnerable 0.18.20 (GHSA-67mh-4wv8-2f99, dev-server CORS) is pulled only by drizzle-kit's legacy @esbuild-kit/core-utils config loader — drizzle-kit's own work already uses esbuild 0.25.x, so bumping the legacy loader to >=0.25.0 patches the advisory; the loader's transform/build API usage is stable across 0.18→0.25.",
+  "pnpm": {
+    "overrides": {
+      "postcss@<8.5.10": ">=8.5.10",
+      "esbuild@<0.25.0": ">=0.25.0"
+    }
+  }
+}

package/scripts/clean-repo.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Remove dead/scratch artifacts from the repo root before commit/publish. Idempotent + safe:
+// only touches a known pattern set, never source/config. Run: `npm run clean`.
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = process.cwd();
+const EXACT = new Set(["Constella App.html", "extracted_design_system.css", "tsconfig.tsbuildinfo"]);
+const matches = (name) =>
+  EXACT.has(name) || /^temp_.*\.(jsx?|tsx?|html|css)$/i.test(name);
+
+let removed = 0;
+for (const name of readdirSync(ROOT)) {
+  if (!matches(name)) continue;
+  const p = join(ROOT, name);
+  try {
+    if (statSync(p).isFile()) { rmSync(p, { force: true }); console.log("removed", name); removed++; }
+  } catch { /* skip */ }
+}
+console.log(removed ? `\nClean: removed ${removed} artifact(s).` : "Clean: nothing to remove.");

package/scripts/dev-all.mjs

@@ -0,0 +1,46 @@
+// Launches `next dev` (web) AND the background worker together for LOCAL DEVELOPMENT, so inbound
+// Telegram messages, the cron tick and the filesystem sync watcher run in dev too. `next dev` on its
+// own starts only the web server — without the worker the Telegram bot is never polled (you send a
+// message and nothing happens). Mirrors scripts/start-all.mjs but for dev (next dev instead of next
+// start, with a longer worker warm-up since next dev compiles on first request).
+//
+// Run it with `npm run dev:all`. Dependency-free: spawns both as child processes, forwards their
+// output, and shuts both down together when either dies or on Ctrl-C.
+import { spawn } from "node:child_process";
+
+// Running from source = DEVELOPER mode (run-mode picker + Config chips), same as start-all.
+if (!process.env.CONSTELLA_PUBLIC) process.env.CONSTELLA_DEV = "1";
+
+const procs = [];
+let shuttingDown = false;
+
+function shutdown(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const { p } of procs) { try { p.kill(); } catch { /* already gone */ } }
+  process.exit(code);
+}
+
+function run(name, args, extraEnv) {
+  const p = spawn(process.execPath, args, {
+    stdio: ["ignore", "inherit", "inherit"],
+    env: { ...process.env, ...extraEnv },
+  });
+  p.on("exit", (code) => {
+    console.log(`[${name}] exited (${code}) — shutting down the other process too.`);
+    shutdown(code ?? 1);
+  });
+  p.on("error", (e) => { console.error(`[${name}] failed to start:`, e.message); shutdown(1); });
+  procs.push({ name, p });
+}
+
+process.on("SIGINT", () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));
+
+console.log("Constella (dev) → next dev + worker (Telegram poll · cron tick · file watcher).");
+// Web (dev) first — next dev loads .env on its own.
+run("web", ["node_modules/next/dist/bin/next", "dev"]);
+// Worker after a longer warm-up than start-all (next dev binds + compiles lazily). Plain Node needs
+// --env-file to read .env; the worker self-retries until the dev server answers, so the delay is just
+// to avoid a burst of "connection refused" logs on the very first ticks.
+setTimeout(() => run("worker", ["--env-file=.env", "bin/worker.mjs"]), 4000);

package/scripts/i18n-parity.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * i18n parity guard. The `en` dict is the source of truth; `pt` is the runtime layer.
+ * A missing `pt` key silently falls back to English (i18n.ts: `pt[key] ?? en[key] ?? key`),
+ * so drift is invisible at runtime. This check fails CI when the two dicts diverge.
+ *
+ * Dependency-free on purpose: it parses src/lib/i18n.ts as text (the dicts are module-local
+ * `const`s, not exported), so it runs under plain `node` with no build step.
+ *
+ * Usage: node scripts/i18n-parity.mjs   (wired as `pnpm parity` / part of `pnpm validate`)
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const src = readFileSync(join(root, "src/lib/i18n.ts"), "utf8");
+
+/** Slice the body of a `const <name>: Dict = { ... };` block and return its quoted keys. */
+function keysOf(name, endMarker) {
+  const start = src.indexOf(`const ${name}: Dict = {`);
+  if (start === -1) throw new Error(`Could not find \`const ${name}: Dict = {\` in i18n.ts`);
+  const end = src.indexOf(endMarker, start);
+  if (end === -1) throw new Error(`Could not find end marker \`${endMarker}\` after \`${name}\``);
+  const body = src.slice(start, end);
+  const keys = new Set();
+  const re = /^\s*"([^"]+)"\s*:/gm; // matches `  "some.key":` — comment lines (// …) never match
+  let m;
+  while ((m = re.exec(body))) keys.add(m[1]);
+  return keys;
+}
+
+const en = keysOf("en", "const pt: Dict = {");
+const pt = keysOf("pt", "const DICTS:");
+
+const missingInPt = [...en].filter((k) => !pt.has(k)).sort();
+const extraInPt = [...pt].filter((k) => !en.has(k)).sort();
+
+console.log(`i18n parity: en=${en.size} keys, pt=${pt.size} keys`);
+
+let failed = false;
+if (missingInPt.length) {
+  failed = true;
+  console.error(`\n✗ ${missingInPt.length} key(s) in EN but MISSING in PT (would silently fall back to English):`);
+  for (const k of missingInPt) console.error(`    ${k}`);
+}
+if (extraInPt.length) {
+  failed = true;
+  console.error(`\n✗ ${extraInPt.length} key(s) in PT but MISSING in EN (orphaned PT key):`);
+  for (const k of extraInPt) console.error(`    ${k}`);
+}
+
+if (failed) {
+  console.error(`\nFix: every key must exist in BOTH the en and pt dicts in src/lib/i18n.ts.`);
+  process.exit(1);
+}
+console.log("✓ EN and PT dictionaries are in parity.");

package/scripts/mcp-server.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Constella MCP server — exposes the public REST API (v1) as MCP tools so an AI client
+// (Claude Desktop / Cursor / any MCP host) can drive Constella. Authenticates to Constella with a
+// Personal Access Token. Self-contained: a hand-rolled JSON-RPC-over-stdio MCP server using only
+// Node built-ins + global fetch (Node 18+), so it ships in the compiled distribution with no deps.
+//
+// Configure in an MCP client (env):
+//   CONSTELLA_PAT       cn_… token from Profile → Personal access tokens (REQUIRED; use a write token
+//                       to allow approve/execution/new-work, a read token for read-only)
+//   CONSTELLA_BASE_URL  default http://localhost:3000
+//   CONSTELLA_ORG       optional orgId (multi-org users) → sent as X-Constella-Org
+//
+// This is the OUTBOUND-to-Constella direction (an AI drives Constella). Constella's own agents
+// consuming EXTERNAL MCPs is the other direction and works via the claude CLI's ~/.claude config.
+
+import { createInterface } from "node:readline";
+
+const PAT = process.env.CONSTELLA_PAT || "";
+const BASE = (process.env.CONSTELLA_BASE_URL || "http://localhost:3000").replace(/\/+$/, "");
+const ORG = process.env.CONSTELLA_ORG || "";
+const SERVER_INFO = { name: "constella", version: "1.0.0" };
+
+// ---- tools: thin maps onto the REST routes. `build(args)` → { method, path, body? }. ----
+const S = (props = {}, required = []) => ({ type: "object", properties: props, required });
+const TOOLS = [
+  { name: "constella_status", description: "Counts of goals, issues, tasks and the plan state.", inputSchema: S(), build: () => ({ method: "GET", path: "/status" }) },
+  { name: "constella_review", description: "A readable summary of the plan, issues, tasks and next steps.", inputSchema: S(), build: () => ({ method: "GET", path: "/review" }) },
+  { name: "constella_goals", description: "List goals.", inputSchema: S(), build: () => ({ method: "GET", path: "/goals" }) },
+  { name: "constella_issues", description: "List issues.", inputSchema: S(), build: () => ({ method: "GET", path: "/issues" }) },
+  { name: "constella_tasks", description: "List tasks.", inputSchema: S(), build: () => ({ method: "GET", path: "/tasks" }) },
+  { name: "constella_specs", description: "List specs.", inputSchema: S(), build: () => ({ method: "GET", path: "/specs" }) },
+  { name: "constella_kb", description: "Ask the Knowledge Base a question.", inputSchema: S({ q: { type: "string", description: "the question" } }, ["q"]), build: (a) => ({ method: "POST", path: "/kb", body: { q: a.q } }) },
+  { name: "constella_approve_plan", description: "Approve the pending plan and queue tasks (write scope).", inputSchema: S(), build: () => ({ method: "POST", path: "/plan/approve" }) },
+  { name: "constella_reject_plan", description: "Send the plan back to the CEO for revision (write scope).", inputSchema: S({ reason: { type: "string", description: "why" } }), build: (a) => ({ method: "POST", path: "/plan/reject", body: { reason: a.reason } }) },
+  { name: "constella_set_execution", description: "Turn 24/7 autonomous execution on or off (write scope).", inputSchema: S({ on: { type: "boolean" } }, ["on"]), build: (a) => ({ method: "POST", path: "/execution", body: { on: a.on !== false } }) },
+  { name: "constella_new_work", description: "Start a new unit of work — the CEO drafts specs/issues for approval (write scope).", inputSchema: S({ brief: { type: "string" }, title: { type: "string" } }, ["brief"]), build: (a) => ({ method: "POST", path: "/work", body: { brief: a.brief, title: a.title } }) },
+  { name: "constella_cancel_goal", description: "Cancel a goal by id (write scope).", inputSchema: S({ id: { type: "string" } }, ["id"]), build: (a) => ({ method: "POST", path: `/goals/${encodeURIComponent(a.id)}/cancel` }) },
+  { name: "constella_archive_goal", description: "Archive a goal by id (write scope).", inputSchema: S({ id: { type: "string" } }, ["id"]), build: (a) => ({ method: "POST", path: `/goals/${encodeURIComponent(a.id)}/archive` }) },
+];
+const TOOL_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+
+async function callApi(method, path, body) {
+  if (!PAT) return { ok: false, error: "CONSTELLA_PAT is not set" };
+  const headers = { authorization: `Bearer ${PAT}` };
+  if (ORG) headers["x-constella-org"] = ORG;
+  if (body !== undefined) headers["content-type"] = "application/json";
+  try {
+    const res = await fetch(`${BASE}/api/v1${path}`, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(30_000) });
+    const json = await res.json().catch(() => ({ ok: false, error: `non-JSON response (http ${res.status})` }));
+    return json;
+  } catch (e) {
+    return { ok: false, error: String(e?.message ?? e) };
+  }
+}
+
+// ---- JSON-RPC over stdio (newline-delimited) ----
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
+function result(id, r) { send({ jsonrpc: "2.0", id, result: r }); }
+function error(id, code, message) { send({ jsonrpc: "2.0", id, error: { code, message } }); }
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  const isRequest = id !== undefined && id !== null;
+  switch (method) {
+    case "initialize":
+      return result(id, {
+        protocolVersion: params?.protocolVersion || "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: SERVER_INFO,
+      });
+    case "notifications/initialized":
+      return; // notification, no reply
+    case "ping":
+      return result(id, {});
+    case "tools/list":
+      return result(id, { tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })) });
+    case "tools/call": {
+      const tool = TOOL_BY_NAME.get(params?.name);
+      if (!tool) return error(id, -32602, `unknown tool: ${params?.name}`);
+      const req = tool.build(params?.arguments ?? {});
+      const data = await callApi(req.method, req.path, req.body);
+      const text = JSON.stringify(data, null, 2);
+      return result(id, { content: [{ type: "text", text }], isError: data && data.ok === false });
+    }
+    default:
+      if (isRequest) return error(id, -32601, `method not found: ${method}`);
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+  const s = line.trim();
+  if (!s) return;
+  let msg;
+  try { msg = JSON.parse(s); } catch { return; } // ignore non-JSON lines
+  Promise.resolve(handle(msg)).catch((e) => {
+    if (msg && msg.id !== undefined && msg.id !== null) error(msg.id, -32603, String(e?.message ?? e));
+  });
+});
+rl.on("close", () => process.exit(0));

package/scripts/postbuild.mjs

@@ -0,0 +1,11 @@
+// After `next build` with `output: "standalone"`, Next emits a self-contained server at
+// `.next/standalone/server.js` but does NOT copy the client assets (`.next/static`) or
+// `public/` into it. Without this, `node .next/standalone/server.js` serves HTML whose
+// JS/CSS 404 → screens render unstyled / don't hydrate / navigation breaks. Copy them in.
+import { cpSync, existsSync } from "node:fs";
+
+const SB = ".next/standalone";
+let copied = [];
+if (existsSync(".next/static")) { cpSync(".next/static", `${SB}/.next/static`, { recursive: true }); copied.push(".next/static"); }
+if (existsSync("public")) { cpSync("public", `${SB}/public`, { recursive: true }); copied.push("public"); }
+console.log(`[postbuild] standalone assets copied: ${copied.join(", ") || "(none found)"}`);

package/scripts/publish-public.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Push the CLEAN, COMPILED-distribution tree to the PUBLIC repo (`public` remote = gabriel7silva/constella).
+ *
+ * The public repo ships the *product*, not the source: docs, the launcher (bin/), runtime scripts,
+ * the native skills library, config, and the generated DB migrations (drizzle/) — but **NO `src/`**
+ * and **no committed build** (the compiled `.next` reaches users through the npm tarball, not git).
+ * This script builds that filtered tree in a temporary git index, secret-scans exactly what it will
+ * publish, and REFUSES on any finding. It never runs automatically.
+ *
+ *   node scripts/publish-public.mjs            # scan only (dry run)
+ *   node scripts/publish-public.mjs --push     # scan, then force-push the clean tree to `public main`
+ */
+import { execSync } from "node:child_process";
+import { readFileSync, statSync, mkdtempSync, existsSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PUSH = process.argv.includes("--push");
+
+// Tracked paths that must NEVER reach the public repo (the whole point: no source, no test config).
+const EXCLUDE = ["src", "playwright.config.ts", "e2e", "tests"];
+
+// Mirror of src/server/git-scan.ts — sensitive filenames + high-confidence inline secret patterns.
+const SENSITIVE_FILE = /(^|\/)(\.env(\.[\w.-]+)?|id_[rd]sa\w*|.*\.(pem|key|p12|pfx|keystore|jks|ppk|asc)|credentials?\.json|service[-_]?account[\w.-]*\.json|.*\.(sql|dump|bak|sqlite3?|db)|npm-debug\.log|.*\.local)$/i;
+const ALLOW_FILE = /(\.env\.(example|sample|template|dist)|\.env-example)$/i;
+// Legit source that the SENSITIVE_FILE regex over-matches: Drizzle migrations are DDL, not DB dumps.
+const ALLOW_PATH = /^drizzle\/.*\.sql$/i;
+// Obvious placeholder credentials in doc/example connection strings — not real secrets.
+const PLACEHOLDER = /^(user|username|admin|root|pass|password|pwd|secret|example|changeme|x{3,}|your|host|localhost|db|name|app|<)/i;
+const SECRETS = [
+  ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
+  ["GitHub token", /\bgh[posru]_[A-Za-z0-9]{30,}\b/],
+  ["GitHub fine-grained PAT", /\bgithub_pat_[A-Za-z0-9_]{40,}\b/],
+  ["OpenAI/Anthropic key", /\bsk-[A-Za-z0-9_-]{20,}\b/],
+  ["Google API key", /\bAIza[0-9A-Za-z_-]{30,}\b/],
+  ["Slack token", /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/],
+  ["Private key block", /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ["JWT", /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}\b/],
+  // DB URL with creds — only flag when the user:pass aren't obvious placeholders.
+  ["DB URL with creds", /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp):\/\/([^\s:@/]+):([^\s:@/]+)@/, (m) => !PLACEHOLDER.test(m[1]) && !PLACEHOLDER.test(m[2])],
+  ["Telegram bot token", /\b\d{6,}:[A-Za-z0-9_-]{35,}\b/],
+];
+const TEXT = /\.(m?[jt]sx?|json|md|css|ya?ml|toml|sh|env|txt|html?)$/i;
+
+const isExcluded = (f) => EXCLUDE.some((p) => f === p || f.startsWith(p + "/"));
+
+// 1) Ensure the generated migrations exist (the public repo ships them; they build a fresh end-user
+//    DB via `drizzle-kit migrate`). Generated from src/db/schema.ts, which exists in this dev tree.
+if (!existsSync("drizzle") || readdirSync("drizzle").filter((f) => f.endsWith(".sql")).length === 0) {
+  console.log("• Generating DB migrations (drizzle/) from the schema…");
+  execSync("npx drizzle-kit generate --config drizzle.config.mjs", { stdio: "inherit" });
+}
+
+// 2) Compute exactly the file list that will be published: tracked files minus EXCLUDE, plus the
+//    on-disk drizzle/ migrations (gitignored in this dev repo, force-added to the public tree).
+const tracked = execSync("git ls-files", { encoding: "utf8" }).split("\n").map((s) => s.trim()).filter(Boolean);
+// drizzle/ is gitignored in the dev repo, so list it straight off disk (cross-platform fs walk) — these
+// generated migrations are force-added into the public tree below.
+function walkDir(dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = `${dir}/${e.name}`;
+    if (e.isDirectory()) out.push(...walkDir(p));
+    else out.push(p);
+  }
+  return out;
+}
+const drizzleFiles = existsSync("drizzle") ? walkDir("drizzle") : [];
+const publishFiles = [...new Set([...tracked.filter((f) => !isExcluded(f)), ...drizzleFiles])];
+
+// 3) Secret-scan exactly that set.
+const findings = [];
+for (const f of publishFiles) {
+  if (SENSITIVE_FILE.test(f) && !ALLOW_FILE.test(f) && !ALLOW_PATH.test(f)) { findings.push(`${f}: sensitive file`); continue; }
+  if (!TEXT.test(f)) continue;
+  let body;
+  try { if (statSync(f).size > 512 * 1024) continue; body = readFileSync(f, "utf8"); } catch { continue; }
+  for (const [name, re, valid] of SECRETS) {
+    const m = body.match(re);
+    if (m && (!valid || valid(m))) { findings.push(`${f}: ${name}`); break; }
+  }
+}
+// Belt-and-suspenders: make sure no src/ slipped into the publish set.
+const leaked = publishFiles.filter((f) => f === "src" || f.startsWith("src/"));
+if (leaked.length) findings.push(`src/ leaked into the public tree (${leaked.length} file(s)) — aborting`);
+
+if (findings.length) {
+  console.error(`\n✖ Refusing to publish — ${findings.length} potential secret/sensitive/source finding(s):`);
+  for (const x of findings.slice(0, 30)) console.error("  - " + x);
+  process.exit(1);
+}
+console.log(`✓ Clean: ${publishFiles.length} files to publish (no src/, no secrets). Migrations: ${publishFiles.filter((f) => f.startsWith("drizzle/")).length} file(s).`);
+
+if (!PUSH) {
+  console.log("\nDry run. To publish the clean compiled tree to the public repo, run:");
+  console.log("  node scripts/publish-public.mjs --push");
+  process.exit(0);
+}
+
+// 4) Build the filtered tree in a TEMP git index (HEAD minus EXCLUDE, plus drizzle/), then push it
+//    as a fresh root commit. Force-push = the public repo is a clean mirror, not a shared history.
+console.log("\nStaging the clean public tree…");
+const TMP_INDEX = join(mkdtempSync(join(tmpdir(), "constella-public-")), "index");
+const env = { ...process.env, GIT_INDEX_FILE: TMP_INDEX, GIT_TERMINAL_PROMPT: "0" };
+execSync("git read-tree HEAD", { env, stdio: "inherit" });
+for (const p of EXCLUDE) execSync(`git rm -r --cached --ignore-unmatch -- "${p}"`, { env, stdio: "ignore" });
+if (existsSync("drizzle")) execSync("git add -f -- drizzle", { env, stdio: "inherit" });
+const tree = execSync("git write-tree", { env }).toString().trim();
+const commit = execSync(`git commit-tree ${tree} -m "Constella — compiled distribution (docs, launcher, migrations; no source)"`, { env }).toString().trim();
+
+console.log(`Pushing clean tree (${commit.slice(0, 9)}) to \`public\` (gabriel7silva/constella)…`);
+// Fully-qualify the destination ref: pushing a bare commit object to `main` fails on an empty remote
+// (git can't guess the ref). `refs/heads/main` creates/overwrites the branch deterministically.
+execSync(`git push -f public ${commit}:refs/heads/main`, { stdio: "inherit", env });
+console.log("✓ Pushed. The npm tarball (with the prebuilt .next) is published separately via `npm publish`.");

package/scripts/start-all.mjs

@@ -0,0 +1,45 @@
+// Launches the web server (next start) AND the background worker together, so a single
+// `pnpm start` runs everything. The worker hosts the Telegram bot poll, cron tick, and the
+// filesystem sync watcher — without it, inbound Telegram messages are never fetched. Keeping
+// them in one command means the operator can't forget to start the worker separately.
+//
+// Dependency-free (no `concurrently`): spawns both as child processes, forwards their output,
+// and shuts both down together when either dies or on Ctrl-C.
+import { spawn } from "node:child_process";
+
+// Running from source via `pnpm start` is DEVELOPER mode — show the run-mode picker + Config chips.
+// (The published `constella` CLI sets CONSTELLA_PUBLIC=1 instead, which hides them.)
+if (!process.env.CONSTELLA_PUBLIC) process.env.CONSTELLA_DEV = "1";
+
+const procs = [];
+let shuttingDown = false;
+
+function shutdown(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const { p } of procs) { try { p.kill(); } catch { /* already gone */ } }
+  process.exit(code);
+}
+
+function run(name, args, extraEnv) {
+  const p = spawn(process.execPath, args, {
+    stdio: ["ignore", "inherit", "inherit"],
+    env: { ...process.env, ...extraEnv },
+  });
+  p.on("exit", (code) => {
+    console.log(`[${name}] exited (${code}) — shutting down the other process too.`);
+    shutdown(code ?? 1);
+  });
+  p.on("error", (e) => { console.error(`[${name}] failed to start:`, e.message); shutdown(1); });
+  procs.push({ name, p });
+}
+
+process.on("SIGINT", () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));
+
+console.log("Constella → starting web server + worker (single command).");
+// Web server first. `next start` loads .env on its own.
+run("web", ["node_modules/next/dist/bin/next", "start"]);
+// Worker shortly after so the server is usually up first (the worker also self-retries if not).
+// Plain Node needs --env-file to read .env (next does it internally).
+setTimeout(() => run("worker", ["--env-file=.env", "bin/worker.mjs"]), 1500);

package/scripts/trim-next.mjs

@@ -0,0 +1,23 @@
+// Runs on `prepack` (npm pack / npm publish): strip the parts of `.next` that `next start` does NOT
+// need, so the published tarball ships only the production runtime. The dev-server artifacts
+// (.next/dev — turbopack output + a multi-GB development log), the build cache, and trace files are
+// regenerated locally by `next dev`/`next build` and must never travel to end users.
+//
+// npm's `files` allowlist re-includes the whole `.next` dir and overrides nested .npmignore rules, so
+// deleting these on disk before packing is the reliable way to keep the package small + clean.
+import { rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const NEXT = join(process.cwd(), ".next");
+if (!existsSync(NEXT)) {
+  console.error("• trim-next: no .next/ — nothing to trim (skipping).");
+  process.exit(0);
+}
+for (const sub of ["dev", "cache", "trace"]) {
+  const p = join(NEXT, sub);
+  if (existsSync(p)) {
+    rmSync(p, { recursive: true, force: true });
+    console.error(`• trim-next: removed .next/${sub}`);
+  }
+}
+console.error("• trim-next: .next trimmed to the production runtime.");