@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Midhun Xavier
+
+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

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="ui/brand/vibesboard-mark.png" alt="" width="64" height="64">
+</p>
+<h1 align="center">code-flow</h1>
+<p align="center">Your coding agents. One workspace.</p>
+<p align="center">
+  Bring Claude Code, Codex and Antigravity together to plan, build and review.<br>
+  Use your installed CLIs and existing logins, with work you can inspect before shipping.
+</p>
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="https://midhunxavier.github.io/code-flow/">Documentation</a> ·
+  <a href="docs/patterns.md">Workflows</a> ·
+  <a href="docs/security.md">Security</a>
+</p>
 
-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.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/run-dark.png">
+  <img src="docs/images/run-light.png" alt="Code Flow run with the task, agent activity, verification evidence and review actions. Captured from the local app using demo agents." width="100%">
+</picture>
+
+*Screenshots show the current local app with deterministic demo agents. They do not represent real provider output or a production verification result.*
+
+## Quickstart
+
+The preview adds a one-command launcher: **`npx @midhunxavier/code-flow@preview`**. It starts Code Flow locally and opens your browser. npm and download commands become available when the preview is published; see [installation options](docs/installation.md) for macOS, Linux, Windows through WSL2, npm, Homebrew and the macOS DMG. [Preview downloads](https://github.com/midhunxavier/code-flow/releases).
+
+To run from source today:
+
+Install **Node.js 22.13+**, **Git 2.38+**, and at least one supported CLI: `claude`, `codex` or `agy`. Sign in through the CLI before starting. Additional [ACP agents](docs/acp-agents.md) can be connected in Settings.
+
+```bash
+git clone https://github.com/midhunxavier/code-flow.git
+cd code-flow
+npm ci
+npm start
+```
+
+Open [localhost:4317](http://localhost:4317), or use the owner link printed in the terminal if sign-in is required.
+
+1. Choose a repository and describe the outcome you want.
+2. Pick a workflow and its agents. Set a check command such as `npm test`.
+3. Select **Start run**. Review any plan or question that needs your input.
+4. Inspect the result and its evidence, then review, merge or open a pull request.
+
+Results live on branches such as `codeflow/<run>/build` in separate Git worktrees. The [first-run guide](docs/getting-started.md) explains context, permissions and model settings.
+
+**Inbox** and **Scheduling** are in the sidebar. **New run → Template library** groups task starters and saved configurations. Open **Repository tools** from a project; use **Settings → Connections** for remote work and sharing.
+
+## A workspace for the whole task
+
+| You want to… | Use… |
+| --- | --- |
+| Build a feature with an independent review | [Plan → Build → Review](docs/patterns.md) |
+| Let a coordinator propose a team and task graph | [Auto team](docs/auto-team.md), with plan approval and bounded execution |
+| Fix failing tests, compare solutions or explore a design | [Loop, race, test-first and debate workflows](docs/patterns.md) |
+| Inspect files, changes, terminals and app previews | The [run workspace and side panel](docs/runs.md) |
+| See what needs a decision across projects | The [review inbox](docs/review-inbox.md) |
+| Run scheduled work or revisit it from another device | [Automations and remote access](docs/automations.md) |
+| Work with teammates or a remote machine | [Team collaboration](docs/team-collaboration.md) and [SSH projects](docs/ssh-projects.md) |
+
+Code Flow shows checks, independent review and fail-to-pass evidence separately. Finished work can still be unverified; the [verification guide](docs/verification.md) explains the distinction. Publishing remains an explicit workflow action.
+
+## Choose how the agents work
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/composer-dark.png">
+  <img src="docs/images/composer-light.png" alt="Code Flow composer with a task, workflow selection, agents and run options, using demo data." width="100%">
+</picture>
+
+| Workflow | Flow | Good for |
+| --- | --- | --- |
+| **Plan → Build → Review** | Plan, implement, review, repair | Features and bug fixes |
+| **Loop until green** | Change, check, repeat | A failing test or build |
+| **Best-of-N race** | Parallel candidates, blind judging | Exploring alternative implementations |
+| **Debate → Synthesize → Build** | Proposals, critique, synthesis, optional implementation | Design decisions |
+| **Supervisor → Workers** | Subtasks, separate branches, integration | Work that splits cleanly |
+| **Test-first** | Failing tests, implementation, verification | Precisely specified behavior |
+| **Review council** | Independent reviews, evidence, ranked findings | Reviewing a change |
+| **Auto team** | Proposed team, dependency graph, bounded adaptation | Delegating workflow design |
+
+Assign providers, models and effort per role. Auto team availability and its default selection follow the current rollout state; see [Auto team](docs/auto-team.md). [Project missions](docs/project-teams.md) are a separate preview for recurring repository work.
+
+## Your CLIs, your machine
+
+| Provider | How Code Flow runs it | Authentication |
+| --- | --- | --- |
+| Claude Code | `claude -p` | The CLI's own login |
+| Codex | `codex app-server` or `codex exec` | `codex login` |
+| Antigravity | `agy -p` | The CLI's own login |
+| ACP connections | Saved executable and ACP arguments | The connected CLI's authentication |
+
+Code Flow delegates authentication to the CLIs. Provider access, model availability and usage limits depend on your account and CLI configuration. It does not extract or reuse OAuth tokens. Repository checks execute code; choose suitable permissions and isolation for the repository. Read the [security and execution boundaries](docs/security.md).
+
+## Documentation, wherever you work
+
+Open **Application menu → Help & documentation** or find it in the command palette. The bundled docs at [localhost:4317/docs/](http://localhost:4317/docs/) include search, page navigation and an **Ask code-flow** chat side panel that answers using your installed CLI and the guides. [How local help works](docs/help.md).
+
+The same docs can be hosted on GitHub Pages, with the local app's typography, colors and light/dark themes. The static site provides search and reading with no companion controls. CLI chat runs in the local app, keeping the conversation while you browse guides.
+
+```bash
+npm run docs:preview  # build and preview the static site at 127.0.0.1:4319
+npm run build:docs    # produces dist/docs for GitHub Pages
+```
+
+See [publishing and maintaining the docs](docs/documentation.md) for repository setup, screenshots and the deployment workflow. The complete [documentation library](docs/README.md) covers configuration, project memory, remote workers, shared accounts, integrations, APIs and maintenance.
+
+## Development
+
+```bash
+npm run dev          # localhost:4318, fake agents, no provider quota
+npm run typecheck
+npm test
+npm run test:e2e     # browser acceptance tests; requires Chrome
+```
+
+To prepare the npm preview and macOS DMG, see the [release guide](docs/releasing.md).
+
+The [development guide](docs/architecture.md) covers the source layout, adapter and workflow contracts, and tests. Engineering plans and evaluation records are grouped separately in the docs library.
+
+## License
+
+[MIT](LICENSE). Bundled Inter fonts are distributed under the [SIL Open Font License 1.1](ui/fonts/OFL-1.1.txt).

package/bin/codeflow.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import "../scripts/check-node.mjs";
+import { launch } from "./launcher.mjs";
+
+launch().catch((error) => {
+  console.error(`Code Flow: ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/launcher.mjs

@@ -0,0 +1,127 @@
+import { execFile, spawn } from "node:child_process";
+import { readFile, access } from "node:fs/promises";
+import { homedir, release } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const root = new URL("../", import.meta.url);
+const usage = `Code Flow preview — your coding agents, one workspace.
+
+Usage: codeflow [start] [--port NUMBER] [--no-open]
+       codeflow client <command> [arguments]
+       codeflow --version
+
+Starts a local server and opens your browser. Keep this terminal open;
+press Ctrl+C to stop. Settings and history live in ~/.codeflow.
+
+  --port NUMBER  Use a different local port (default: PORT or 4317)
+  --no-open      Print the sign-in link without opening a browser
+  -h, --help     Show this help
+  -v, --version  Show the installed version
+
+Requires Node.js 22.13+, Git 2.38+, and a signed-in agent CLI.
+Windows: run inside WSL2 with your repository and CLIs installed there.
+Set CODEFLOW_HOME to use a separate data directory.
+`;
+
+export function parseOptions(args, env = process.env) {
+  const options = { open: true, port: env.PORT || "4317" };
+  const rest = args[0] === "start" ? args.slice(1) : [...args];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--no-open") options.open = false;
+    else if (rest[i] === "--port") options.port = rest[++i];
+    else throw new Error(`Unknown option: ${rest[i]}. Run codeflow --help.`);
+  }
+  if (!/^\d+$/.test(options.port ?? "") || Number(options.port) < 1 || Number(options.port) > 65534)
+    throw new Error("Choose an integer port from 1 to 65534 with --port.");
+  return { ...options, port: String(Number(options.port)) };
+}
+
+export function browserCommand(url, platform = process.platform, wsl = /microsoft/i.test(release())) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" || parsed.hostname !== "localhost" || parsed.username || parsed.password)
+    throw new Error("The browser link must be a local Code Flow HTTP URL.");
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "linux" && wsl) {
+    // Encoded PowerShell avoids cmd.exe/shell interpretation of the owner link.
+    const command = `Start-Process -FilePath '${url.replaceAll("'", "''")}'`;
+    return ["powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(command, "utf16le").toString("base64")]];
+  }
+  return ["xdg-open", [url]];
+}
+
+export async function openBrowser(url) {
+  const [command, args] = browserCommand(url);
+  await promisify(execFile)(command, args, { timeout: 10_000, windowsHide: true });
+}
+
+export async function launch(args = process.argv.slice(2)) {
+  if (args.length === 1 && ["-h", "--help", "help"].includes(args[0])) {
+    console.log(usage);
+    return;
+  }
+  if (args.length === 1 && ["-v", "--version"].includes(args[0])) {
+    console.log(JSON.parse(await readFile(new URL("package.json", root), "utf8")).version);
+    return;
+  }
+  if (process.platform === "win32") throw new Error("This preview runs on macOS and Linux. On Windows, use WSL2 and install Node, Git and your agent CLIs inside WSL.");
+  if (args[0] === "client") {
+    const client = spawn(process.execPath, [fileURLToPath(new URL("scripts/codeflow.mjs", root)), ...args.slice(1)], { stdio: "inherit" });
+    await supervise(client);
+    return;
+  }
+  const options = parseOptions(args);
+  const server = fileURLToPath(new URL("src/server.js", root));
+  await access(server).catch(() => { throw new Error("The release files are missing. From a source checkout, run npm run package:npm, then node dist/npm/bin/codeflow.mjs."); });
+  const child = spawn(process.execPath, [server], {
+    cwd: homedir(),
+    env: { ...process.env, ...(process.env.CODEFLOW_HOME ? { CODEFLOW_HOME: resolve(process.env.CODEFLOW_HOME) } : {}), PORT: options.port, CODEFLOW_LAUNCHER: "1" },
+    stdio: ["inherit", "inherit", "inherit", "ipc"],
+  });
+  let announced = false;
+  child.on("message", (message) => {
+    if (announced || message?.type !== "codeflow-ready" || typeof message.url !== "string") return;
+    announced = true;
+    if (process.env.CODEFLOW_DESKTOP === "1") console.log(`CODEFLOW_READY ${JSON.stringify({ url: message.url })}`);
+    if (options.open) void openBrowser(message.url).catch(() => {
+      console.error("Could not open a browser automatically. Open the sign-in link printed above.");
+    });
+  });
+  console.log("Starting Code Flow preview… Press Ctrl+C to stop.");
+  await supervise(child, process.env.CODEFLOW_DESKTOP === "1");
+}
+
+async function supervise(child, watchParent = false) {
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  let stopping = false;
+  const stop = (signal) => {
+    if (stopping) return;
+    stopping = true;
+    child.kill(signal);
+  };
+  const handlers = signals.map((signal) => {
+    const handler = () => stop(signal);
+    process.on(signal, handler);
+    return [signal, handler];
+  });
+  const disconnected = () => stop("SIGTERM");
+  process.once("disconnect", disconnected);
+  const parentPid = process.ppid;
+  const parentWatch = watchParent ? setInterval(() => {
+    if (process.ppid !== parentPid) stop("SIGTERM");
+  }, 1000).unref() : undefined;
+  try {
+    await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => {
+        process.exitCode = code ?? (stopping ? 0 : signal === "SIGINT" ? 130 : 1);
+        resolve();
+      });
+    });
+  } finally {
+    clearInterval(parentWatch);
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+    process.off("disconnect", disconnected);
+  }
+}