ensemble-review 0.0.0-stage → 1.0.36

package/LICENSE

@@ -0,0 +1,129 @@
+# Ensemble License 1.0
+
+_Formerly the Limn License 1.0. Only the name changed; the terms are the same._
+
+Copyright 2026 Alex Wakeman
+
+## 1. Acceptance
+
+In order to get any license under these terms, you must agree to them as both
+strict obligations and conditions to all your licenses.
+
+## 2. Copyright License
+
+The licensor grants you a copyright license for the software to do everything
+you might do with the software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose. However, you may only distribute the
+software according to section 5 (Distribution License) and make changes or new
+works based on the software according to section 6 (Changes and New Works
+License).
+
+## 3. Permitted Purposes
+
+Any purpose is a permitted purpose for:
+
+(a) an individual using the software for themselves; and
+
+(b) an organization in which no more than three (3) individuals use the
+software, counting the organization together with all of its affiliates.
+
+Any other use, including use within an organization in which more than three
+(3) individuals use the software, is not a permitted purpose. That use needs a
+separate commercial license from the licensor, which you can ask for through
+the contact form at https://ensemble.ac/contact.
+
+## 4. No Competing Use
+
+No purpose is a permitted purpose if it is a competing use. A competing use is
+making the software, or any product or service substantially similar to it or
+built from it, available to others as a commercial product or service, whether
+as installable software, a hosted service or any other form.
+
+## 5. Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of
+the software. Your license to distribute covers distributing the software with
+changes and new works permitted by section 6 (Changes and New Works License).
+
+## 6. Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new
+works based on the software for any permitted purpose.
+
+## 7. Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms, together with the copyright notice above.
+Anyone who gets a copy from you gets it under these terms only, and no other
+terms. If you modify the software, you must include in any modified copies of
+the software a prominent notice stating that you have modified the software.
+
+## 8. Patent License
+
+The licensor grants you a patent license for the software that covers patent
+claims the licensor can license, or becomes able to license, that you would
+infringe by using the software for a permitted purpose.
+
+## 9. Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do
+not limit them.
+
+## 10. No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to
+anyone else, or prevent the licensor from granting licenses to anyone else.
+These terms do not imply any other licenses. The licensor will not convert
+these terms, or any version of the software released under them, to the MIT
+License or to any other license by the passing of time.
+
+## 11. Patent Defense
+
+If you make any written claim that the software infringes or contributes to
+infringement of any patent, your patent license for the software granted under
+these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+## 12. Violations
+
+The first time you are notified in writing that you have violated any of these
+terms, or done anything with the software not covered by your licenses, your
+licenses can nonetheless continue if you come into full compliance with these
+terms, and take practical steps to correct past violations, within 32 days of
+receiving notice. Otherwise, all your licenses end immediately.
+
+## 13. No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.***
+
+## 14. Definitions
+
+The **licensor** is Alex Wakeman, the individual offering these terms, and the
+**software** is the software the licensor makes available under these terms,
+including any version of it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+
+An **organization** includes any company, firm, partnership, government body,
+charity, team or other group of people working together, and **affiliates** of
+an organization are all organizations that have control over, are under the
+control of, or are under common control with it. **Control** means ownership of
+substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct
+or indirect.
+
+An individual **uses** the software within an organization if they run it, or
+work with it directly, in the course of their work for, or on behalf of, that
+organization.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# Ensemble (`ensemble-review`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **local dashboard for tracking your team's GitHub PR activity** across
+multiple repositories. Run it on your machine, see at a glance who's doing what,
+which PRs are stalled, which review threads are sitting untouched, and what needs
+_your_ attention right now — all rendered as an interactive timeline.
+
+There's no hosted backend, no database server, and no stored credentials. It
+authenticates by shelling out to your already-logged-in `gh` CLI, syncs activity
+into a local SQLite file, and serves the dashboard from a single local process.
+
+**100% free.** Every feature, no paid tier, no sign-up (see [License](#license)
+for the one limit, on large organisations).
+
+> **Renamed.** This package used to be `limn-review` (and before that
+> `pierre-review`). The command is now `ensemble`; both old packages only forward
+> to this one, and say so. On first start, an existing `~/.limn` (or
+> `~/.pierre-review`) is moved to `~/.ensemble` — your database, settings and
+> clones come with it. If `~/.ensemble` already exists, nothing is moved.
+> Settings named `LIMN_…` still work; their new names start `ENSEMBLE_…`.
+
+## Quick start
+
+```bash
+npx ensemble-review
+```
+
+This starts the server, prints a local URL, and opens your browser to it.
+
+Or install globally and use the short command:
+
+```bash
+npm install -g ensemble-review
+ensemble
+```
+
+## Review and fix with Claude — free, on your own Claude
+
+Claude Review (a code review of any PR, follow-ups, a check against a user
+story you paste, and a chat about the review) and AI Fix are free. By default
+they use your local Claude Code login: if you are signed in to Claude Code,
+there is nothing to set up. An Anthropic API key is the alternative: set
+`ANTHROPIC_API_KEY`. Ensemble stores no key and charges nothing for it. They can
+run on Codex instead (below).
+
+- **Claude and Codex work out of the box.** The first time Ensemble starts, it
+  downloads both in the background (Claude about 110 MB, Codex about 360 MB
+  unpacked) into `~/.ensemble/ai-runtime`, at the exact versions this release was
+  tested with. The package itself stays small. Signing in is the only step.
+  `ensemble ai install codex` runs the same download by hand;
+  `ENSEMBLE_AI_AUTO_INSTALL=false` skips the automatic one.
+- Set `ENSEMBLE_CLAUDE_PATH` to the `claude` you already have to use it instead of
+  the bundled copy (the download then skips it).
+- The reviewer reads code. It cannot edit files, run commands or reach the web.
+- The fixer edits files. It has no shell, and builds and tests nothing.
+- Nothing is posted or pushed until you press the button.
+- **Use my API keys first** (Settings → AI), or `ENSEMBLE_AI_USE_API_KEY=true`, uses
+  `ANTHROPIC_API_KEY` even when you are signed in to Claude Code.
+- `ENSEMBLE_AI_DISABLED=true` turns every AI feature off.
+
+### Codex instead of Claude
+
+Every AI feature can run on Codex, on your own ChatGPT plan. One provider runs
+everything at a time.
+
+Codex comes with Ensemble. Sign in from **Settings → AI**, or:
+
+```bash
+ensemble ai login codex     # sign in with ChatGPT (add --device-auth on a headless machine)
+```
+
+Ensemble keeps its own
+Codex sign-in in `~/.ensemble/codex`; your `~/.codex` is not read or changed. Codex
+with an OpenAI API key is not available yet.
+
+- Pick the provider in **Settings → AI**, or set `ENSEMBLE_AI_PROVIDER` to
+  `claude`, `codex` or `auto` (the default: Claude when both are signed in,
+  Codex when only Codex is).
+- Each run is labelled with the provider and model that ran it.
+- `ensemble ai status` shows whether Codex is set up and signed in.
+- `ensemble ai logout codex` signs Ensemble's Codex out.
+
+## Prerequisites
+
+- **Node.js ≥ 20** (with npm).
+- **GitHub CLI**, installed and authenticated. Install it from
+  <https://cli.github.com>, then run:
+
+  ```bash
+  gh auth login
+  ```
+
+  `ensemble` reads your team's activity using your `gh` token. It pre-checks this on
+  startup and exits with a friendly message if `gh` is missing or not authed.
+
+> **Native module note:** `ensemble-review` depends on `better-sqlite3`, a native
+> addon. npm installs a prebuilt binary for common platforms; if none matches your
+> Node/OS/arch, npm compiles it from source on install (needs a C++ toolchain —
+> Xcode Command Line Tools on macOS, `build-essential` + Python on Linux, MSVC
+> build tools on Windows).
+
+## Usage
+
+```
+ensemble [options]
+ensemble status [options]
+ensemble ai install
+```
+
+| Flag | Env | Default | Description |
+|------|-----|---------|-------------|
+| `--no-open` | `NO_OPEN` | — | Don't open the browser on start. |
+| `--port <n>` | `PORT` | `4000` | Port to listen on. |
+| `--db <path>` | `DATABASE_URL` | `~/.ensemble/pierre-review.sqlite` | SQLite DB path. |
+| — | `ENSEMBLE_DATA_DIR` | `~/.ensemble` | Where Ensemble keeps its data. |
+| — | `PERSIST_BODIES` | `false` | Store full comment/PR text in the DB instead of loading it on demand (larger DB, but PR detail works fully offline). |
+| `-h`, `--help` | — | — | Show usage. |
+
+Examples:
+
+```bash
+ensemble --port 4123 --no-open
+ensemble --db /tmp/ensemble.sqlite
+```
+
+## Data directory
+
+Everything Ensemble keeps lives in `~/.ensemble`:
+
+```
+~/.ensemble/pierre-review.sqlite   the database
+~/.ensemble/clones/                git clones Claude Review and AI Fix read
+~/.ensemble/ai-runtime/            the AI runtime, once you set AI up
+```
+
+The directory is created automatically. Override it with `ENSEMBLE_DATA_DIR`, or
+just the database with `--db` / `DATABASE_URL`. No team activity data or
+credentials are ever sent anywhere — everything stays on your machine.
+
+## How it works
+
+Once running, open the printed URL (default <http://localhost:4000>). Add the
+repositories you want to watch from the in-app picker; the app syncs their PR
+activity (full backfill on first sync, incremental every few minutes thereafter)
+into your local DB and renders it as a timeline.
+
+Repos are grouped into **Workspaces**, and the selected workspace is the scope for
+everything — the feed, the timeline, the metrics, the review-bot settings. Every
+repo belongs to exactly one workspace; new ones land in **Default** (renameable, not
+deletable), and you can create more and move repos between them from *Manage repos &
+workspaces*.
+
+To keep the database small and backfills fast, bulky text — PR/comment/review
+bodies and diff hunks — isn't stored; it's fetched from GitHub (using your `gh`
+token) the first time you open a PR and cached in your browser, so re-opening an
+unchanged PR is instant and offline. Set `PERSIST_BODIES=true` to store that text
+locally instead — a larger database, but PR detail then works fully offline.
+
+## License
+
+Source-available under the **Ensemble License 1.0** — see [LICENSE](./LICENSE).
+Ensemble is free for individuals, and for organisations where no more than 3 people
+use it (affiliates count together). More users than that need a licence — ask
+through the [contact form](https://ensemble.ac/contact?topic=licence). You may
+**not** offer Ensemble, or a product built from it, as a competing commercial
+product or service.
+The AI runtime Ensemble downloads on first use is Anthropic's, under Anthropic's own
+terms; it is not part of this package.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,21 @@
+# Third-party notices
+
+Ensemble includes material from the projects below. Each is used under the licence shown.
+
+## Material Icon Theme
+
+The file-type icons in the Changes tab (`apps/frontend/src/components/FileTypeIcons.tsx`) are
+copied from Material Icon Theme by Material Extensions, npm `material-icon-theme@5.39.0`.
+
+Source: https://github.com/material-extensions/vscode-material-icon-theme
+
+```
+The MIT License (MIT)
+Copyright (c) 2025 Material Extensions
+
+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/dist/ai/active-runtime.js

@@ -0,0 +1,11 @@
+// THE ACTIVE PROVIDER'S DOWNLOAD — is the program the next run needs installed? Claude's runs need the
+// Claude SDK download (`getAiRuntimeStatus`); Codex's need the Codex program (`getCodexRuntimeStatus`,
+// installed WITH the shared download, so its zod is there too). `/api/me`'s top-level `ai.runtime`
+// and the background sweepers' gate (`agenticRunReady`) both ask this, so a Codex machine is never
+// held back for a missing Claude program, nor a Claude one for a missing Codex.
+import { getAiRuntimeStatus, getCodexRuntimeStatus } from './runtime.js';
+import { activeProviderId } from './provider-setting.js';
+export function activeRuntimeStatus() {
+    return activeProviderId() === 'codex' ? getCodexRuntimeStatus() : getAiRuntimeStatus();
+}
+//# sourceMappingURL=active-runtime.js.map

package/dist/ai/agent-isolation.js

@@ -0,0 +1,51 @@
+// AGENT ISOLATION — every Agent SDK run in this app sees ONLY the tools it registered itself.
+//
+// ⚠ MEASURED (2026-10-10): a run on the reader's ambient Claude Code login, with `tools: []`,
+// `settingSources: []` and `bypassPermissions`, still lists the ACCOUNT'S claude.ai CONNECTORS
+// (`mcp__claude_ai_Claude_Docs__create/update/delete/export`, …) a few seconds after start — they
+// connect after `system/init`, so the init message shows none. A trial agent wrote a report into the
+// user's Claude Docs unprompted. Claude Review reads PR text strangers write, so a prompt injection
+// could create, edit or delete documents in the reader's claude.ai account. `strictMcpConfig: true`
+// removes them (measured: 8 connector tools → 0); the PreToolUse hook below is the backstop that
+// refuses any `mcp__` tool whose server the run did not register, and its deny holds under
+// bypassPermissions (the path guard relies on the same property).
+//
+// EVERY `query({ options })` spreads `ISOLATED_MCP` and adds `ownToolsOnlyHook(<its server names>)`
+// to `PreToolUse` — pinned by agent-isolation.test.ts, which reads every call site.
+export const ISOLATED_MCP = { strictMcpConfig: true };
+// NO SESSION FILES. By default the Claude Code CLI saves every run's transcript under
+// `~/.claude/projects/<encoded cwd>/`. Limn never resumes an SDK session, and its runs work in
+// temporary worktrees, so each run left a new directory there (~2,000 / 3.5 GB measured on one
+// machine). EVERY `query({ options })` spreads this too; `ai/runtime.ts` also forces it on the tapped
+// `query`, so a call site that forgets it still writes nothing. Old litter: ai/session-litter.ts.
+export const NO_SESSION_FILES = { persistSession: false };
+/** The MCP server a tool name belongs to (`mcp__<server>__<tool>`), or null for a built-in tool. */
+export function mcpServerOf(toolName) {
+    if (!toolName.startsWith('mcp__'))
+        return null;
+    const rest = toolName.slice('mcp__'.length);
+    const cut = rest.indexOf('__');
+    return cut < 0 ? rest : rest.slice(0, cut);
+}
+/** True when `toolName` is an MCP tool from a server this run did not register. */
+export function isForeignMcpTool(toolName, ownServers) {
+    const server = mcpServerOf(toolName);
+    return server != null && !ownServers.includes(server);
+}
+/** One SDK PreToolUse matcher entry refusing every MCP tool outside `ownServers`. */
+export function ownToolsOnlyHook(ownServers) {
+    return {
+        hooks: [
+            async (input) => input.hook_event_name === 'PreToolUse' && isForeignMcpTool(input.tool_name ?? '', ownServers)
+                ? {
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'deny',
+                        permissionDecisionReason: `${input.tool_name} is not available in this run.`,
+                    },
+                }
+                : { continue: true },
+        ],
+    };
+}
+//# sourceMappingURL=agent-isolation.js.map

package/dist/ai/auto-install.js

@@ -0,0 +1,81 @@
+// THE FIRST-BOOT AI DOWNLOAD — Claude and Codex come with Limn, without a click.
+//
+// The SDKs and the Codex CLI stay OUT of the npm manifest (a fast `npx limn-review`; the guardrails in
+// scripts/build-release.mjs are unchanged), so on a boot that finds either runtime missing, stale or
+// without its native program, Limn downloads what is missing in the background — the same
+// single-flight `installAiRuntime` that `limn ai install codex` and the SPA's Retry run. ⚠ A Claude
+// that is already ready is never fetched again or swapped (`['codex']` alone: the existing install
+// adding Codex). After it, signing in to each provider is the only step.
+//
+// ⚠ IT NEVER DELAYS THE SERVER. `index.ts` calls `startAiAutoInstall` AFTER `listen`, with `void`;
+// nothing awaits it. `/api/me` reads `runtime: 'installing'` (and the current step in
+// `runtimeMessage`) the moment it starts, because `install()` claims its slot synchronously.
+//
+// ⚠ A FAILURE IS RETRIED ONCE, a few minutes later (a laptop waking on a dead network), then left for
+// the reader's Retry, `limn ai install`, or the next boot — never a loop. A Codex-only failure is
+// Codex's alone (ai/runtime.ts): Claude stays set up.
+//
+// Skipped when AI is off (LIMN_AI_DISABLED=true) or LIMN_AI_AUTO_INSTALL=false.
+import { config } from '../config.js';
+import { getAiRuntimeStatus, getCodexRuntimeStatus, installAiRuntime, } from './runtime.js';
+/** How long after a failed automatic download the one automatic retry waits. */
+export const AUTO_INSTALL_RETRY_MS = 3 * 60_000;
+/**
+ * The providers a download must bring, or null when nothing is missing. ['codex'] alone over a ready
+ * Claude downloads Codex only (ai/runtime.ts): an existing install neither fetches nor swaps Claude.
+ */
+export function autoInstallProviders(claude, codex) {
+    // Already running (a `limn ai install` started by the same process cannot be, but a Retry can).
+    if (claude.runtime === 'installing' || codex.runtime === 'installing')
+        return null;
+    const needClaude = claude.runtime !== 'ready';
+    const needCodex = codex.runtime !== 'ready';
+    if (!needClaude && !needCodex)
+        return null;
+    if (!needCodex)
+        return ['claude'];
+    return needClaude ? ['claude', 'codex'] : ['codex'];
+}
+/** The testable body: one attempt, and on failure ONE scheduled retry. */
+export function runAutoInstall(deps, attempt = 1) {
+    if (!deps.enabled)
+        return;
+    const providers = autoInstallProviders(deps.claude(), deps.codex());
+    if (!providers)
+        return;
+    const names = providers.map((p) => (p === 'codex' ? 'Codex' : 'Claude')).join(' and ');
+    deps.log.info(`ai: downloading ${names} in the background`);
+    void deps
+        .install(providers)
+        .then((r) => {
+        if (r.ok) {
+            deps.log.info(`ai: ${names} downloaded — sign in to use ${providers.length > 1 ? 'them' : 'it'}`);
+            return;
+        }
+        deps.log.warn(`ai: the download did not finish: ${r.message}`);
+        if (attempt === 1)
+            deps.schedule(() => runAutoInstall(deps, 2), AUTO_INSTALL_RETRY_MS);
+    })
+        .catch(() => {
+        /* installAiRuntime never throws; belt and braces for the boot */
+    });
+}
+/** Start the first-boot download (a no-op when nothing is missing). Never throws, never awaited. */
+export function startAiAutoInstall(log) {
+    try {
+        runAutoInstall({
+            enabled: config.aiEnabled && config.aiAutoInstall,
+            claude: getAiRuntimeStatus,
+            codex: getCodexRuntimeStatus,
+            install: (providers) => installAiRuntime(undefined, { providers }),
+            schedule: (fn, ms) => {
+                setTimeout(fn, ms).unref?.();
+            },
+            log,
+        });
+    }
+    catch (err) {
+        log.warn(`ai: the background download could not start: ${err.message}`);
+    }
+}
+//# sourceMappingURL=auto-install.js.map